Interactive Notifications

• Configure project to use interactive notifications
• Sending interactive notifications
• Mobile Originated (MO) messages
• Predefined categories
• Custom categories
  • System UI behaviour
  • Creating your own notification actions
  • Text input actions
• Notification action custom handling

The Interactive notifications released in version 2.6.9.

Interactive notifications are push notifications that provide an option for end user to interact with application through button tap action. This interaction can be accomplished by using Mobile Messaging SDK predefined categories or creating your own.

Each notification interaction category has a unique ID and contains a set of actions with their IDs. Actions may be set up with the following options (NotificationActionOptions):

• may bring the mobile app to foreground or leave it in background state
• may require device to be unlocked before performing (or not)
• may be marked as destructive (or not)
• may trigger MO message sending

Configure project to use interactive notifications

Оnly for App delegate composition approach of Mobile Messaging SDK integration:

1. Override method application:handleActionWithIdentifier:forRemoteNotification:completionHandler: in order Mobile Messaging SDK to be able to handle actions for remote notifications:

   func application(_ application: UIApplication, handleActionWithIdentifier identifier: String?, forRemoteNotification userInfo: [AnyHashable : Any], completionHandler: @escaping () -> Void) {
       MobileMessaging.handleActionWithIdentifier(identifier: identifier, forRemoteNotification: userInfo, responseInfo: nil, completionHandler: completionHandler)
   }

2. Override method application:handleActionWithIdentifier:for:completionHandler: in order Mobile Messaging SDK to be able to handle actions for local notifications:

   func application(_ application: UIApplication, handleActionWithIdentifier identifier: String?, for notification: UILocalNotification, completionHandler: @escaping () -> Void) {
       MobileMessaging.handleActionWithIdentifier(identifier: identifier, localNotification: notification, responseInfo: nil, completionHandler: completionHandler)
   }

Sending interactive notifications

Interactive notifications can be tested through our Single Push message and Multiple Push messages APIs by using category parameter.

Mobile Originated (MO) messages

With Mobile Messaging SDK you can send messages to arbitrary destinations from mobile device. These messages are also known as Mobile Originated (MO) messages. Actionable notifications are the obvious application for the MO service, meaning that you can trigger the MO message sending by any of notification actions, for instance, if user taps an "Accept" button, a specific MO message is sent to your backend service. In order to make a notification action to trigger the MO messages, you specify the NotificationActionOptions.moRequired option for the action:

let voteAction = NotificationAction(identifier: "vote",
                                         title: "Vote",
                                       options: [.moRequired])

Predefined categories

Mobile Messaging SDK provides only one predefined interaction category for now, but this list will be extended in future.

Displaying of Interactive Notifications with predefined categories can be tested without any additional implementation on application side through Push API.

A = action

Category.id	A.id	A.title	A.foreground	A.authenticationRequired	A.destructive	A.moRequired
mm_accept_decline	mm_accept	Accept	true	true	false	true
	mm_decline	Decline	false	true	true	true

Note

Mobile Messaging SDK provides localization for action button titles of predefined categories. Titles are localized for the following languages: Arabic, Czech, Danish, German, English, Spanish (Latin America), Spanish, Finnish, French, Hebrew, Croatian, Hungarian, Indonesian, Italian, Japanese, Korean, Malay, Norwegian, Dutch, Polish, Portuguese (Portugal), Portuguese, Romanian, Russian, Slovak, Swedish, Thai, Turkish, Vietnamese, Chinese (Simplified), Chinese (Traditional), Hindi.

Custom categories

Setting up custom categories enables you to configure interactive notification categories along with their actions.

System UI behaviour

For the alert-style, maximum of four (4) actions are shown in the default notification mode. If there are more than four action objects provided, the system displays only the first four.

For the banner-style, notifications (on iOS 8-9) the system shows up the first two actions only.

Actions are displayed in the order they've been set.

Creating your own notification actions

Use unique identifiers for your categories and actions, keeping in mind that mm_ prefix is reserved for all predefined IDs and cannot be used for your custom categories and actions identifiers.

In order to create a custom category, first instantiate its actions:

//Action with title "Cancel", which will be marked as destructive and will require device to be unlocked before proceed
let cancelAction = NotificationAction(identifier: "cancel",
                                      title: "Cancel",
                                      options: [.destructive, .authenticationRequired])!

