Skip to main content

App Integration (Android client)

This page adds Huawei Push Kit support to your Android app. It is the same for all users (hosted or on‑prem). Apps that do not target Huawei can skip this entirely — they won't pull in any Huawei dependency.

Prerequisites: you already have agconnect-services.json and your SHA‑256 fingerprint is registered — see [AppGallery Setup](../../Push Credentials/huawei-hms.md).

1. Add the optional HMS module​

// app/build.gradle.kts
dependencies {
    implementation("com.paylisher:paylisher-sdk-android-hms:<version>")
}

The module auto‑registers its push service via manifest merge — you don't declare any <service> yourself.

2. Add the Huawei Maven repository (required)​

The HMS module's transitive dependencies (com.huawei.hms:push, com.huawei.agconnect:*) live only in Huawei's Maven repository — they are not on Google's Maven or Maven Central. Every app that uses the HMS module must declare it:

// settings.gradle.kts → dependencyResolutionManagement { repositories { ... } }
maven {
    url = uri("https://developer.huawei.com/repo/")
    content { includeGroupByRegex("com\\.huawei.*") }
}
note

FCM never needs this because Google's Maven is already present in every project. Huawei's is not.

3. Apply the AGConnect Gradle plugin​

The plugin processes agconnect-services.json at build time. The AGConnect plugin (agcp) does not publish a Gradle plugins‑DSL marker and expects the Android Gradle Plugin on the buildscript classpath, so apply it the classic way:

// Root build.gradle.kts — add a buildscript block at the top
buildscript {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://developer.huawei.com/repo/") }
    }
    dependencies {
        classpath("com.android.tools.build:gradle:<your-AGP-version>")
        classpath("com.huawei.agconnect:agcp:1.9.1.301")
    }
}

// Keep the Android Gradle Plugin OUT of the plugins { } block (it now comes from
// the buildscript classpath) and apply it without a version in the module.

Also add the Huawei Maven repo to pluginManagement { repositories { ... } } in settings.gradle.kts.

// app/build.gradle.kts — apply after the plugins { } block
apply(plugin = "com.huawei.agconnect")
tip

If you get com.android.tools.build:gradle is not set, it means AGP isn't on the buildscript classpath — add the classpath("com.android.tools.build:gradle:…") line above.

4. Add agconnect-services.json​

Place the file downloaded from AppGallery Connect in the app module root — the same directory as app/build.gradle.kts:

app/
├── build.gradle.kts
└── agconnect-services.json   ← here

5. Register the push token​

FCM tokens are fetched automatically at SDK startup. For HMS, fetch the first token after Paylisher.setup(...) — call it once (for example in your Application or first Activity):

com.paylisher.android.hms.PaylisherHms.registerToken(applicationContext)

The token is stored on the user profile as token + pushProvider = "hms", so the backend routes it to the HMS channel. Token rotations are captured automatically afterwards.

6. Runtime behaviour​

  • On a GMS device: the SDK uses FCM; HMS stays dormant.
  • On a GMS‑less Huawei device: the SDK uses HMS. The FCM setup is skipped safely (no crash).
  • The device is one or the other — a single build handles both.

What about in-app and action-based messages?​

Nothing extra. HMS delivers push, in-app, and action-based messages through the same entry point, and the shared engine routes them by message type — identical to FCM. The steps above are all you need; there is no separate in-app or action-based wiring for HMS.

// HmsMessagingService passes every message type to the shared engine:
override fun onMessageReceived(message: RemoteMessage?) {
    PaylisherPushCore.handleMessage(applicationContext, message.dataOfMap, message.messageId)
}
// → the engine routes by data["type"]: PUSH / IN-APP / ACTION-BASED — same as FCM.

The heavy lifting (rendering, dedup, WorkManager, all layout types) is shared between the FCM and HMS paths, so adding HMS is deliberately a thin "mailbox + token" layer — not a second copy of the rendering logic.

In-app has a second, transport-independent path

Engage in-app messages can also arrive via API pull (the SDK polls Engage on foreground), which does not use FCM or HMS at all — see In-App Messaging (API Pull). This means in-app messages can reach GMS‑less Huawei devices even before HMS push is set up.

In-app rendering prerequisite (both channels)

For an in-app to render, the SDK needs the current Activity. Call FcmMessagingService.setMainActivity(this) (or PaylisherPushCore.setMainActivity(this)) in your Activity's onResume(). This is provider‑agnostic — the same requirement as FCM, not specific to HMS.

Verifying without a Huawei device​

registerToken needs HMS Core, which a standard Google emulator does not have — there it logs that no token was obtained (expected, not an error). To verify real delivery without owning a device, use AppGallery Connect → Quality → Cloud Debugging (free remote Huawei devices). See Troubleshooting.

Distribution​

Huawei devices don't have Google Play; publish your app to Huawei AppGallery as well. It's the same app/codebase — just an additional store.