Action categories

Overview

You can use categories to group multiple actions for a single notification. This allows you to present interactive notifications that provide multiple options when the notification is displayed. Users can perform an action from the notification itself without having to bring the application to the foreground.

For example, if you send a notification and add two actions that allow your users to confirm or cancel a reservation, your app could then send that response without requiring your user to open the app.

Dynamic action categories (iOS 10 or later)

Dynamic action categories are collections of mobile app message actions that are generated by the SDK in real-time when a special payload is received. This capability exists on iOS 10 and higher. There is no need to predefine dynamic action categories in the application binary.

You can define actions for dynamic action categories in the "category-actions" section of the payload. The payload includes the category-actions key, as well as a mutable-content flag in the normal app's payload. It can also include a category-name key if the name of the dynamic category must match a specific identifier. The category-name key is sometimes used for dynamic notification presentation.

• The mutable-content flag allows the application's notification service to process the push message before it is delivered to the user.
• The category-actions key includes a list of action buttons that are assigned to a temporary category at run time.
• The app key includes the text, sound, and badge of the notification.
• After the temporary category is created, the SDK assigns the category name to the notification and passes the category name to the operating system so that it can be displayed to the user.
• The category-name key overrides the random category name that is generated by the SDK with a category name that you specify. Add this key to your payload when you want to use iOS 10 (and later) features that require a predefined category name.

📘

Tip

Always include a notification-action value so a default action can be executed when the notification is opened. Category actions open only if a user expands the push message and selects an alternative action button.

{
	"category-actions": [
		{
			"name": "Vist our Website",
			"type": "url",
			"value": "https://acoustic.com"
		},
		{
			"name": "About us",
			"type": "url",
			"value": "https://acoustic.com/about"
		}
	],
	"notification-action": {
		"type": "url",
		"value": "https://acoustic.com"
	},
	"aps": {
		"alert": "Message",
		"sound": "default",
		"mutable-content": 1
	},
	"category-name": "content-extension"
}

Notification service dynamic action categories

The Mobile App Messaging SDK for iOS supports media attachments in notifications for iOS 10 (and later) applications. In iOS 10, Apple introduced the notification service extension that allows applications to intercept and pre-process remote notifications before they are presented to the user. When a user on an iOS 10 device receives a notification with a media attachment from the APNS service, the incoming notification is processed before it is displayed to the user.
First, the URL for the media attachment is extracted, and then the media file is downloaded and attached to the notification. Dynamic action categories are created in real-time by the SDK when a special payload is received, and background processing is enabled for the app. They are defined in the "category-actions" section of the payload and include standard action. You can use them with custom actions that you define by overriding those two predefined actions. The specific action is chosen by supplying a “type” key in either the “notification-action” or “category-actions” payload.

Static action categories (iOS 8 or later)

Static action categories are pre-defined in your app and cannot be changed except by updating the app itself. They are collections of buttons with actions behind them. You must implement them using the application:handleActionWithIdentifier:remoteNotification: API.

If you are using simple notifications and want to create static action categories with background actions, you must turn on Remote notifications in your XCode project. Go to the Background Modes section of the Capabilities tab for your target and select Remote notifications.

Create a static category

1. Specify the actions and labels for your notifications. The following code provides an example of this:

id acceptAction = [[MutableUserNotificationAction alloc] init];
[acceptAction setIdentifier: @"Accept"];
[acceptAction setTitle: @"Accept"];
[acceptAction setActivationMode: UIUserNotificationActivationModeForeground];
[acceptAction setDestructive: false];
[acceptAction setAuthenticationRequired: false];
id rejectAction = [[MutableUserNotificationAction alloc] init];
[rejectAction setIdentifier: @"Reject"];
[rejectAction setTitle: @"Reject"];
[rejectAction setActivationMode: UIUserNotificationActivationModeForeground];
[rejectAction setDestructive: false];
[rejectAction setAuthenticationRequired: false];

Class MutableUserNotificationCategory = NSClassFromString(@"UIMutableUserNotificationCategory");
id category = [[MutableUserNotificationCategory alloc] init];
[category setIdentifier: @"example"];
[category setActions:@[acceptAction, rejectAction] forContext: UIUserNotificationActionContextDefault];
[category setActions:@[acceptAction, rejectAction] forContext: UIUserNotificationActionContextMinimal];
            appCategories = [NSSet setWithArray: @[ category ]];

