Using Android Studio

Starting with version 1.2.5.0, where Android O Notification Channels are created,
the WonderPush SDK requires you to use at least compileSdkVersion 26
and support libraries must use version 26.0.2 minimum.
This in turn requires you to use at least minSdkVersion 14.
Note that this does not force you target Android O, you can keep a lower targetSdkVersion if you need to.

You will need to point the SDK to the notification icon
and default activity to launch when clicking a notification.
Simply add the following into your app/build.gradle file:

Replace YOUR_PACKAGE with your application package. This is likely already present, make sure it’s there if you encounter any error.
Eg.: com.your.package.

Replace YOUR_MAIN_ACTIVITY_CLASS with the class name of your main activity.
Eg.: .MainActivity or com.your.package.MainActivity.

Replace YOUR_NOTIFICATION_ICON with a drawable icon to be displayed in the notification.
This icon should follow the Android Notification Icon Guidelines
and provide with a square, multi-resolution, 24dp, white on transparent icon with a 2dp wide margin.
You can also use you launcher icon directly if its shape is easily recognizable.
Mipmaps are not supported however.
Eg.: Your application launcher icon: @drawable/ic_launcher.

For easier assistance, we strongly recommend preserving all WonderPush class names from being obfuscated by ProGuard.
Add the following to your proguard-rules.pro file:

Click on the Sync Project with Gradle Files button and rebuild your project.

If gradle cannot find the dependency, make sure that you include at least the jcenter default repository.
Modify your top-level build.gradle file to include:

// This should already be present in your top-level build.gradle
allprojects {
repositories {jcenter()}}// You can also include directly our Bintray repository if the// desired version is not yet available on JCenter or Maven Central.
allprojects {
repositories {
maven {
url 'http://dl.bintray.com/wonderpush/maven/'}}}

Perform a clean build of your project. If you experience a problem, look at the next points.

The rest of this section discusses potential problems you might encounter, depending on your setup.
Just skip over them unless you see some errors.

Minimum SDK version 14

In order to be able to register Notification Channels in Android O, the WonderPush SDK has to compile against the Android SDK version 26.
This requires using Support libraries version 26, which, along with updating com.google.android.gms:play-service-gcm above version 10.2 for the latest push notification-related fixes,
bumps the minSdkVersion to 14, as far as WonderPush is concerned (your application may already target a higher minimum version).

Compared to the previously imposed minSdkVersion 9, jumping to minSdkVersion 14 only affects 0.7% of all Android users.
Note that Android SDK 14 (aka Android 4.0, Ice Cream Sandwich) was released on October 2011, more than 6 years ago.
In addition, in their blog post, Google says that “We believe that many of these old devices are not actively being used.”

You can avoid to left those users behind if this is a strong requirement for your application, by building multiple APKs using build variants as shown in the blog post.
Doing so you can either drop support for push notifications or use the version 1.2.3.3 of the WonderPush SDK.

Mixed versions of support libraries

If your application uses Support libraries, you may see the following message when you hover the dependency declared in your app/build.gradle file:

All com.android.support libraries must use the exact same version specification (mixing versions can lead to runtime crashes). Found versions 26.0.2, 25.3.1. Examples include com.android.support:support-compat:26.0.2 and com.android.support:animated-vector-drawable:25.3.1.
There are some combinations of libraries, or tools and libraries, that are incompatible, or can lead to bugs. One such incompatibility is compiling with a version of the Android support libraries that is not the latest version (or in particular, a version lower than your targetSdkVersion.)

This is because you use one of the Support libraries in a different version than the WonderPush SDK does,
for instance if you declared the something like following in your app/build.gradle:

dependencies {
compile 'com.android.support:support-v13:25.3.1'}

The resolution is hopefully simple.
You can either upgrade your dependencies to match the version of appcompat-v7 that the SDK uses,
or you can redeclare a dependency on appcompat-v7 with the same version as you are already using, to upgrade the version the SDK will deal with:

dependencies {// If you use an older version for one of the support libraries (here support-v13 for the example)// than the one the WonderPush SDK uses, upgrade yours:
compile 'com.android.support:support-v13:26.0.2'// If you use a newer version than the WonderPush SDK uses, upgrade the one the SDK uses:
compile 'com.android.support:appcompat-v7:26.0.2'}

