HUAWEI Cordova Map Plugin in Ionic
Introduction
Hello everyone, in this article, I will show how to integrate Huawei Cordova Map Plugin to an Ionic project and how to use features of this plugin.
Pre-Installation
Configuring App Information in AppGallery Connect
Before you get started, you must register as a HUAWEI developer and complete identity verification on HUAWEI Developers.
Firstly, lets create an AppGallery Connect Project.
- Sign in to AppGallery Connect and select My projects.
- Click Add project.
3. Enter a project name and click OK.
After the project is created, the Project settings page is displayed. Before you use development capabilities provided by AppGallery Connect, you need to add an app to your project first.
- In section Project settings > General information, click Add app.
- On the Add app page, enter app information.
3. On the Project settings page, enter SHA-256 certificate fingerprint and then download the configuration file agconnect-services.json for Android platform.
We will use this file later.
A signing certificate fingerprint is used to verify the authenticity of an app when it attempts to access an HMS Core (APK) through the HMS SDK. Before using the HMS Core (APK), you must locally generate a signing certificate fingerprint and configure it in the AppGallery Connect. You can refer to 3rd and 4th steps of Generating a Signing Certificate Codelab tutorial for the certificate generation. Perform the following steps after you have generated the certificate.
Enabling Service
To use HUAWEI Map Plugin on your app, you need to enable the service if not enabled before.
- Sign in to HUAWEI Developers and click Console in the upper right corner. Go to HMS API Services > My APIs, select the project for which you want to enable HUAWEI Map Kit, and click Add API from library. The API Library page is displayed.
2. Click Map Kit.
3. On the Map Kit page, click Enable to enable HUAWEI Map Kit.
Installation
Before integrate Huawei Map plugin, make sure you have installed Node.js, npm, Cordova CLI and Ionic CLI on your computer.
- Create a new Ionic project. I used the Cordova Backend to develop the sample project but you can use also Capacitor Backend if you want.
ionic start HuaweiMapDemo blank --type=angular --cordovaTo create a new Ionic project, you can use
ionic start <name> <template> [options]command. For more details you can follow ionic start - Ionic Documentation.
2. Update the widget id property which is specified in the config.xml file. It must be same with client > package_name value of the agconnect-services.json file.
3. Go into project directory and add the android platform to the project.
cd HuaweiMapDemo
ionic cordova platform add android4. Install HMS Map plugin to the project.
ionic cordova plugin add @hmscore/cordova-plugin-hms-map5. Install Ionic Native support for HMS Map plugin.
npm install @ionic-native/core @hmscore/ionic-native-hms-map6. Copy agconnect-services.json file to <project_root>/platforms/android/app directory.
7. Add keystore(.jks) to your project’s root directory.
You can refer to 3rd and 4th steps of Generating a Signing Certificate Codelab tutorial page for generating keystore file.
8. Create a file named as build.json in project’s root directory and fill the file according to your keystore information as in example below.
{
"android": {
"debug": {
"keystore": "<keystore_file>",
"storePassword": "<keystore_password>",
"alias": "<key_alias>",
"password": "<key_password>"
},
"release": {
"keystore": "<keystore_file>",
"storePassword": "<keystore_password>",
"alias": "<key_alias>",
"password": "<key_password>"
}
}
}9. Build Ionic app to generate resource files.
ionic build10. Run the application.
ionic cordova run android --deviceProject should be compile without an error and a blank Ionic project should be opened on the device.
We successfully configured our project. We can use all functionalities of Huawei Cordova Map Plugin in our project.
Using Huawei Cordova Map Plugin
Adding Plugin to AppModule
In order to use Map Plugin in Ionic, we need to import wrapper files to app.module.ts file as a provider.
After this step, we can use plugin functions in all pages. Inject like a service and call functions.
Creating Map
In Huawei Map Plugin, map instances are linked to specific div tags. Plugin creates an android map View and it shows this view below Ionic View.
We should add a div tag with id attribute to html file of the page where we want to use the map.
Then, we should add some CSS properties. We should give width and height to map div and make ion-content’s background color transparent.
As last step, we should initialize the map.
Map should be successfully shown on the page after initialized.
Adding Marker
We can add markers to a map to identify locations and provide extra information with information windows.
After map initialized, we called addMarker function to add marker. You can configure marker options according to your case. In the sample above, we added a custom icon to marker. If you want to use default marker icon, you can delete icon property.
In addition, after marker added to map, we called setTag method of marker. We can push extra information to markers separately.
The page should look like the following.
Adding InfoWindow
Initially, infowindows of markers are empty. We can update infowindows with
- static values,
- dynamic values using marker tags.
In order to customize infowindows, we should create an html file. We can design this page as an html (add scripts, styles etc. ). getMarkerInfo function gives information of current marker. We can get our additional info with markerInfo.tag key.
I created a file named marker-info.html and saved it to assets folder.
In order to use this custom html file, We should set this file as info window adapter.
If you are using Capacitor Backend, you should pass file path with “public” instead of “www”.
The result should look like following.
Drawing on Map
Adding polygons, polylines, circles etc. is similar to marker. Just set the options and call related “add” method.
And the result is:
Event Listening
We can use on function to listen for map events. It has two parameters: event name and handler. When an event occurs, the handler is called.
You can reach all events from this address.
Page Navigation
We need to change map visibility manually on page navigations. We can use Ionic lifecycle events to handle this problem. Map visibility should be updated like:
- Create HMS map on page creation,
- Hide HMS map on map page leaving,
- Show HMS map on map page enter,
- Destroy HMS map on map page destroy.
Before creating map, HTML elements should be rendered. So, we need to use ionViewDidEnter to handle map create and show cases.
Scrolling with Map
In Ionic, we should add scroll function manually for HMS Map plugin. The content component in Ionic provides scroll events. We will use these events to handle map scrolling.
Firstly, we should activate scroll events. For each scroll event, scrollMap function will be triggered.
Then, we define the scrollMap function. Basically, calling map.scroll() function will be sufficient.
Conclusion
In this story, I have tried to clarify HMS Map Plugin with detailed examples. I hope it was easy to understand. Please state your opinions and questions in the comments section.
I have collected all examples in a project and uploaded it to GitHub. You can find it by clicking this link.
In this story, I used HMS Map version 5.1.0–300.
