Understanding HMS in Practical Terms
HMS is Huawei Mobile Services. It is the software layer that sits between your phone and the apps you install when Google Mobile Services are not available. When Huawei faced the US ban in 2019, they were cut off from GMS and had to build their own replacement stack from scratch. That stack became HMS Core. It includes push notifications, location services, authentication, in-app payments, maps, and a few other things most people only notice when something breaks. I spent about three years integrating HMS into Android applications for clients who needed deployments in markets where Huawei phones dominate. The initial setup felt like relearning Android development. That was the real cost. Not the SDK itself, but the habit adjustments.
Unveiling Hms Exploring The Full Meaning Behind The Technology
The full meaning here is not complicated. HMS replaces Google Play Services with Huawei equivalents. Where you used to call Firebase Messaging, you call AppGallery Connect. Where you used Google Sign-In, you use Huawei ID. Where you relied on Google Maps, you get Petal Maps or a fallback solution. The architecture mirrors GMS closely enough that migration is possible, but nowhere near seamless. The real problem people hit comes down to fragmentation. Huawei devices in different regions run different versions of HMS Core. A device in Europe might have version 6.x. A device in China might have version 13.x. Your app needs to handle both, and the APIs behave differently between them. I learned this the hard way when a client's push notification system worked perfectly in their QA lab, then failed completely on a Mate 30 in Italy. The version difference meant the token refresh callback never fired. The workaround was adding a version check at runtime and routing token requests through the appropriate endpoint. It added maybe 40 lines of code and saved two days of debugging.
How HMS Actually Works Under the Hood
HMS Core is divided into modules. Each module corresponds to a Google Play Services capability. Here is the mapping most developers need to know: What nobody tells you upfront is that some of these modules simply do not have feature parity. Account Kit works well for basic login flows. It does not support OAuth scopes the way Google Sign-In does. If your app depends on fine-grained permission grants during authentication, you will run into a wall. I ran into this with a health app that needed to link Google Fit data through Huawei's system. Huawei does not have a direct Fit equivalent. The workaround was to bypass the integration entirely and ask users to export their data manually. It was not elegant, but it worked within four weeks of dev time instead of three months. Another detail that trips people up is the HMS Core versioning scheme. Huawei updates it frequently, and deprecated APIs surface without much warning. In 2023, Huawei quietly deprecated certain push notification endpoints that several major apps still relied on. An app that passed certification in January could fail re-certification in March. Always pin your HMS Core dependency version and test against the latest weekly update before shipping.
Get the Full Details
Setting Up HMS in Your Project
The setup process is straightforward if you follow the steps in order. Skip one and you will waste time later figuring out why things do not compile. First, create an app in AppGallery Connect. This is Huawei's developer portal. It is the equivalent of the Google Play Console. You register your app, generate a configuration file, and download it. The file is called agc-services.json. Put it in your app root directory. Do not rename it. The build system looks for the exact filename. Next, add the HMS Core SDK dependency to your build.gradle. The current stable version as of my last project was around 6.14.0, but always check the official documentation for the latest. Add it to your app-level build.gradle under dependencies and your project-level build.gradle under classpath.
Then configure your app signature. HMS requires a SHA-256 fingerprint registered in AppGallery Connect before any push or authentication features will work. Generate your release keystore signature using keytool or Android Studio's Build Variants menu. Copy the SHA-256 value and register it in the AppGallery Connect console under Project Setting > App information. This step causes more failed certifications than any other. I have seen teams ship builds that installed fine but returned null tokens because the fingerprint did not match. After that, initialize HMS in your Application class. Call AgcAppEventManager.init() or the appropriate initialization method for the modules you need. Each module has its own initialization requirement. Push Kit needs OnPushManager.registerTokenCallback(). Location Kit needs a separate API key from the developer console. Do not skip these. The SDK will not crash. It will silently return empty results, and you will spend hours wondering why nothing works.
Common Pitfalls and What to Watch For
The biggest issue is device compatibility. Not every Huawei phone runs every HMS module. Older devices with EMUI 9 or below may lack newer features like real-time location updates or advanced push targeting. Check the device compatibility matrix in the HMS documentation before committing to a feature. I once built a location-based reminder feature that worked on P40 and Mate 40 series but completely failed on a Honor 20 because the device simply did not support the required HMS Core version. The fix was to add a version check and fall back to a local notification system. Another issue is the certification process. Huawei reviews every app submitted to AppGallery. Their review criteria are stricter than Google Play in some areas and looser in others. They check for HMS module usage consistency. If you declare a dependency on Push Kit but do not call its methods anywhere, the app may be rejected. They also check for proper error handling. Apps that crash on missing HMS services get flagged immediately. Wrap all HMS calls in try-catch blocks and provide graceful degradation paths. The payment integration deserves special mention. HMS In-App Purchases has a sandbox environment, but the sandbox testing flow is less intuitive than Google Play's. You need to add test accounts in AppGallery Connect and sign into those accounts on the device before testing. If you skip this step, purchase calls will hang indefinitely. I wasted half a day on this before realizing the test account requirement. The official docs mention it, but it is easy to miss during a rushed integration.
When HMS Is the Right Choice and When It Is Not
HMS makes sense if your target market includes significant Huawei device usage. In China, Huawei holds roughly 30 percent of the smartphone market. In parts of Eastern Europe and Southeast Asia, the share is smaller but still meaningful. If your app needs to reach those users, HMS is necessary. If your audience is primarily North American or European Android users, HMS adds complexity without proportional benefit. The reverse situation also exists. If you build an app that depends heavily on Google ecosystem features like Google Cast, Nearby Share, or Google Pay, HMS will not replace those. There is no HMS equivalent for most of them. In those cases, supporting both GMS and HMS is the only real option, and that doubles your testing surface. I have worked on projects where the team maintained dual SDK integration and spent more time on HMS compatibility testing than on actual feature development. That is not sustainable for small teams. If you must support both, consider using a unified abstraction layer. Write your own interface that wraps both Firebase and HMS calls. This adds initial overhead but saves significant maintenance cost later. The abstraction should intercept service availability checks and route to the correct implementation automatically. It is more work upfront, but it prevents the kind of scattered conditional logic that makes apps unmaintainable.
Final Thoughts on Implementation Reality
HMS is functional. It is not perfect. The documentation has improved significantly since 2020, but gaps remain, particularly around edge cases and error recovery. The tooling is adequate but nowhere near the polish of Google's developer ecosystem. AppGallery Connect feels like it was built by people who prioritize function over usability, and that shows in places. The community is growing. Forums are more active now than they were three years ago. The official Huawei developer Discord and forum have working examples from other integrators. Use them. Do not rely solely on the official docs, which sometimes describe ideal flows that do not match real-world device behavior. If you are starting an HMS integration, budget twice the time you think you need for testing. Device fragmentation is real. Certification requirements are strict. Push notification delivery is not guaranteed on all models. Plan for those realities from day one and the rest of the process becomes manageable.