2. You then need to inform the OS to use the created categories:

UIUserNotificationSettings *settings = [UIUserNotificationSettings settingsForTypes:UIUserNotificationTypeBadge|UIUserNotificationTypeSound|UIUserNotificationTypeAlert categories:[appCategories]];

3. To handle the user interaction of these notifications you would need to Implement the standard method for handling the category callbacks in your AppDelegate class.

- (void)application:(UIApplication *)application handleActionWithIdentifier:(NSString *)identifier forRemoteNotification:(NSDictionary *)userInfo completionHandler:(void (^)())completionHandler
{
if(userInfo[@"aps"] && [userInfo[@"aps"][@"category"] isEqual: @"example"])

{ // perform action based on user interacting with the example category

4. Register the categories that you want to handle in the APNS registration call in your AppDelegate.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  if ([application respondsToSelector:@selector(registerUserNotificationSettings:)]) {
    UIMutableUserNotificationAction* acceptAction = [[UIMutableUserNotificationAction alloc] init];
    acceptAction.identifier = @"Accept";
    acceptAction.title = @"Accept";
    acceptAction.activationMode = UIUserNotificationActivationModeForeground;
    acceptAction.destructive = false;
    acceptAction.authenticationRequire = false;

    UIMutableUserNotificationAction* rejectAction = [[UIMutableUserNotification alloc] init];
    rejectAction.identifier = @"Reject";
    rejectAction.title = @"Reject";
    rejectAction.activationMode = UIUserNotificationActivationModeForeground;
    rejectAction.destructive = false;
    rejectAction.authenticationRequired = false;

    UIMutableUserNotificationCategory* category = [UIMutableUserNotificationCategory alloc] init];
    category.identifier = @"example";
    [category setActions:@[acceptAction, rejectAction] forContext: UIUserNotificationActionContextDefault];
    [category setActions:@[acceptAction, rejectAction] forContext: UIUserNotificationActionContextMinimal];

    UIUserNotificationSettings *settings = [UIUserNotificationSettings settingsForTypes: UIUserNotificationTypeBadge|UIUserNotificationTypeSound|UIUserNotificationTypeAlert categories: [NSSet setWithObject: category ] ];
    [application registerUserNotificationSettings:settings];
    [application registerForRemoteNotification];
  }
}

Your app now has all that it needs to show the notification to the user as well as perform an action based on the user’s selection. You now need to send a notification to the user using this category which we have just created. The sample app provided within the SDK has this static category already implemented for you to test.
To add the category to a push notification from your Acoustic Campaign instance, navigate to Development – Actions. At the bottom of this page you will see the input box for where categories are created. Click the New Category button to add the template to the page. The default category template will be created, you need to modify the ‘category’ key to match to what we have created.

For our example, the category would need to look like this.

{
  "label": "Example Category implemented in the sample app",
  "category": "example",
  "description": "Contains the Accept, Reject"
}

If you needed to add extra variables with this push you could use the custom properties sections as shown in the default category template.
Now when you are adding your actions to your iOS app message within the send experience you can select the category you want to use. Select the Add Category button.
You will now be presented with the available categories you have already created within your Acoustic Campaign instance. In our case we have the example and invitation categories. We will select the example category.
We also have the option of adding a simple action which will be used if a device does not support these types of notifications, i.e. those devices running iOS 7 and below.
This message will then be sent to your users when the app receives this message it will display the notifications as created in the static category.
You can also use this category in messages which are sent to the API. To use this category within an API call you can use the following payload:

{
  "aps": {
    "category": "example",
    "alert": "Message",
    "badge": 3,
    "sound": "default"
  }
}

Configuring iOS static action categories in Cordova

You can support iOS static action categories from your Cordova application by registering a callback for your category name with MCEPlugin.setCategoryCallbacks.
The callback includes the payload of the message and the identifier of the chosen action if an action was selected by the user. For more information about how each MCEPlugin method works, see MCEPlugin.js, which is included in the Cordova plug-in. For more information about how to implement Cordova with your app, see the sample project for examples.