Mobile Center Push

Mobile Center Push enables you to send push notifications to users of your app from the Mobile Center portal. Mobile Center portal and the Push SDK is integrated with Firebase Cloud Messaging.

Note that only devices having the Google Play store application or emulators with Google APIs images can receive the notifications.

Note

Firebase displays a notification in the system notification center only if the application is in background at the moment the Push is received.

Prerequisite - Add Firebase to your app

Before using Mobile Center Push service, you need to add Firebase to your application. You can either choose a manual integration or Firebase Assistant.

1. Prerequisites

Please learn about Prerequisites, in particular please make sure to keep Google Repository up-to-date in the Android SDK Manager.

2. Manual integration

  1. Follow the instructions listed in Manually add Firebase section.

  2. Make sure to continue following instructions in Add the SDK sub section right after but do not add compile "com.google.firebase:firebase-core:${version}" as the SDK manages this step for you can it could trigger incompatibilities if versions mismatch.

3. Using Firebase Assistant

  1. Follow these instructions if you don't see Firebase in the Tools menu.

  2. Click on Tools > Firebase and follow only the first two following steps:

    1. Connect your app to Firebase

    2. Add FCM to your app

Step 3 is managed by Mobile Center SDK automatically, so you can stop after step 2.

Note

Please remove this if added automatically as the SDK manages this for you can it can trigger build errors if versions mismatch:

   compile "com.google.firebase:firebase-core:${version}"
   compile "com.google.firebase:firebase-messaging:${version}"

4. Obtain your Android API Key

Go to Project Settings and under Cloud Messaging, copy your Server Key. This will be the Android API Key that you will need to set in the Mobile Center Push portal.

Add Mobile Center Push to your app

Please follow the Get started section if you haven't set up and started the SDK in your application, yet.

1. Add the Mobile Center Push module

The Mobile Center SDK is designed with a modular approach – a developer only needs to integrate the modules of the services that they're interested in.

  1. Open your app level build.gradle file (app/build.gradle) and add the following lines after apply plugin. Include the dependencies that you want in your project. Each SDK module needs to be added as a separate dependency in this section. For integrating the Push module, add the following lines:

    dependencies {
       def mobileCenterSdkVersion = '0.12.0'
       compile "com.microsoft.azure.mobile:mobile-center-push:${mobileCenterSdkVersion}"
    }
    
  2. Make sure to trigger a Gradle sync in Android Studio.

2. Start Mobile Center Push

In order to use Mobile Center, you need to opt in to the module(s) that you want to use, meaning by default no modules are started and you will have to explicitly call each of them when starting the SDK.

Add Push.class to your MobileCenter.start() method to start Mobile Center Push service.

MobileCenter.start(getApplication(), "{Your App Secret}", Push.class);

Make sure you have replaced {Your App Secret} in the code sample above with your App Secret. Please check out the Get started section if you haven't set up and started the SDK in your application, yet.

Android Studio will automatically suggest the required import statement once you add Push.class to the start() method, but if you see an error that the class names are not recognized, add the following lines to the import statements in your activity class:

import com.microsoft.azure.mobile.MobileCenter;
import com.microsoft.azure.mobile.push.Push;

Intercept push notifications

You can set up a listener to be notified whenever a push notification is received in foreground or a background push notification has been clicked by the user.

Note

Firebase does not generate notifications when the push is received in foreground.

Note

If the push is received in background, the event is NOT triggered at receive time. The event is triggered when you click on the notification.

Note

The Firebase SDK does NOT expose title and message to the background notification click callback. Title and message are only available in foreground pushes.

You need to register the listener before calling MobileCenter.start as shown in the following example:

Push.setListener(new MyPushListener());
MobileCenter.start(...);

If (and only if) your launcher activity uses a launchMode of singleTop, singleInstance or singleTask, you need to add this in the activity onNewIntent method:

    @Override
    protected void onNewIntent(Intent intent) {
        super.onNewIntent(intent);
        Push.checkLaunchedFromNotification(this, intent);
    }

Here is an example of the listener implementation that displays an alert dialog if the message is received in foreground or a toast if a background push has been clicked:

public class MyPushListener implements PushListener {

    @Override
    public void onPushNotificationReceived(Activity activity, PushNotification pushNotification) {

        /* The following notification properties are available. */
        String title = pushNotification.getTitle();
        String message = pushNotification.getMessage();
        Map<String, String> customData = pushNotification.getCustomData();

        /*
         * Message and title cannot be read from a background notification object.
         * Message being a mandatory field, you can use that to check foreground vs background.
         */
        if (message != null) {

            /* Display an alert for foreground push. */
            AlertDialog.Builder dialog = new AlertDialog.Builder(activity);
            if (title != null) {
                dialog.setTitle(title);
            }
            dialog.setMessage(message);
            if (!customData.isEmpty()) {
                dialog.setMessage(message + "\n" + customData);
            }
            dialog.setPositiveButton(android.R.string.ok, null);
            dialog.show();
        } else {

            /* Display a toast when a background push is clicked. */
            Toast.makeText(activity, String.format(activity.getString(R.string.push_toast), customData), Toast.LENGTH_LONG).show(); // For example R.string.push_toast would be "Push clicked with data=%1s"
        }
    }
});

Existing Firebase Analytics users

Note

Mobile Center Push has a dependency on Firebase. Firebase Analytics is included in the core Firebase module and therefore, it's a dependency for Firebase messaging. Mobile Center Push SDK automatically disables Firebase Analytics to prevent unwanted data collection by Firebase.

If you are a Firebase customer and want to keep reporting analytics data to Firebase, you need to call the following method before MobileCenter.start:

Push.enableFirebaseAnalytics(getApplication());
MobileCenter.start(getApplication(), "{Your App Secret}", Push.class);

Enable or disable Mobile Center Push at runtime

You can enable and disable Mobile Center Push at runtime. If you disable it, the SDK will stop updating the Google registration identifier used to push but the existing one will continue working. In other words, disabling the Mobile Center Push in the SDK will NOT stop your application from receiving push notifications.

Push.setEnabled(false);

To enable Mobile Center Push again, use the same API but pass true as a parameter.

Push.setEnabled(true);

This API is asynchronous, you can read more about that in our Mobile Center Asynchronous APIs guide.

Check if Mobile Center Push is enabled

You can also check if Mobile Center Push is enabled or not:

Push.isEnabled();

This API is asynchronous, you can read more about that in our Mobile Center Asynchronous APIs guide.