[Huawei Developers] Freemind R:
Hi everyone,

In this article, we will convert a GMS project which has Location, Map and Analytics APIs to GMS+HMS project step by step. In order to do that, I prepared an initial project which has those APIs for you to download.

You can find and download the GitHub link of the initial project in this link. This project contains the main features of the Google Location, Map, Analytics APIs. We will install HMS toolkit plugin to Android Studio, configure the project with App Gallery Connect, and finally convert it step by step.

Installing the HMS toolkit plugin

We start by installing the HMS toolkit plugin in Android Studio. For this in the Android Studio window, you should open settings by navigating File -> Settings. In the marketplace, search for HMS toolkit and install the plugin.

After installing the HMS toolkit, you will be prompt that you need to restart Android Studio. Follow the instruction and restart the IDE. After restarting the IDE, you will see the HMS section in the toolbar of Andriod Studio.

Running the initial project

As it is mentioned before, the initial project has Google Location, Map and Analytics APIs. When you run the project in a GMS device, it should look like this;

As you can see in the figure, there are three activities which are for Map, Location and Analytics APIs. This initial project only works on devices with Google Mobile Services. Next step is configuring our project with Huawei Mobile Services.

Creating a New Project in AppGallery Connect

The first thing we are going to do is creating a project through the AppGallery Connect platform. Go to this link and create a developer account. Then go to the console by clicking the console button at the left top corner in the web page. Click on , then click on “My Apps”. Afterwards, you will need to create a new app by clicking the “New App” button at the left top corner. Fill the necessary parts accordingly.

After creating the app, we are going to configure our project in the AppGallery Connect. In order to do that, at the navigation window near the AppGallery Connect logo, click “My projects” section.

The project page will ask us to fill the package name section. This will also help our toolkit to automatically match between the Android Studio and AppGallery Connect.

After configuring the package name, in the “Project Settings” page, you should set your Data Storage location.

Also, we are gonna activate the APIs that we are going to convert from Google Mobile Services by opening the “Manage APIs” page. In our case, we need to activate Location Kit, Analytics Kit and Map Kit. In order to activate the Analytics kit, you should enable Analytics Kit at the “Project Overview”, in the HUAWEI Analytics section which is shown in the navigation bar on the left.

For creating a new app on AppGallery Connect, please refer to the official documentation.

Configuring the Project Using HMS toolkit- Configuration Wizard

Now we can continue to configure our project with HMS toolkit in Android Studio. When you click the HMS section, you will see the window which you can use the features of the HMS toolkit. In this article, we will use Configuration Wizard and Convertor.

We are going to use Configuration Wizard in order to configure our project, connect the project with App Gallery Connect, create a keystore.jks file, download the related agconnect-services.json file and configure the related APIs for the project.

In order to configure our project, we will need to set the fingerprint of our project. We are going to choose “Use your certificate” option and create a new fingerprint for our project as seen in the figure below.

After creating fingerprint and starting the configuration process, the configuration wizard will start analyzing and configuring our project. It will match the Android Studio project with the AppGallery project, download necessary settings, service files and configure the fingerprint in the project.

Converting the project with HMS toolkit convertor

We configured our project successfully. Next, we are going to convert our project. We will start the conversion process by selecting Convertor -> New Conversion.

Follow the conversion procedure as shown below. Select a backup directory to prevent any unexpected errors. By doing this, you will be able to restore your project to the version before the conversion

In this part, you will see the analysis of automatic conversion rate. In our case, we have a %100 auto conversion rate and we will not have to convert anything manually. Since we are going to convert our project to GMS+HMS project, we are going to select the conversion policy as “Add HMS API(HMS API First)” then we will click “Analyze” button.

After the analysis is finished, we will have an analysis report as seen in the figure below. As we can see, there are auto conversion entries as well as manual conversion. In order to solve those manual conversion entries, we are going to click “Details” in the corresponding entry and follow the procedures. In order to start the automatic conversion, we are going to select all the automatic conversion entries and click the convert button.

Auto: This item will be automatically converted.

Dummy: HMS does not support this method. The XMS Adapter encapsulates only the GMS method. You need to confirm whether to retain or delete this method in or from HMS. After the confirmation, you can start an automatic conversion.

Manual: This item requires manual conversion.

Since we selected G+H conversion, convertor added the XMS Adapter to the project, an adaption-layer code module, based on the original code for calling third-party APIs. The adapter code can call GMS APIs or HMS APIs based on the scheduling policy. The scheduling policy is determined by us. In this project, we selected the policy of “HMS APIs first”.

The XMS Adapter automatically generated by the tool schedules GMS APIs and HMS APIs and separates or decouples service code from adapter code. You only need to pay attention to services and do not need to spend much time on the differences between GMS APIs and HMS APIs.

For details about the principle, please refer to Add HMS API Policy.

After the conversion, we are synchronizing the build.gradle files and check the project whether we have any errors. Because we are developing this project in Kotlin, we encountered some getter setter errors.

In order to fix those errors, we will change the getter setter functions as we are doing in Java.

Testing the converted project with both GMS and HMS devices

After we fix all the errors in the project, now we are ready to run the project both in the GMS device and the HMS device. As it is seen in the figures below, the application is working on the HMS only device. If we run it on the GMS only devices, it will also work without any problem.

If we also check the App Debugging section of HUAWEI Analytics in the AppGallery Connect Platform, it will be seen that the Analytics kit is also working exactly how it should.

Conclusion

Migrating a complex project from GMS to HMS is very easy with HMS toolkit conversion. Thanks to XMSAdapter architecture that HMS toolkit provides, the application chooses GMS APIs or HMS APIs according to the availability of the services.

Please also refer to the official documentation of HMS toolkit: link

You can also find and download the fully converted version of the project here.

Any questions about the process, you can ask a question in https://forums.developer.huawei.com/forumPortal/en/home