Upgrading to Android SDK v3


We have released the Android SDK v4.

You're looking at the upgrade guide to the older Android SDK v3.
Please follow the upgrade guide to the newer Android SDK v4 instead.

Start with the guide

Follow these steps of the new quickstart guide:

Then go on with the rest of this document.

Make sure to use the appropriate Firebase Sender ID

The previous versions of the WonderPush Android SDK used the push_sender_ids string resource from res/values/string.xml, which defaults to WonderPush's own Sender ID, 1023997258979.
By default, the WonderPush Android SDK v3 uses the Sender ID of the Firebase account that is used by your application by reading the google-services.json file, if available.

Go to your WonderPush dashboard in the Settings / Configuration page, Android app tab and check to see if you have already filled a Server Key.

  • if filled, then you'll need to use the Sender ID corresponding to that Server Key. If in doubt, we can help.
    If it matches the Firebase Sender ID you see in google-services.json, you can stop here.
    Look at your push_sender_ids value, and use that value; if there are 2 values, ignore 1023997258979 and use the other one.
  • if empty, then use 1023997258979 as Sender ID.

Finally, you need to force the Sender ID picked up by the SDK by editing your app/build.gradle file to add the following entry:

android {
    defaultConfig {
        buildConfigField 'String', 'WONDERPUSH_SENDER_ID', '"YOUR_SENDER_ID"'

Replace YOUR_SENDER_ID with the Sender ID identified earlier.

Remove unused code

  • Remove the manifest placeholders in your AndroidManifest.xml:
android {
    defaultConfig {
        // You can remove this, it is no longer used
        manifestPlaceholders = [
                wonderpushNotificationIcon: '@drawable/notification_icon',
                wonderpushDefaultActivity : '.MainActivity'

Now that you have the WONDERPUSH_CLIENT_ID and WONDERPUSH_CLIENT_SECRET build config fields, you can:

  • Remove your WonderPushInitializerImpl class
  • Remove a possible <meta-data android:name="wonderpushInitializerClass" …/> in your AndroidManifest.xml. You would only have this if you changed the class name from the above default.


No need to keep WonderPushInitializerImpl, as most options can now be controlled by configuration options. That said, if you do have a valid use case for the initializer class, keep it as is.

  • Remove calls to WonderPush.initialize(Context) and WonderPush.initialize(Context, String, String). The automatic initialization takes care of this.
    Your Application class may now be empty, feel free to remove it along with its reference in attribute of the <application android:name=".MyApplication"> tag in your AndroidManifest.xml.
    Note that WonderPush.setUserId() is only required when changing logging in or out, the SDK already remembers the latest given value, so you can remove that call there too.

  • Remove calls to WonderPush.showPotentialNotification(). They were only needed for pre Android 14 versions anyway.

  • We've renamed a few methods:

Deprecated method

New method











Things are getting a whole lot simpler, don't you feel?

Remove any GcmListenerService

If you used your own implementation of GcmListenerService, you will need to move its onMessageReceived(String, Bundle) implementation to call move it to your FirebaseMessagingService.onMessageReceived(RemoteMessage) implementation.

See Firebase Cloud Messaging setup for Android for more information on how to setup your own FirebaseMessagingService.

public class MyFirebaseMessagingService extends FirebaseMessagingService {

    public void onMessageReceived(RemoteMessage remoteMessage) {
        if (com.wonderpush.sdk.push.fcm.FirebaseMessagingService.onMessageReceived(this, remoteMessage)) {
            // The notification was handled by WonderPush
        } else {
            // Handle the notification yourself


You will also need to update the changes in your AndroidManifest.xml:



        <!-- OLD ENTRIES TO REMOVE -->
                <action android:name="com.google.android.c2dm.intent.RECEIVE" />

        <!-- NEW ENTRIES TO ADD -->
        <!-- This removes the FirebaseMessagingService provided by the WonderPush SDK. -->
        <!-- This registers your own FirebaseMessagingService. -->
                <action android:name="com.google.firebase.MESSAGING_EVENT" />



Remove any InstanceIDListenerService

If you used your own implementation of InstanceIDListenerService, you will need to move its onTokenRefresh() implementation to call move and adapt it to your FirebaseMessagingService.onNewToken(String) implementation.

public class MyFirebaseMessagingService extends FirebaseMessagingService {

    public void onNewToken(String token) {
        WonderPushFirebaseMessagingService.onNewToken(this, token);


You will also need to update the changes in your AndroidManifest.xml:

        <action android:name="com.google.android.gms.iid.InstanceID" />

And follow the steps in the above Remove any GcmListenerService section to implement your FirebaseMessagingService.

Review if you have any GCM specific code

If you have an advanced integration of notification, it can be a good idea to search for the following strings in your code:

  • com.google.android.gms:play-services-gcm
  • GcmReceiver
  • com.google.android.c2dm.permission.SEND
  • com.google.android.c2dm.intent.RECEIVE
  • com.google.android.gms.iid.InstanceID
  • InstanceIDListenerService
  • GcmListenerService
  • GcmPubSub

If you found any, follow the GCM to FCM migration guide, as parts of it may apply to you – although most of the work only impacts the WonderPush Android SDK implementation and not your application.

Enable Java 8 language features

// Make sure you can use Java 8 language features
// See: https://developer.android.com/studio/write/java8-support.html#supported_features
android {
  // Configure only for each module that uses Java 8
  // language features (either in its source code or
  // through dependencies).
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  // For Kotlin projects
  kotlinOptions {
    jvmTarget = "1.8"

Continue with the guide

You can continue the quickstard guide from the Step 5. Sync Gradle and build to see that everything compiles and runs fine.