MoEngage Docs

Push Notification

Configuring your MoEngage Account

Copy the Sever Key from the FCM console and add it to the MoEngage Dashboard(Not sure where to find the Server Key refer to Getting FCM Server Key. To upload it, go to the Settings Page Dashboard --> Settings --> Channel --> Push --> Mobile Push --> Android and add the Server Key and package name.
Please make sure you add the keys both in Test and Live environment.

Before configuring MoEngage SDK for receiving push notifications please make you have configured Firebase in your application, if not done already refer to the documentation and complete setup.
Also, make sure you have added the Firebase Messaging dependency in your application's build.gradle file.

Adding metadata for push notification

To show push notifications some metadata regarding the notification is required where the small icon and large icon drawables being the mandatory ones.
Refer to the config object below and create a NotificationConfig object and pass it to the SDK using the MoEngage.Builder object.

/**
 * Notification Configuration object.
 *
 * @param smallIcon Resource-Id for the Notification Small icon.
 *
 * Guideline: Notification small icon should be flat, pictured face on, and must be white on
 * a transparent background.
 *
 * @param largeIcon Resource-Id for the Notification Large Icon
 *
 * @param notificationColor Set the color for notification.
 *
 * @param tone File name of the sound file which should be played whenever notification is
 * received on the device. The sound file should be present in the raw folder of your application.
 *
 * <b>Note:<b/> This is used only for Android N and below devices.
 *
 * @param isMultipleNotificationInDrawerEnabled By default, the SDK shows only one notification at a given point in time, existing
 * notification is updated with the new notification. If set to true new notifications would be
 * shown separately.
 *
 * @param isBuildingBackStackEnabled By default MoEngage SDK synthesis the back-stack from the manifest when redirecting user on
 * push click. If set to false SDK would not synthesis a back-stack.
 *
 * @param isLargeIconDisplayEnabled false if you don't want to show the notification large icon on
 * Android Lollipop and above devices, else true.
 *
 * @since 11.0.00
 *
 */
public class NotificationConfig(
    /**
     * Resource-id for push-notification small icon
     */
    @DrawableRes var smallIcon: Int,
    /**
     * Resource-id for push-notification large icon
     */
    @DrawableRes var largeIcon: Int,
    /**
     * Color resource for push-notification icon.
     */
    @ColorRes var notificationColor: Int,
    /**
     * Notification tone for android Oreo and below devices.
     */
    var tone: String?,
    /**
     * If true show multiple notification in the drawer, else show single notification.
     */
    var isMultipleNotificationInDrawerEnabled: Boolean,
    /**
     * If false sdk will not synthesize back-stack for the notification's click action.
     */
    var isBuildingBackStackEnabled: Boolean,
    /**
     * If true notification large icon will be shown on Lollipop and above devices.
     */
    var isLargeIconDisplayEnabled: Boolean
) {
    /**
     * @param smallIcon Resource-Id for the Notification Small icon.
     *
     * Guideline: Notification small icon should be flat, pictured face on, and must be white on
     * a transparent background.
     * @param largeIcon Resource-Id for the Notification Large Icon
     */
    constructor(@DrawableRes smallIcon: Int, @DrawableRes largeIcon: Int) : this(
        smallIcon, largeIcon, -1, null, false,
        true, true
    )

}

Use the configureNotificationMetaData() to pass on the configuration to the SDK.

val moEngage = MoEngage.Builder(this, "XXXXXXXX")
     .configureNotificationMetaData(NotificationConfig(R.drawable.small_icon, R.drawable.large_icon, R.color.notiColor, null, true, isBuildingBackStackEnabled = false, isLargeIconDisplayEnabled = true))
     .build()
   MoEngage.initialise(moEngage)
MoEngage moEngage =
        new MoEngage.Builder(this, "XXXXXXXXXX")
            .configureNotificationMetaData(new NotificationConfig(R.drawable.small_icon, R.drawable.large_icon, R.color.notiColor, "sound", true, true, true))
            .build();
    MoEngage.initialise(moEngage);

For push notifications to work properly it is important the SDK is initialized with the above meta data in the onCreate() of the Application class

📘

Notification Small Icon Guidelines

Notification small icon should be flat, pictured face on, and must be white on a transparent background.

Configuring Firebase Cloud Messaging

For showing Push notifications there are 2 important things

  1. Registration for Push, i.e. generating push token.
  2. Receiving the Push payload from Firebase Cloud Messaging(FCM) service and showing the notification on the device.
    The above can either be handled by the application or MoEngage SDK. There is some configuration required based on whether the above-mentioned things are handled by the application or SDK.

Push Registration and Receiving handled by App

By default, MoEngage SDK attempts to register for push token, since your application is handling push you need to opt-out of SDK's token registration.

How to opt-out of MoEngage Registration?

To opt-out of MoEngage's token registration mechanism disable token registration while configuring FCM in the MoEngage.Builder as shown below

val moEngage = MoEngage.Builder(this, "XXXXXXXX")
          .configureNotificationMetaData(NotificationConfig(R.drawable.small_icon, R.drawable.large_icon, R.color.notiColor, null, true, isBuildingBackStackEnabled = false, isLargeIconDisplayEnabled = true))
        .configureFcm(FcmConfig(false))
        .build()
    MoEngage.initialise(moEngage)
MoEngage moEngage = new MoEngage.Builder(this, "XXXXXXXXXX")
            .configureNotificationMetaData(new NotificationConfig(R.drawable.small_icon, R.drawable.large_icon, R.color.notiColor, "sound", true, true, true))
            .configureFcm(new FcmConfig(false))
            .build();
MoEngage.initialise(moEngage);

Pass the Push Token To MoEngage SDK

The Application would need to pass the Push Token received from FCM to the MoEngage SDK for the MoEngage platform to send out push notifications to the device.
Use the below API to pass the push token to the MoEngage SDK.

MoEFireBaseHelper.getInstance().passPushToken(applicationContext,token)
MoEFireBaseHelper.getInstance().passPushToken(getApplicationContext(), token);

Note: Please make sure token is passed to MoEngage SDK whenever push token is refreshed and on application update. Passing token on application update is important for migration to the MoEngage Platform.

Passing the Push payload to the MoEngage SDK

To pass the push payload to the MoEngage SDK call the MoEngage API from the onMessageReceived() from the Firebase receiver.
Before passing the payload to the MoEngage SDK you should check if the payload is from the MoEngage platform using the helper API provided by the SDK.

if (MoEPushHelper.getInstance().isFromMoEngagePlatform(remoteMessage.data)){
      MoEFireBaseHelper.getInstance().passPushPayload(applicationContext, remoteMessage.data)
    }else{
      // your app's business logic to show notification
    }
if (MoEPushHelper.getInstance().isFromMoEngagePlatform(remoteMessage.getData())) {
  MoEFireBaseHelper.Companion.getInstance().passPushPayload(getApplicationContext(), remoteMessage.getData());
}else{
  // your app's business logic to show notification
}

Push Registration and Receiving handled by SDK

Add the below code in your manifest file.

<service android:name="com.moengage.firebase.MoEFireBaseMessagingService">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

When MoEngage SDK handles push registration it optionally provides a callback to the Application whenever a new token is registered or token is refreshed.
An application can get this callback by implementing FirebaseEventListener and registering for a callback in the Application class' onCreate() using MoEFireBaseHelper.getInstance().addEventListener()

🚧

MoEngage SDK(version 9.2.00 above) is compiled with 17.3.2 hence expecting the client app to use Firebase version 17.3.2. However, we do support versions below 17.1.0 but your application needs to handle the token registration mechanism.

❗️

Note

At any point, your application's manifest should have only one service with intent filter com.google.firebase.MESSAGING_EVENT. If there is more than one service only the first service will receive the callback and MoEngage SDK might never receive the Push Payload resulting in poor delivery rates.

Rich Landing

Refer to the Adding Rich Landing Page doumentation.

Updated 2 days ago


Push Notification


Suggested Edits are limited on API Reference Pages

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