This will ensure every module of the Support libraries ultimately has the same version.

You may encounter a similar issue with the Google Play Services library, as it is modular too.
See below.

Outdated Android libraries

We know we don’t necessarily use the same versions of the plethora of libraries involved in building an Android application.
For instance, you may encounter the following error when building your project:

The build fails here because proguard does not know one method the WonderPush SDK uses.
That method was introduced in API 24 as a result of the deprecation of a similar method.
The solution consists in downloading the new Android N SDK or ulterior, if not done already, and updating your application build.gradle to read:

android {
compileSdkVersion 24 # or ulterior
}

Note that this also implies to update the any android support library you may use to the matching major version,
and probably the buildToolsVersion too. Android Studio should guide you with hints in the gradle file source.

Conflicting versions of Google Play Services

If this happens, you should see something like the following errors during the gradle build:

The resolution is hopefully simple.
You can either upgrade your dependencies to match the version of play-services-gcm that the SDK uses,
or you can redeclare a dependency on play-services-gcm with the same version as you are already using, to upgrade the version the SDK will deal with:

dependencies {// If you use an older version than the WonderPush SDK uses, upgrade yours:
compile 'com.google.android.gms:play-services-analytics:11.0.4'// If you use a newer version than the WonderPush SDK uses, upgrade the one the SDK uses:
compile 'com.google.android.gms:play-services-gcm:11.0.4'}

This will ensure every module of the Google Play Services library ultimately has the same version.

You may encounter a similar issue with the Support libraries, as they are modular too.
See above.

Migrating from Eclipse ADT to Android Studio

If you already have integrated the WonderPush SDK when the SDK or your project used Eclipse,
then you will get a few errors from the Manifest Merger, this is because the WonderPush SDK
now injects the required manifest modifications automatically thanks to Gradle.

You can simply remove everything you added to your manifest.
Then follow the instructions for Android Studio.

If you do not already use a custom Application class for your project, you can switch very easily. An Application class is the prefered way to initialize many SDKs.
If you cannot, maybe because you use a framework that does not enable you to do so, you can also initialize the WonderPush SDK in the onCreate() method of your main Activity.

Adding an Application class is two-step:

Create the YourApplication class, inheriting android.app.Application, like shown in the previous code snippet.

You now have to point Android to it. Add the following attribute to the <application> tag of your AndroidManifest.xml:

<application android:name=".MyApplication">

Then you will need to implement the WonderPushInitializerImpl class. It is referenced by the SDK’s manifest that is merged into your application.
This class is used under the hood by the simple WonderPush.initialize(this) call above. It is used in multiple places inside the SDK so it can initialize itself on some key events, without additional complexity for you.
Place it in your main application package directly.

Make sure the xmlns:tools namespace is declared in the root <manifest> tag.

Replace YOUR_INITIALIZER_CLASS by the fully qualified name of your initialized class.
Eg.: com.alternate.package.WonderPushInitializerImplementationAlternateName.

tools:replace="android:value" indicates the manifest merger that you are willingly overriding an entry coming from the WonderPush SDK.

Special considerations for Android < 4

If you target API < 14 (pre-Android 4), you should also initialize the WonderPush SDK in the onCreate() method of each of your activities, so that notifications can be displayed in-app over any activity of your application:

Send your first push notifications

Watch for error logs

You can now test your WonderPush-enabled application, but as nobody’s perfect, not even us, we know you may run into a few setup problems.
We advise you to look at your logs for any entry tagged WonderPush as the SDK will report setup issues this way. Don’t hesitate to create a logcat filter by log tag WonderPush to see them more easily.

If you have any problem or wonder what the SDK is doing, you may temporarily make it verbose.
Simply do the following, preferably just before initializing the SDK, so as to get the most information:

WonderPush.setLogging(true);// ← only use true in development!

You should not do this for a production build. Once done with the additional logs, turn verbosity off.

Missing Google Play?

If you see a message like Google Play Services not present., then you are either using a wrong emulator system image, a device that does not support Google Cloud Messaging or Google Play Services, or using a very old device.

