iOS Action Buttons

Action buttons allow you to send push notifications with interaction beyond dismissing and opening your app, depending on their configuration they can silently send a response to your backend, without loading the app into the foreground or act as a deeplink into a specific area of your app.

In this recipe, we'll show you how you can mix and match both of these types of buttons along with the dynamically generated buttons that the Kumulos SDK can provide on-the-fly.

Our example will show a loyalty app for a popular Mexican grill sending notifications to handle a recurring order for a burrito.

Ingredients

This recipe assumes that you have an app in Kumulos configured to send push notifications and a build of the app on a test device with the SDK integrated, including the NotificationServiceExtension.

Recipe

This recipe consists of three parts.

• Configuring your iOS application with notification categories to handle the generation of buttons for fixed message types
• Triggering a push notification with the appropriate payload via the Kumulos UI or API
• Handling interactions with the notification in your app

Configuring your iOS application

By integrating the Kumulos SDK, including the NotificationServiceExtension, your app automatically supports dynamically adding action buttons to push notifications based on configuration you send with a notification, the only limitation with these action buttons is that they will all cause your app to be opened.

If you also want to configure your iOS application with a mix of background and foreground actions, or have a set of actions you would like to consistently add to a type of notification you must add these to your app code.

Note that if all of your interactions will involve opening the app you can skip this section and allow the SDK to handle all the action buttons dynamically.

iOS action buttons work by defining a category for notifications and adding an array of buttons to the category, as seen in the code snippet below.

let actionArray = NSMutableArray()

let quickOrderAction = UNNotificationAction(identifier: "quick-order", title: "Just my regular please!", options: .background)
let customiseOrderAction = UNNotificationAction(identifier: "customise-order", title: "I want to customize it!", options: .foreground)

actionArray.add(quickOrderAction)
actionArray.add(customiseOrderAction)

let orderFoodCategory = UNNotificationCategory(identifier: "orderFood", actions: actionArray as! [UNNotificationAction], intentIdentifiers: [],  options: .customDismissAction)

let categories = Set<UNNotificationCategory>()
categories.insert(orderFoodCategory)

UNUserNotificationCenter.current().setNotificationCategories(categories)

Using this configuration when a push notification is received with the category "orderFood" 2 buttons will be added to the notification by the app before it is presented, although both will trigger a callback to the same handler one will foreground the app while the other will remain in the background.

Triggering a push notification

We now have the option of sending a push notification by using the pre-defined category or by using the Kumulos action buttons.

Using the pre-configured category

From the UI this is as simple as opening the advanced tab and toggling on the Set Notification Category toggle then entering "orderFood" into the text box.

From a transactional API a sample request body might look like

{
  "target": {
    "segmentUuid": "loyal-customers"
  }​,
  "content": {
    "title": "Hi {user.firstName} its time for your free buritto"
    "message": "You usually order {user.favoriteOrder | a buritto}, would you like this to be ready at your usual time of {user.favoriteTime | 4pm}?"
  },
  "ios": {
      "category": "orderFood"
  }
}

Using the dynamically created action buttons

If you want a more ad-hoc creation of buttons that will all trigger the app to be foregrounded you could just define the actions in the notification payload, in the UI this just requires configuring the action buttons in the advanced tab.

From a transaction API call a sample request body would look like

{
  "target": {
    "userIds": ["customer-id-123"]
  }​,
  "content": {
    "title": "Hi {user.firstName} its time for your free buritto"
    "message": "You usually order {user.favoriteOrder | a buritto}, would you like this to be ready at your usual time of {user.favoriteTime | 4pm}?",
    "data": {
        "product":"chicken-burrito",
        "options": ["cheese","beans"]
    }
  }
  "buttons": [
    {
        "id": "quick-order"
        "text": "Just my regular please!"
    },
    {
        "id": "customize-order",
        "text": "I want to customize it!"
    }
  ]
}

Whichever way you decide to configure and send the buttons this completes the first half of the recipe, your users will be presented with a push notification along with the 2 buttons just waiting for some interaction!

Handling interactions with the notification in your app

The final step is to take the appropriate action within your app when the user presses one of the action buttons, this is accomplished by the push opened handler block.

 let builder = KSConfigBuilder(apiKey: "your-api-key", secretKey: "your-secret-key")
    .setPushOpenedHandler(pushOpenedHandlerBlock: { (notification : KSPushNotification) -> Void in
         if let action = notification.actionIdentifier {
            switch(action) {
            case "customize-order":
                let product = notification.data["product"]
                let options = notification.data["options"]

                MyDeepLinkService.openScreen('order-customization', withProduct: product, withOptions: options)
                break
            case "quick-order":
                MyOrderService.doQuickOrder()
                break
            default:
                //Noop.
                break
            }
        }
    })

Kumulos.initialize(config: builder.build())