How do I integrate HMS to my game using HMS Unity Plugin 2.0? — Part 1
Introduction
Hello everybody! In this article, I will be introducing the brand new version of HMS Unity Plugin version 2.0! Yes, it is out and it will make your life much easier, even when compared to the previous version of the plugin 1.2.0!
The HMS Unity Plugin is a tool that helps developers to quickly integrate Huawei Mobile Services (HMS) to their games in Unity without worrying about the boilerplate codes that has to be written in the background. All the necessary backend code is dealt with for you, and all you have to do is to focus on your own game and HMS features.
In this article, I will be using my own game as a scenario to quickly explain the steps required for you to integrate many HMS kits with a few clicks and/or lines of code. To be specific, I am using the version 2.0.1 for this article.
Before diving into details, you can check out here, the plugin’s GitHub page, if you think you are experienced enough with the plugin and that you do not require any specific scenario to start using the plugin. Readme already has general details about how to start using the kit.
Please note that I developed this game and used the plugin for this article series in Unity editor version 2019.4.18f1. For 2020 version of the Unity, you should be able to do the same steps with the same version of the plugin. For 2018 or other versions, please check out here, the releases page, for the corresponding plugin release (if any) and for the latest updates.
I further suggest that you download the latest version of the plugin for the corresponding Unity version, although I have used version 2.0.1 here. Details on how to use/import the plugin will follow, but I wanted to let you know beforehand.
Full source code with all the kits integrated can be found here, the repo for this reference game.
About My Game
Let me quickly introduce my game to you, so that during the phases of integration, it makes sense to you why I am implementing the plugin features in this way.
It is a hypercasual game called Raining Apocalypse, where you simply escape from the rain! You are the cool fire character that run horizontally. The more rains you run away from the more points you score. So, as you can see, very simple and affordable to implement. :)
I developed this game using a Udemy course and the source code is not completely written by me. However, we will not focus on the game development parts anyway, we will integrate the HMS kits to our game to increase our chances of survival in the game industry.
It consists of two scenes: main menu scene and game scene. It has several scripts attached, some of which we will use in the integration.
I will integrate “Account Kit, Ads Kit, Push Kit, Game Service, IAP, Analytics Kit and Crash Kit” to my game. For this part 1 of the article, I will talk about Account Kit, Ads Kit, Analytics Kit, Crash Kit and Push Kit. Game Service and IAP will be talked about in Part 2 of the series.
It looks too many and seems to cost the developers a lot of time, but not with Plugin 2.0 and you will see how, if you read on. :)
Development Process
To start using the plugin you must go here, the readme of the official GitHub page of the plugin and complete the phases, starting from the phase called “1 — Register your app at Huawei Developer” to “4 — Connect your game with any HMS Kit”, so that the AppGallery Connect side of your application is done. HMS requires AppGallery Connect configurations to correctly work with the in-game features you want to implement.
I will, from now on, assume that you have completed the first 3 phases and now ready to implement the 4th phase and onwards. You can continue using the following phases for the kits as well; but here, I will merge them with a real life scenario, i.e. my game, so that you can better understand how those features would work in your own game. By this way, you can decide easily where to put those methods in your own game.
Now, assuming that you are done with the AGC side, let’s get to the coding. I will talk about AGC side a bit in some of the kits I explain as well.
Coding Phase
Let’s start with Account Kit and Ads Kit. The main menu scene of my game has a logo and a play button to start the game. What I want to add is a banner ad to the bottom and also to implement sign in functionality. By this way, I will show 320*50 (or any size you choose) ads to the users at the beginning of my game. Also, since I do not want to proceed to the game without the user signed in, I will implement the sign in functionality so that when I try to use the other kits in-game, I do not have to deal with sign in process again.
To start using any kit, you must import the plugin (downloaded from the releases page) and click on the kits that you want to use. Mine currently looks like this:
Clicking them will add a manager to your game screen. They are coming with DontDestroyOnLoad() function by default, so you do not have to worry about carrying it over to the other scenes. However, it is strongly suggested that you do this in the outermost scene, so this carry-over process is smooth and bug-free. I do it in my main menu scene because it comes first, and the game scene opens the second.
I have my own manager script called EnesGameManager.cs to control the behaviour of kits and game-specific functionalities.
Before every use of managers, you must call them with .Instance because the plugin uses the singleton pattern to implement the managers. That is also helpful in changing scenes all you like because the plugin will delete the unnecessary copies of the manager and will make sure that you only work with the one and the only instance. This will save you from coding overhead and wrong instance usage.
Account Kit
After ticking the box, HMSAccountManager is added to the scene. All you have to do is to add the below line to anywhere you choose as per your own game logic. You can place it inside a new method to add a button click to the play button, for example.
HMSAccountManager.Instance.SignIn();Important Note: If you plan to use GameService, it has automatic sign-in functionality. Instead of using Account Kit, you can just enable the GameService, tick the box (“Initialize on Start”) under Game Service tab and your app will do auto sign-in every time the user opens the app. If this is not what you want, use of Account Kit is required and GameService function should be manually initialized.
All of the details about this can be found in the part 2 of the article, which is here.
GameService is dependent on AccountKit anyway, so even if you do not use Account Kit to login (which is perfectly fine), GameService login system will use it for you in the background.
Ads Kit — Part 1
Ads Kit has three types of advertisements as of the publish date of this article. If you are reading this later than the publish date, some new types of ads might have been added to the plugin, so I would suggest you to check them out as well. Ads Kit, right now, supports “Banner Ads, Interstitial Ads and Rewarded Ads”. I will be using banner ads and interstitial ads in my game.
To enable the ads you want to use, just tick the corresponding boxes. That is very easy. Also, if you want to use test ads like me, check that box too. It will replace any ID you enter above with the test ID, so you can test the layout of ads in your game for example, before getting a real ID. If you have the ID already you can uncheck the test ID box, enter the ID and click save. Replacing does not mean you will lose the already-entered ID, but you will see the test ads from now on, until you uncheck the box.
The default size is 320*50 and the default position is POSITION_BOTTOM. If you require different sizes and positions, you can only change them inside of manager script in this version of the plugin. You can check Huawei -> Scripts -> Ads folder to reach the manager script and configure as per your needs.
If you build now, you should get your ads like below. You can work on alignment yourself to match the elements.
There is one more thing left. This banner ad will show in every screen you will be opening from now on. For my case, it will be present on my game screen if I press play button; which is not what I want. Thus, in the game scene, I will call below one line code to hide the ads because it is the behaviour I want. You can call this code piece in any Start() function of the active object scripts.
HMSAdsKitManager.Instance.HideBannerAd();As you can see, no initialization etc. required. HMSAdsKitManager will remain on your other scenes and can be directly called by using its instance.
If you do not want the banner ads in your main screen and want it in other scenes, you can always use the above hide code to hide it in the beginning and call the below show method to show it anywhere you like.
HMSAdsKitManager.Instance.ShowBannerAd();That’s it for banner ads. Very short, very simple.
Ads Kit — Part 2
I also want to use interstitial ads in my app. The scenario I want to use it is when the user dies, before showing a lose screen to retry, I want to show interstitial ads, unless the user has purchased the remove_ads product (which I will talk about in IAP section).
To implement this, I need to put the code into the proper place in my own game code. There is no one way to do it. If you have a similar scenario like me, you can also follow my code and find your corresponding code and implement your own interstitial ads logic.
In my player script, I have the TakeDamage function where I control the damage inflicted on my player. It also controls the death, when the health drops below zero. So here, when the player dies, I call interstitial ad show code to display the user interstitial ads. The if check can be ignored now and will be talked about in IAP section.
Basically, just calling the ShowInterstitialAd() function is enough to show the ads. Once the player dies, it will be shown immediately and after the user closes it, the lose panel will be shown.
Like most kits, there are callbacks that you may want to implement. For example, interstitial ads has “OnInterstitialAdClosed” callback that can be implemented. If you want to control what will happen right after the user closes the interstitial ad, you can implement this by using the code below in start function.
void Start()
{
//...
HMSAdsKitManager.Instance.OnInterstitialAdClosed = OnInterstitialAdClosed;
}The second “OnInterstitialAdClosed” is the name of the function that you will be defining. So it can be changed to whatever you like. You can generate a new function manually by using the name you defined in the right hand side of the equal sign. However, since some callbacks come with parameters from the plugin, it is recommended that you show the potential fixes and generate one from there automatically. By this way, you will also which parameters, if any, will be returned from the callback. You can check other methods in all kits by typing “HMS…Manager.Instance.On…” and see which callbacks are supported.
Analytics Kit
In the code above, you can see an AnalyticsManager instance is used. That is the whole implementation of analytics kit I have in my game. After I enabled it from the Kit Settings menu in the Unity Editor, I can call HMSAnalyticsManager however I like, as in the other managers. Here, my scenario for Analytics Kit is sending the score of the player to the server to see how much score people are achieving. You can use, just as I did, SendEventWithBundle function to send whatever items need to be sent as your game logic requires. The function requires an EventID, key and a value to be sent that can be of type string or int. That’s it and now you can check if the parameters are coming to AGC console by checking the tab “Real-time Overview”
Some of the events are predefined. As long as you enable Analytics Kit, they will be sent to the console anyway, even if you do not code anything in your game. If you cannot see your own custom event here, I would suggest adding that even manually from the Events tab close to bottom in AGC console. You can also look for support from the Huawei Developer website and/or forum.
Crash Kit
Crash Kit, when clicked, is automatically implemented thanks to the plugin. You should see crash reports in AGC Console, if any crash appears. You can also deliberately cause your app to crush, but how to do so is outside the scope of this article.
Push Kit
Push Kit, like Crash Kit, is also automatically enabled when you tick the box besides it. It is complete and ready to use. Simple as that, you should go to AGC Console, create a notification and you should receive notification depending on the time you set.
Tips & Tricks
- Do not forget to get the agconnect-services.json file from the AGC and paste it to the StreamingAssets folder. The folder must be placed inside Assets folder of the Unity files.
- In case any method or code piece that I shared will not work and you face any compiler complaints, make sure that you have imported the right libraries with “using” keyword. Make sure you imported them to use them smoothly. Normally, IntelliSense should suggest what to import, however, in case you do not use it, here is the list that you may need. For any usage of the plugin, first line below is required and the other lines are needed for the most functions related to the kits.
using HmsPlugin;using HuaweiMobileServices.Game;using HuaweiMobileServices.Utils;using HuaweiMobileServices.Id;using HuaweiMobileServices.IAP;
- It is very normal that your game is different and the scenario you wanted this kits may differ from mine. That’s why, I always talked about how my need/scenario for the kit and then implemented it. If you are having trouble how to convert this to your own game logic, try to understand what I did and where, so you can implement the similar functionality where you want it to be in your own game.
- Please make sure that your package name ends with either .huawei or with .HUAWEI if you want to use IAP in your game. If you used another package name, please change it for AppGallery. Otherwise, IAP will not work. IAP will be talked about in part 3 but I wanted to warn here, so if you do not have an existing game yet, you can start off right.
Conclusion
In this article, we integrated many kits to our game. This was not just a “to integrate, do this” kind of article, but rather I tried to show you a real game scenario, so while you are applying this article to your game, you will hopefully have a better understanding. With Plugin 2.0, the speed of integration has increased dramatically, reduced down from days to perhaps hours depending on the complexity of your app.
I hope that this article has been helpful for you. You can always ask questions below, if you have anything unanswered in your mind.
Remaining two kits will be talked about here, in the part 2.
See you there!
References
- HMS Unity Plugin 2.0 Branch (Github Page)
- Documentation of every single kit in Huawei Docs (Links are present in the GitHub readme)