If on the emulator, you should use a Google APIs system image.
You can install one using the Android SDK Manager, and under the folder matching the desired Android version, check and install a system image whose name starts with “Google APIs”.
Then open the Android Virtual Device Manager, edit your AVD and choose a “Google APIs” target. You may also increase your Internal storage size or SD card size if you still have some trouble.

If your device does not support Google Cloud Messaging or Google Play Services, like the Amazon Kindle Fire, you should use an SDK adapted to such platform.

Outdated Google Play?

If you see a message like Google Play services out of date., then you should see a notification inviting you to update Google Play Services, click on it.

If on the emulator, you should download the newest Android SDK Platform, and create a new AVD using this API level.
If you already use the latest available API level, they you can try finding and downloading the latest Google Play Services APK on the Internet and installing it on your emulator manually.
You can also try to declare the compile 'com.google.android.gms:play-services-gcm:VERSION' dependency using a lower version than the WonderPush Android SDK for your tests.

Registered installation

You should now see one installation in your WonderPush dashboard.
Click Audience, choose All users, your installation should now be listed in the preview list.

A few statistics may be cached, click Refresh now if necessary.

Make sure your installation is displayed as pushable. If not, you probably forgot one step of the above, look for the logs for pointers.

Some push notifications seem to never get received?

Depending on the chosen scheduling, it may take up to 1 minute for our servers to process your notifications. Note that you must both be pushable and present in the targeted segment for your device to be delivered a notification. If in doubt, click on your notification, then click on the associated segment, and see if you are listed as pushable there.

When your device receives a push notification, you can see a log like the following:

If you force-quit the application, the system won’t deliver notifications to the SDK until you manually restart the app.

Look for the logs, in the event something went wrong in the handling of the notification, they should contain an helpful message for you, or a stacktrace that you should kindly send back to us.

Need support?

If all else fails, don’t hesitate to contact us by chat, using the “Chat with us” button in the lower right corner of your WonderPush dashboard, or by email.

Using the SDK in your Android application

Track your first event

The SDK automatically tracks generic events. This is probably insufficient to help you analyze, segment and notify users properly.
You will want to track events that make sense for your business, here is an simple example:

WonderPush.trackEvent("customized_interests");

This would permit you to know easily whether a user kept the default set of "topics of interests", say in a newsstand application, or if they already chose a topics that represents well their center of interest.
Your notification strategy could be to incite to customization for the lazy users, whereas you could engage in a more personalized communication with the users you performed the customized_interests event.

Enriching the events

Events can host a rich set of properties that WonderPush indexes to permit you to filter users based on finer criteria.
To do so, simply give a JSON object as second parameter. Here is an example:

Inactive users with non-empty carts could then easily be notified. Combined with a free delivery coupon for carts above a given amount, your conversion rate will improve still!

Opt-out

On Android, users are opt-in by default, and the SDK registers the device at the first opportunity (the first launch after either a new installation or an update).
A user always has the option of opening the system settings and blocking notifications. This process does not prevent the application from receiving push notifications, but it prevents any notification from being displayed in the notification center, they are simply hidden silently, and the application has no mean to know it.

If a user no longer wants to receive notifications, you will rather want them to opt out of push notifications.
This is done very simply using the following function call, and WonderPush will no longer send push notifications to this installation:

WonderPush.setNotificationEnabled(false);

Note that the device is not actually unregistered from push notifications, so the registration id continues to be valid and the device stays reachable.
The installation is simply marked and reported as Soft opt-out in the dashboard, and WonderPush filters it out from the targeted users.

Demo application

API Reference

Advanced usage

Using your own account

Sticking with the WonderPush sender ID is the simplest approach. However, you would not be able to send push notifications by other means than WonderPush.
If you want to use another sender ID, you can change it by adding the following in the res/values/string.xml file inside your own application:

If you haven’t created an API project yet, click Create Project. Supply a name and click Create.

In the overview, locate your project id and project number.

Copy down your project number. This is your GCM sender ID.

