Step 1 - Requirements

• A OneSignal Account - Your OneSignal App ID, available in Keys & IDs
• Huawei Platform Setup on OneSignal
• A Huawei device
  • Other Android devices and emulators not supported
• Android Studio

Step 2 - Follow the OneSignal Android SDK setup guide

2.1 Follow the OneSignal Android SDK setup guide

• Firebase / Google setup not required for app builds released to the Huawei AppGallery.

Step 3 - Huawei Configuration File (agconnect-services.json)

You can skip this step if you already have a Huawei agconnect-services.json in your Android Studio Project from setting up a different Huawei service.
3.1 From the AppGallery Connect Project List select your app.

3.2 Click on the "agconnect-services.json" button to download this file.

3.3 Place this file in your app directory in Android Studio.

Step 4 - Generating a Signing Certificate Fingerprint

You can skip this step if you already have added your SHA-256 certificate fingerprint to Huawei's dashboard for a different Huawei service.

4.1 From your Android Studio go to View > Tool Windows > Gradle

4.2 From here select app > Tasks > android > signingReport

4.3 Copy your SHA-256 for your release variant.

• Optional but recommended for quicker testing is the SHA-256 for your debug variant too.
• You may have other custom variants in your project, if you need push support for them copy these as well.

4.4 From the AppGallery Connect Project List select your app.

4.5 Scroll to the bottom to find the "SHA-256 certificate fingerprint" field were you should enter your keys.

Step 5 - Add Huawei Gradle Plugin and Dependencies

5.1 Open your root build.gradle (Project: ) in Android Studio and add maven {url 'https://developer.huawei.com/repo/'} under buildscript { repositories } and allprojects { repositories }

5.2 Under buildscript { dependencies } add classpath 'com.huawei.agconnect:agcp:1.3.1.300'

5.3 You should have in total 3 new lines in your root build.gradle, highlighted below.

5.4 Open your app/build.gradle file and add implementation 'com.huawei.hms:push:4.0.3.301' under the dependencies section.
5.5 Also to the app/build.gradle file add apply plugin: 'com.huawei.agconnect' to the very bottom of the file.
5.6 You should have in total 2 new lines in your app/build.gradle, highlighted below.

👍

Sync Gradle

Make sure to press "Sync Now" on the banner that pops up after saving!

Step 6 - Compatibility with other HMS push libraries or your own HmsMessageService class

This is only required if you must keep another 3rd-party HMS push SDK / Library in your app in-addition to OneSignal or you have your own HmsMessageService.

6.1 Create a class that extends from HmsMessageService, if you don't have one already and add the following methods.

🚧

extends HmsMessageService

If you already had a class that extends HmsMessageService please add the two new OneSignalHmsEventBridge lines instead of creating another class.

public class YourHmsMessageService extends HmsMessageService {    
   public void onNewToken(String token) {
        // ...
        // Forward event on to OneSignal SDK
        OneSignalHmsEventBridge.onNewToken(this, token);
    }

    @Override
    public void onMessageReceived(RemoteMessage message) {
        // ...
        // Forward event on to OneSignal SDK
        OneSignalHmsEventBridge.onMessageReceived(this, message);
    }
}

This is to forward onNewToken and onMessageReceived to OneSignal via the OneSignalHmsEventBridge.

6.2 If you didn't have a class that extended HmsMessageService before make sure to add it to your AndroidManifest.xml under the <application> tag.

<application>
        ...
       
        <!--
          Ensure you only have one intent-filter for "com.huawei.push.action.MESSAGING_EVENT".
          HMS only supports one per app.
        -->
        <service
            android:name=".YourHmsMessageService"
            android:exported="false">
            <intent-filter>
                <action android:name="com.huawei.push.action.MESSAGING_EVENT" />
            </intent-filter>
        </service>

        ...
    </application>

Step 7 - Run and test your app

Run your app on real Huawei device to make sure your device is subscribed to notifications as a Huawei device and can receive notifications sent from the OneSignal dashboard.

📘

Troubleshooting

If you run into any issues please see our Android troubleshooting guide

You can see a fully implemented example project on Github.

Step 8 - (Optional) Omit Google Libraries for Huawei AppGallery builds

Step 8 - Option 1

If your app will only be available on the Huawei AppGallery and you want to omit any Google related dependencies that OneSignal includes you can use exclude with implementation in your app/build.gradle.

implementation('com.onesignal:OneSignal:3.15.1') {
    exclude group: 'com.google.android.gms'
    exclude group: 'com.google.firebase'
}

Step 8 - Option 2

If your app will be for both the Google Play Store and Huawei AppGallery and you want to be selective on which libraries you will include to make your APK smaller you can add dependencies based on buildTypes or variants.
Example:

android {
  // ...
   buildTypes {
       debug {
       }
       release {
       }
       // **** Add your custom hauwei buildType here
       huawei {
       }
   }
}

dependencies {
    // **** Use the full OneSignal dependencies for Google Play Store builds
    debugImplementation 'com.onesignal:OneSignal:3.15.1'
    releaseImplementation 'com.onesignal:OneSignal:3.15.1'
    
    // **** Only include hms:push for your Huawei AppGallery builds.
    huaweiImplementation 'com.huawei.hms:push:5.0.0.300'
    // Omit Google / Firebase libraries for Huawei builds.
    huaweiImplementation('com.onesignal:OneSignal:3.15.1') {
        exclude group: 'com.google.android.gms'
        exclude group: 'com.google.firebase'
    }
}

Common Troubleshooting issues.

While testing, make sure to keep the OneSignal setLogLevel method set to VERBOSE.

Check the logs to see any errors being thrown and Huawei Common Error Codes.

Getting notification_types: -25

"notification_types":-25 means OneSignal timed out waiting for a response from Huawei's HMS to get a push token. This is most likely due to another 3rd-party HMS push SDK or your own HmsMessageService getting this event instead of OneSignal.

Please refer to the above step on how to check this and forward the event if this is the case.

Getting notification_types: -28

This means there is a class HMS is missing from the app that is needed for push. Just having com.huawei.hms:push in the build.gradle will cause this specific error not to happen any more. However, if you have some aggressive Proguard or R8 settings, this might cause issues. We recommend turn off minifyEnabled temporary if you have it to see if that is the root of the issue.

Also, you shouldn't mix and match major release versions of other HMS libraries. Start with either 4 or 5. Make sure not to have a mixture from 3 to 5 which is going to create other errors

Error getting Huawei Push Token

E/OneSignal: HMS ApiException getting Huawei push token!
    com.huawei.hms.common.ApiException: -5: Core error

Check your Proguard or R8 rules to make sure they are setup properly. Possibly disable it temporarily to see if it is related. If it fixes the issue after disabling Proguard or R8 then you can follow this guide and turn it back on:

4. Configuring Obfuscation Scripts:
   https://developer.huawei.com/consumer/en/doc/development/HMS-Guides/Preparations#h1-1575707474823