The WonderPush Developer Hub

Welcome to the WonderPush developer hub. You'll find comprehensive guides and documentation to help you start working with WonderPush as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Troubleshooting Android

Common issues on Android.


Activate logging when troubleshooting

You can activate WonderPush logs by adding a single line in your build config: buildConfigField 'boolean', 'WONDERPUSH_LOGGING', 'true'

Our logs report pretty much the entire activity of our SDK. They are all prefixed with [WonderPush] so they're easy to filter in and out.

Don't forget to turn them off in your release build.

Make sure you use minimum required versions

If you keep your application up-to-date with the latest Android Studio, Gradle and Gradle plugin, then you are probably already complying with these requirements, but let's be explicit to ensure success.

  • Make sure to use the latest targetSdkVersion, 26 minimum, per Google Play requirement
  • Make sure to use the latest compileSdkVersion, 26 minimum.
  • Make sure you use appropriate version for support libraries, if you use any, matching compileSdkVersion, 26.0.2 minimum.
  • Make sure to use minSdkVersion 21 minimum.

This translates to the following in your app/build.gradle file:

android {
    # Use 26 minimum.
    # Using the latest is encouraged by Android Studio
    # Cannot be lower than targetSdkVersion
    compileSdkVersion 26
    defaultConfig {
        # Use 26 minimum per Google Play requirement:
        # using the latest is encouraged by Android Studio
        targetSdkVersion 26
        # Use 14 minimum per Firebase requirement:
        minSdkVersion 21

β€œuses-sdk:minSdkVersion 16 cannot be smaller than version 21” error message

We have raised the required minSdkVersion to 21, released in 2014 and covers 95% of Android devices.

Make sure your application uses at least 21 in your app/build.gradle, otherwise you'll see the following build error:

Manifest merger failed : uses-sdk:minSdkVersion 16 cannot be smaller than version 21 declared in library [com.wonderpush:wonderpush-android-sdk:4.0.1] [...]/.gradle/caches/transforms-2/files-2.1/110f18d74c064672b3bb9b02e46b3f51/jetified-wonderpush-android-sdk-4.0.1/AndroidManifest.xml as the library might be using APIs not available in 16
    Suggestion: use a compatible library with a minSdk of at most 16,
        or increase this project's minSdk version to at least 21,
        or use tools:overrideLibrary="com.wonderpush.sdk" to force usage (may lead to runtime failures)

Trouble receiving notifications

First thing, make sure that you are in the targeted audience by double checking that your installation is in the chosen segment. Look at the installation's tags, properties and events from the dashboard.

Make sure you don't have tons of notifications already displayed, as some devices will not show new notifications.

Recently upgraded to our Android SDK v4?

Do not forget to add the FCM compatibility module when upgrading to our Android SDK v4.
Otherwise you will see the following error in your logs:

E/WonderPush.Push: Cannot refresh push subscription, no push service available

See the Upgrading to Android SDK v4 guide for resolution.

Network firewalls

If your device is connected to the Internet via an enterprise network, chances are you are behind a Firewall. Firebase Cloud Messaging, the technology behind Android push notifications, requires ports 5228, 5229 and 5230 to be open for notifications to be delivered.

Power management

In low battery or battery saver modes, notifications can be delayed.

Devices with stamina or ultra power mode enabled drop push notifications altogether to improve battery life even further. Please disable such mode if you want to receive notifications.

The app must not have been force quit or killed.
Note that some devices automatically kill applictions after some time spent in the background as a mean to extend battery life. This can be easily checked if you see W/GCM: broadcast intent callback: result=CANCELLED forIntent { flg=0x10000000 pkg=com.your.package (has extras) } logs in logcat when the device receives a push notification. This indicates that FCM will not wake the app up to let it display the appropriate notification, and thus while delivered properly, the device drops the notification.

Adaptive battery may delay notifications for some apps. You can disable it in the Settings / Battery / Adaptive Battery screen.

App Standby Buckets further affect the application's ability to consume power. In the Settings / Developer Options / Apps (before last section) / Standby apps screen, you can read the current app's state. Read more about app standby buckets on App Standby Buckets and Power management restrictions in the Android documentation.
You can explicitly exempt an application from the Settings / Apps & notifications / Advanced / Special app access / Battery optimization screen, select All apps in the dropdown above the list, click on your app, and choose Don't optimize in the popup.
The most effective way to avoid the restrictive buckets is simply to open the app often. Note that if you recently opened the application to check something like whether you actually subscribed to that event you expected a notification for, you have hence influenced the app standby bucket and just gave it more quota on power usage.

Build error mentioning AndroidX

You have recently upgraded our Android SDK to v4 but your application does not use AndroidX and you get the following Gradle build errors:

This project uses AndroidX dependencies, but the 'android.useAndroidX' property is not enabled. Set this property to true in the file and retry.
The following AndroidX dependencies are detected: androidx.collection:collection:1.0.0, androidx.cardview:cardview:1.0.0, androidx.versionedparcelable:versionedparcelable:1.0.0, androidx.core:core:1.0.0, androidx.localbroadcastmanager:localbroadcastmanager:1.0.0, androidx.lifecycle:lifecycle-common:2.0.0, androidx.arch.core:core-common:2.0.0, androidx.constraintlayout:constraintlayout:1.1.3, androidx.constraintlayout:constraintlayout-solver:1.1.3, androidx.lifecycle:lifecycle-runtime:2.0.0, androidx.annotation:annotation:1.0.0

Our SDK now depends on AndroidX to benefit from more modular dependencies.
Simply follow Android's Migrating to AndroidX guide.
Migrating is as easy as clicking on the Refactor > Migrate to AndroidX menu entry in Android Studio.

All libraries must use the exact same version specification


You are still using our Android SDK v3.x. We have released our Android SDK v4.
Please upgrade using our Upgrading to Android SDK v4 guide.

If you see the error All libraries must use the exact same version specification, add the following in your app/build.gradle file:

dependencies {
    # Make sure you use a version matching your compileSdkVersion, 26.0.2 minimum
    # Use the highest version you see in the error message
    implementation ''

Could not initialize WonderPush

If you see the following log:

WonderPush: Could not initialize WonderPush using the initializer class, BuildConfig options or manifest <meta-data> options!
WonderPush: No BuildConfig class found. You probably need to give the value of your gradle defaultConfig.applicationId as the a "wonderpush_buildConfigPackage" string resource or a "com.wonderpush.sdk.buildConfigPackage" manifest <meta-data>.

then you will need to tell the SDK where to find the BuildConfig class.

Firebase fails to initialize. My installation is opt-out.

If you see one of the following errors:

java.lang.IllegalArgumentException: Please set your project ID. A valid Firebase project ID is required to communicate with Firebase server APIs: It identifies your project with Google.
Could not get Firebase InstanceId FIS_AUTH_ERROR

You must use the WonderPush SDK FCM module version 1.0.1 at least.

Edit your app/build.gradle to add:

dependencies {
  implementation 'com.wonderpush:wonderpush-android-sdk-fcm:[1.0.1,2)'

Huawei: My installation is opt-out

If you see the following error in your device logs:

E WonderPush.Push.HCM.HCMPushService: Could not get HMS InstanceId
E WonderPush.Push.HCM.HCMPushService: com.huawei.hms.common.ApiException: 907135701: scope list empty

then you probably have a mismatch between the signing configuration and the SHA-256 certificate fingerprint configured in AppGallery Connect.

Check your app/build.gradle file:

android {
    signingConfigs {
        mySignConfig { // <- note the actual name you have, and use it below
            // [...]

    // Make sure to setup the signingConfig in all buildTypes.
    // You are most likely missing the debug build type.
    buildTypes {
        debug {
            signingConfig signingConfigs.mySignConfig // <- use the actual name of one of your signingConfigs
            // [...]
        release {
            signingConfig signingConfigs.mySignConfig // <- use the actual name of one of your signingConfigs
            // [...]

You can also add more SHA-256 certificate fingerprints in AppGallery Connect. Follow Huawei Push Kit / Preparations / 1.3 Generating a Signing Certificate Fingerprint documentation on how to proceed.

Updated 4 days ago

Troubleshooting Android

Common issues on Android.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.