If you do not include WonderPush’s sender ID in the application, don’t forget to give us your browser or server API key, also known as Sender Auth Token, via your WonderPush dashboard, under Settings / Configuration, so we can push notifications on your behalf. Otherwise, if you include our sender ID as recommended, you don’t have to take any action. Your application to be able to receive WonderPush notifications as well as notifications from other providers.

Updating this value will require to unregister the device, prior to re-registering it, and the resulting registration id will be different. This is handled automatically by the SDK.

Tip: If you already have push notification support in your application and require that the registration ids don’t change, then only use your sender ID in the push_sender_ids string value. But as explained above, be sure to give us your server API key in the dashboard.

Knowing when a notification is opened

Sometimes you need to take an action when the notification is opened.
The SDK broadcasts a local intent when the notification is opened. It gives you the original received push notification intent, so you can possibly read custom key-value payload. The SDK also tells you whether the notification has been opened after the user clicked it, or if it was automatically opened because the application was already in foreground.

// Put the following call before you initialize the SDK, in your Application class for example
LocalBroadcastManager.getInstance(this).registerReceiver(newBroadcastReceiver() {@OverridepublicvoidonReceive(Context context, Intent intent) {// Read whether the user clicked the notification (true) or if it was automatically opened (false)boolean fromUserInteraction = intent.getBooleanExtra(WonderPush.INTENT_NOTIFICATION_OPENED_EXTRA_FROM_USER_INTERACTION, true);// Get the original push notification received intent
Intent pushNotif = intent.getParcelableExtra(WonderPush.INTENT_NOTIFICATION_OPENED_EXTRA_RECEIVED_PUSH_NOTIFICATION);if(pushNotif != null) {// Perform desired action, like reading custom key-value payload}}},newIntentFilter(WonderPush.INTENT_NOTIFICATION_OPENED));

Handling registered callbacks on button click

Notification and in-app buttons can also trigger app-specific methods once clicked.

The SDK will broadcast a local intent that your application can listen to and handle, this keeps all parts decoupled and won’t cause bugs if a user has an older version of your application where the callback does not exist.

That’s it, your registered callback will be called whenever the user clicks that button.

Handling data notifications

Data notifications can be received while your application is either foreground or background, they do not display any alert in the notification center, nor any in-app message. As such, they have to be handled using code.

The WonderPush SDK broadcasts a local intent when a data notification is received. Simply register a local broadcast received, preferably in your Application class:

Handling your own deep links

The most common way of handling deep links is to add intent filters on the desired activities, so that the system can properly resolve URIs such as yourApplicationSpecificScheme://someActivity.
You can set this up this way:

<activity android:name=".SomeActivity"><!-- Makes the activity reachable from the yourApplicationSpecificScheme://someActivity URI across the system --><intent-filter><action android:name="android.intent.action.VIEW"/><category android:name="android.intent.category.DEFAULT"/><category android:name="android.intent.category.BROWSABLE"/><data android:scheme="yourApplicationSpecificScheme" android:host="someActivity"/></intent-filter></activity>

You would then use this application-specific URI in your notification.
When your activity is started, you can examine the data URI from the intent to extract any additional information.

If desired, you can also broadcast the notification opening to let some code resolve the most appropriate action to perform.
To do so, you would use the wonderpush://notificationOpen/broadcast URI in your notification.
Here is how to listen to this local broadcast, preferably in your Application class:

Handling your own notifications

UPGRADING

Prior to the WonderPush Android SDK v1.2.1.0, we recommended using a BroadcastReceiver. While still technically valid, you should no longer call WonderPush.onBroadcastReceived(), or notifications may be displayed twice.

If you want to handle some notifications yourself, you will have to first create your own GcmListenerService as follows:

The GcmListenerService is called whenever a push notification is received.

Make sure the xmlns:tools namespace is declared in the root <manifest> tag.

tools:node="remove" indicates the manifest merger that you want to remove an entry that would otherwise be merged from the WonderPush SDK.
While not strictly necessary, this ensures your GcmListenerService will be called instead of the WonderPush one.

Replace: YOUR_CUSTOM_GCMLISENERSERVICE_CLASS with the actual fully qualified class name of the class you’ve just created.
Eg.: com.your.package.CustomGcmListenerService.