Advanced Push Configuration

🚧

This section is only required for advanced use-cases where the application wants to customise/alter the default behaviour of the MoEngage SDK.

MoEngage SDK allows the client application to optionally customize the notification display and extend/customize the behavior of the notification. Some of the possible customizations are deciding whether to show a notification or not, tweaking the NotificationCompat.Builder object, etc.
To do so you need to extend a class called PushMessageListener provided by the MoEngage SDK and pass on the instance of this class to the MoEngage SDK. Once you have done this you can override the default implementation as per the requirement.
Let's look at the above steps in more detail.

Extending PushMessageListener

First thing required to customise the notification is creating a class which extends PushMessageListener we will call this class CustomPushMessageListener(only for illustration purpose you can have any class name you want). The barebones of this class would look something like below.

class CustomPushMessageListener : PushMessageListener() {
}
public class CustomPushMessageListener extends PushMessageListener {

}

Refer to the API documentation of PushMessageListener for more details about the class.

Passing the instance of CustomPushMessageListener to MoEngage SDK

You need to pass on the instance of CustomPushMessageListener to the MoEngage SDK in the onCreate() of the Application class. You need to pass the instance to MoEPushHelper.getInstance().setMessageListener(); API. Below is a sample call.

MoEPushHelper.getInstance().messageListener = CustomPushMessageListener()
MoEPushHelper.getInstance().setMessageListener(new CustomPushMessageListener());

Checkout the API documentation for more details.

Tweaking the NotificationCompat.Builder

To tweak the NotificationCompat.Builder object you would need to override onCreateNotification() in the CustomPushMessageListener class created above. You can call the super() to get all the MoEngage Defaults and then tweak it further as per requirement. Our CustomPushMessageListener would like some below.
This method is called on a worker thread, you can choose to make network requests if required.

class CustomPushMessageListener : PushMessageListener() {

  // customise the notification builder object as required
  override fun onCreateNotification(context: Context, payload: NotificationPayload): Builder {
    // get the object constructed by MoEngage SDK
    val builder = super.onCreateNotification(context, payload)
    // customise as required.
    // below customisation is only for illustration purpose. You can chose to have other
    // customisations as required by the application.
    builder.setOngoing(true)
    // return the builder object to the SDK for posting notification.
    return builder
  }
}
public class CustomPushMessageListener extends PushMessageListener {

  // customise the notification builder object as required
  @Override public Builder onCreateNotification(Context context, NotificationPayload payload) {
    // get the object constructed by MoEngage SDK
    NotificationCompat.Builder builder = super.onCreateNotification(context, payload);
    // customise as required.
    // below customisation is only for illustration purpose. You can chose to have other
    // customisations as required by the application.
    builder.setOngoing(true);
    // return the builder object to the SDK for posting notification.
    return builder;
  }
}

Checkout API Reference for more details.

Optionally control notification display

To control whether a notification is shown to the user or not you need to override isNotificationRequired() in the CustomPushMessageListener class created above.
If you intend to show the notification overridden implementation should return true else false
Note: It is important to call the super() in this case. If the super() is not called notification will not be displayed. If the super() returns false make sure your implementation returns false else users might end-up seeing blank notifications. Below is the structure for implementation.
If this method returns false this notification is discarded by the SDK, i.e. notification will not be shown on the device and the impression will not be tracked.

class CustomPushMessageListener : PushMessageListener() {

  // decide whether notification should be shown or not. If super() returns false this method
  // should return false. In case super() isn't called notification will not be displayed.
  override fun isNotificationRequired(context: Context, payload: Bundle): Boolean {
    val shouldDisplayNotification = super.isNotificationRequired(context, payload)
    // do not show notification if MoEngage SDK returns false.
    if (shouldDisplayNotification) {
      // app's logic to decide whether to show notification or not.
      // for illustration purpose reading notification preference from SharedPreferences and
      // deciding whether to show notification or not. Logic can vary from application to
      // application.
      val preferences = context.getSharedPreferences("demoapp", 0)
      return preferences.getBoolean("notification_preference", true)
    }
    return shouldDisplayNotification
  }
}
public class CustomPushMessageListener extends PushMessageListener {

  // decide whether notification should be shown or not. If super() returns false this method
  // should return false. In case super() isn't called notification will not be displayed.
  @Override public boolean isNotificationRequired(Context context, Bundle payload) {
    boolean shouldDisplayNotification = super.isNotificationRequired(context, payload);
    // do not show notification if MoEngage SDK returns false.
    if (shouldDisplayNotification){
      // app's logic to decide whether to show notification or not.
      // for illustration purpose reading notification preference from SharedPreferences and
      // deciding whether to show notification or not. Logic can vary from application to
      // application.
      SharedPreferences preferences = context.getSharedPreferences("demoapp", 0);
      return preferences.getBoolean("notification_preference", true);
    }
   return shouldDisplayNotification;
  }
}

Checkout API Reference for more details.

Notification Received Callback

To receive a callback whenever a push is received override the onNotificationReceived() in the CustomPushMessageListener class created above.

class CustomPushMessageListener : PushMessageListener() {
  
  override fun onNotificationReceived(context: Context, payload: Bundle) {
    super.onNotificationReceived(context, payload)
    //callback for push notification received.
  }
}
public class CustomPushMessageListener extends PushMessageListener {

  @Override public void onNotificationReceived(Context context, Bundle payload) {
    super.onNotificationReceived(context, payload);
    //callback for push notification received.
  }
}

Check API Reference for more details.

Notification Clicked Callback

To receive a callback whenever a push is received override the onHandleRedirection() in the CustomPushMessageListener class created above.
This method doubles as a callback and can be used for handling redirection. If you want to handle redirection on notification click do not call the super() and add your custom logic for redirection here.

class CustomPushMessageListener : PushMessageListener() {

  override fun onHandleRedirection(activity: Activity, payload: Bundle) {
    super.onHandleRedirection(activity, payload)
    //callback for notification cleared. if you want to handle redirection then do not call super()
    // and add the redirection logic here.
  }
}
public class CustomPushMessageListener extends PushMessageListener {

  @Override public void onHandleRedirection(Activity activity, Bundle payload) {
    super.onHandleRedirection(activity, payload);
    //callback for notification cleared. if you want to handle redirection then do not call super()
    // and add the redirection logic here.
  }
}

Check API Reference for more details.

Notification Cleared Callback

To receive a callback whenever a push is received override the onNotificationCleared() in the CustomPushMessageListener class created above.

class CustomPushMessageListener : PushMessageListener() {

  override fun onNotificationCleared(context: Context, payload: Bundle) {
    super.onNotificationCleared(context, payload)
    //callback for notification cleared.
  }
}
public class CustomPushMessageListener extends PushMessageListener {
  
  @Override public void onNotificationCleared(Context context, Bundle payload) {
    super.onNotificationCleared(context, payload);
    // callback for notification cleared.
  }
}

Check API Reference for more details.

Custom Action on Action Button Click

To use a custom action on Action Button click override the handleCustomAction() in the CustomPushMessageListener class created above.

class CustomPushMessageListener : PushMessageListener() {

  override fun handleCustomAction(context: Context, payload: String) {
    super.handleCustomAction(context, payload)
      // callback for notification custom action
  }
}
public class CustomPushMessageListener extends PushMessageListener {
  
  @Override public void handleCustomAction(Context context, String payload) {
    super.handleCustomAction(context, payload);
    // callback for notification custom action
  }
}

Check API Reference for more details.