//Action with title "Share", which will require device to be unlocked before proceed and will bring application to the foreground
let shareAction = NotificationAction(identifier: "share",
                                     title: "Share",
                                     options: [.foreground, .authenticationRequired])!

let shareCategory = NotificationCategory(identifier: "category_share_cancel", actions: [_shareAction, _cancelAction])!

In case of App delegate composition approach of Mobile Messaging SDK's integration, call the withInteractiveNotificationCategories: method within the constructor chain while starting the Mobile Messaging SDK session:

MobileMessaging
    .withApplicationCode(<#application code#>, notificationType: <#notification types#>)?
    .withInteractiveNotificationCategories([shareCategory]) // registers notification categories
    .start()

In case of App delegate inheritance approach of Mobile Messaging SDK's integration, override the interactiveNotificationCategories in your App Delegate:

override var interactiveNotificationCategories: Set<NotificationCategory>? {
    return customCategories
}

Preview of interactive notifications on iOS 9 and iOS 10

Text input actions

Starting from iOS 9.0 it is possible to create notifications with a text input field. Such notifications are typically used in chat and messaging applications. In order to display notification with text input field you need to register a NotificationCategory with TextInputNotificationAction:

let replyAction = TextInputNotificationAction(identifier: "reply_action",
                                              title: "Reply",
                                              options: [],
                                              textInputActionButtonTitle: "Send",
                                              textInputPlaceholder: "Message")!

let chatMessageCategory = NotificationCategory(identifier: "chat_message",
                                               actions: [replyAction],
                                               options: nil,
                                               intentIdentifiers: nil)!

MobileMessaging
    .withApplicationCode(<#application code#>, notificationType: <#notification types#>)?
    .withInteractiveNotificationCategories([chatMessageCategory]) // registers notification categories
    .start()

In order to handle the text input action, please take a look on Notification action custom handling.

Additionally, only for App delegate composition approach of Mobile Messaging SDK integration:

1. Override method application:handleActionWithIdentifier:forRemoteNotification:withResponseInfo:completionHandler: in order Mobile Messaging SDK to be able to handle actions for remote notifications:

   func application(_ application: UIApplication, handleActionWithIdentifier identifier: String?, forRemoteNotification userInfo: [AnyHashable : Any], withResponseInfo responseInfo: [AnyHashable : Any], completionHandler: @escaping () -> Void) {
       MobileMessaging.handleActionWithIdentifier(identifier: identifier, forRemoteNotification: userInfo, responseInfo: responseInfo, completionHandler: completionHandler)
   }

2. Override method application:handleActionWithIdentifier:for:completionHandler: in order Mobile Messaging SDK to be able to handle actions for local notifications:

   func application(_ application: UIApplication, handleActionWithIdentifier identifier: String?, for notification: UILocalNotification, withResponseInfo responseInfo: [AnyHashable : Any], completionHandler: @escaping () -> Void) {
       MobileMessaging.handleActionWithIdentifier(identifier: identifier, localNotification: notification, responseInfo: responseInfo, completionHandler: completionHandler)
   }

Notification action custom handling

In order to implement your own logic for handling of notification action:

1. Implement MessageHandlingDelegate protocol and it's method didPerform(action:forMessage:completion:), i.e.:

   class MyMessageHandlingDelegate : MessageHandlingDelegate {
       func didPerform(action: NotificationAction, forMessage message: MTMessage, completion: @escaping () -> Void) {
           // handle text input action
           if #available(iOS 9.0, *), let textInputAction = action as? TextInputNotificationAction {
               // text input action happened, handle the text that user has input
               print("user responded with text \(textInputAction.typedText)")
           }
           
           // handle a tap on notification alert
           if action.isTapOnNotificationAlert {
               // users tap on the notification alert detected, handle it here
               print("user tapped on notification \(message.text)")
           }
   
           // handle any other actions that are nor text input or tap, i.e. custom notification action:
           if action.identifier == "action_try_new_product" {
               // users tap on the custom notification action button detected, handle it here
           }
           
           // don't forget to call `completion`, it's very important to tell the system that action handling is finished
           completion()
       }
   }

2. Pass the delegate object to MobileMessaging SDK:

   MobileMessaging.messageHandlindDelegate = MyMessageHandlingDelegate()