Handling foreground push notifications

Control what happens when a mobile push notification is received in the foreground

It is important to define the right behavior for the situation when a push notification is received in foreground. You don't want to interrupt the user workflow, but still be delivering important information to the user.

Normally you have 3 options on how to handle a push notification received in the foreground:

  • Show the OS style notification
  • Show a custom dialog
  • Ignore the notification

The default behavior on iOS is to ignore notification.
The default behavior Android is to show the OS style notification. You can find information on how to change it below.

iOS

The default behavior in iOS is to not show notifications in the foreground with alert, sound and badge. If you want to show notifications in the foreground, you could do the following:

XPush.registerForegroundNotificationOptions { (message: XPMessageResponse) in
        return [.alert, .badge, .sound]
}
[XPush registerForegroundNotificationOptions:^XPNotificationType(XPMessage *message) {
    return XPNotificationType_Alert | XPNotificationType_Sound | XPNotificationType_Badge;
}];

If you have different types of messages in your app you might want to implement a different behavior for each. This can be achieved by using the following logic inside the function:

XPush.registerForegroundNotificationOptions { (message: XPMessageResponse) in

    if x.message.data?["showMessage"] != nil {
        return [.alert, .sound, .badge]
    }

    return []

}
[XPush registerForegroundNotificationOptions:^XPNotificationType(XPMessage *message) {
    If (message.data[@"type"] == @"article") {
        return XPNotificationType_Alert | XPNotificationType_Sound | XPNotificationType_Badge;
    }
    return XPNotificationType_None;
}];

The method described above (registerForegroundNotificationOptions) is designed to define the behavior for the default iOS notifications. In order to implement the custom behavior (like custom dialogs) you should use another method called message response handler:

XPush.registerMessageResponseHandler { (response: XPMessageResponse) in

    if response.action.type == .present {
        // Logic when message received in foreground
    }
               
}
[XPush registerMessageResponseHandler:^(XPMessageResponse *response) {
    if (response.action.type == XPActionType_Present) {
        // Logic when message received in foreground
    }
}];

After showing a custom dialog you can programatically proceed with the message click action (e.g. open URL) when user clicks a button:

XPush.click(response.message)
[XPush clickMessage:response.message actionIdentifier:nil]];

You can also track the message as clicked without running any actions (e.g. open URL):

XPush.reportMessageClicked(response.message)
[XPush reportMessageClick:response.message actionIdentifier:nil]];

Find a complete example below:

// Show OS notifications in foreground
XPush.registerForegroundNotificationOptions { (message :XPMessageResponse) in
    return [.alert, .sound, .badge]
}


// Register custom message handler
XPush.registerMessageResponseHandler { (response: XPMessageResponse) in
      
        if response.action.type == .present {
            // Show an article dialog with "View" button
            self.showArticleDialog(response.message, clickCallback: {
               XPush.clickMessage(response.message)
            })
        }
        
}
// Show OS notifications in foreground
[XPush registerForegroundNotificationOptions: ^XPNotificationType(XPMessageResponse *response) {
        return XPNotificationType_Alert | XPNotificationType_Sound | XPNotificationType_Badge;
}];

// Register custom message handler
[XPush registerMessageResponseHandler: ^(XPMessageResponse * _Nonnull response) {        
        if (response.action.type == XPActionType_Present) {
            // Show an article dialog with "View" button
            [self showArticleDialog: response.message viewButtonCallback: ^{
                // Process message click
                [XPush clickMessage:response.message actionIdentifier:nil];
            }];
        }
    }];

Android

In android, when initialising PushConnector, you can set the behaviour for foreground notifications by setting .setShowForegroundNotifications() to either true or false (the value by default is true). If set to false, notifications won't show while your app is in the foreground, unless you specifically call mPushConnector.showNotification().

new PushConnector.Builder(XPUSH_APP_KEY, GOOGLE_PROJECT_NUMBER)
        .setShowForegroundNotifications(false)
        .create(this);

Now when a message is received you can choose how you want to handle it. To do this you will be using the messageResponseReceived callback (see here for more details).

@Override
public void messageResponseReceived(Message messagePayload,
                                    HashMap<String, String> responsePayload,
                                    WeakReference<Context> uiReference) {

    if (responsePayload.get("responseType").equals("present")) {
        
    }
}

Some of the useful functions you can use are:

  1. showNotification(). To show the push notification:
mPushConnector.showNotification(messagePayload);
  1. clickMessage(). Parameters are message and the action of that message to click. If set to null, the default action of the notification will be used. So if the message has a click action of Open URL, *the URL will open in the phone's browser.
mPushConnector.clickMessage(messagePayload, null);
  1. reportMessageClicked. Parameters are the message to report as clicked, and the action to report as clicked (should be null if not using interactive notifications).
mPushConnector.reportMessageClicked(messagePayload, null);
  1. reportMessageDismissed. Parameters are the message to report as closed, and the action to report as closed (should be null if not using interactive notifications)
mPushConnector.reportMessageDismissed(messagePayload, null);