Push notifications in native Android applications

improve this page | report issue


IBM MobileFirst Platform Foundation provides a unified set of API methods to send, or push, notifications to devices where the MobileFirst application is installed. It is possible to send a notification in 3 distinct types: event source notifications, broadcast notifications and tag notifications.

In this tutorial, the concept, API, and usage of push notifications are explained in the context of Native Android applications.
To create and configure an Android native project, first follow these tutorials:

The following topics are covered:

Notification types

Event source notifications

Event source notifications are notification messages that are targeted to devices with a user subscription.

Broadcast notifications

Broadcast notifications are notification messages that are targeted to all subscribed devices.

Tag notifications

Tag notifications are notification messages that are targeted to all subscribed devices to a particular tag.

For more information, select a notification type.

Setting up the project


  1. Create a MobileFirst project and add a MobileFirst Android Native API.

    In this tutorial and the accompanying sample, the application is called "androidnativepush". Be sure to replace this value with your own application name.

    The native API includes the following push-related file:

    • The push.png file is an icon file that is displayed when a push notification arrives. Copy this file from your native API project and put it in your project res/drawable folders.
  2. Edit the application-descriptor.xml file.

    • Replace the key and senderId values with your API key and project number respectively in the pushSender tag. In case you do not have these, you can get them from the Google Developer Console.
      • Your project number is the senderId.
      • Your Android key is the GCM key. You can generate it in API & Auth > Credentials.

      <pushSender key="GCM-KEY" senderId="GCM-ID"/>
      Note: Google recently announced a move from GCM to FCM. The below instructions have been updated accordingly. Also note that existing in-the-field GCM configurations will continue to function however new GCM configurations will not, and FCM must be used instead.
      Android devices use the Firebase Cloud Messaging (FCM) service for push notifications. To setup FCM:
      1. Visit the Firebase Console.
      2. Create a new project and provide a project name.
      3. Click on the Settings "cog wheel" icon and select Project settings.
      4. Click the Cloud Messaging tab to generate a Server API Key and a Sender ID and click Save.
  3. Edit the wlclient.properties file.

    Edit the wlclient.properties file in your native Android project and enter appropriate values for the following fields:

    • wlServerHost – The hostname or IP address of MobileFirst Server.
    • wlServerPort – The port on which MobileFirst Server is listening.
    • wlServerContext – The context root of your MobileFirst Server instance.
    • GcmSenderId – The project number that you obtained through the Google API console.


  4. Add Google Play Services (optional)

    • From Android SDK Manager > Extras, add the Google Play Services option.
    • Import Google Play Services as a library to the Eclipse workspace:
      1. Select File > Import, select Android > Existing Android Code into workspace, and browse to the
        google-play-services_lib project @ android_sdk_location\extras\google\google_play_services\libproject\google-play-services_lib
      2. After successfully importing google-play-services_lib into the workspace, mark it as an Android library project: Right-click imported-project > properties > Android and select the IsLibrary checkbox.
    • Right-click the Android project > properties > Android > and click Add.
      1. In the Project Selection dialog, select the google-play-services_lib project and click OK.
      2. Click Apply and OK in the Properties window.
    • Add a reference to the google-play-services version in your-app\android\native\AndroidManifest.xml as the first child of the application element:

          android:value="@integer/google_play_services_version" />

  5. Modify the native Android project.

    Verify that the following permissions exist in the AndroidManifest.xml file of your Android project.

    <permission android:name="com.imf.androidnativepush.permission.C2D_MESSAGE" android:protectionLevel="signature" />
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.GET_TASKS"/>
    <uses-permission android:name="com.worklight.androidnativepush.permission.C2D_MESSAGE" />
    <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />
    <uses-permission android:name="android.permission.GET_ACCOUNTS" />
    <uses-permission android:name="android.permission.USE_CREDENTIALS" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>

    Add the launchMode attribute to the main AndroidNativePush activity. Set its value to singleTask.


    Add an intent-filter to the main AndroidNativePush activity for notifications.

        <action android:name="com.worklight.androidnativepush.AndroidNativePush.NOTIFICATION" />
        <category android:name="android.intent.category.DEFAULT" />

    Add the GCMIntentService and add an intent-filter for RECEIVE and REGISTRATION of notifications.

    <service android:name="com.worklight.wlclient.push.GCMIntentService" />
    <receiver android:name="com.worklight.wlclient.push.WLBroadcastReceiver" android:permission="com.google.android.c2dm.permission.SEND">
            <action android:name="com.google.android.c2dm.intent.RECEIVE" />
            <category android:name="com.worklight.androidnativepush" />
            <action android:name="com.google.android.c2dm.intent.REGISTRATION" />
            <category android:name="com.worklight.androidnativepush" />

Select a notification type

Last modified on December 30, 2016