Overview

In Acoustic Campaign, marketers can enhance their mobile app messages by adding actions. They can guide their customers to a certain path by asking them to complete a certain action. The actions added to the messages are defined by developers in the Acoustic Campaign UI. The type of action defined in the UI is mapped to plugins in the app or to the base Campaign SDK. The SDK then initiates the action based on the type received in a notification, and the customer is directed to the respective path.

Types of actions

Acoustic Campaign provides several built-in actions and plugins for additional custom actions. You can also customize the provided plugins to add actions or write your own custom action plugins.

Standard actions

The Standard actions are provided by Acoustic and are built-in the Campaign product. They are available in the UI for developers to create these actions. The following are the Standard actions provided:

  • Open app
  • Open dialer
  • Open URL
  • Show in-box notification

Acoustic Campaign also provides plugins for additional custom actions. Install the plugins and register the actions. You can also Register an action through a JSON file.

πŸ“˜

Tip

For Android, registering the action through JSON is preferred.

πŸ“˜

Note ( iOS only)

When you use the 'MceNotificationActionRegistry.registerNotificationAction' method to register a notification action, the registered callback function is called whether the app is running in the foreground or the background. After the app is terminated, the method is not called for the action provided. To enable the app to react to notification action when the app is not running, use the JSON configuration file method.

Wallet (Passbook) plugin

The Wallet plugin allows a push notification to add a pass to the Wallet on the device.

Install the Wallet (Passbook) plugin

To add the Wallet (Passbook) action,

  1. Go to Mobile > Developer Resources > Actions from the left navigation menu.
  2. From the Actions page, scroll to the iOS actions text area and click New Action.
  3. From the dropdown, select Wallet menu, and the template code is automatically added to the iOS actions text area.
  4. Click Save in the top right of the screen before leaving the page.

Enable the Wallet action template

The following example shows how to register the plugins in your AppDelegate method for iOS:

  1. Create a registerPlugins method in the AppDelegate class if one does not already exist.
  2. In the registerPlugins method, add the following code to register the Wallet plugin. The registerPlugins method should be called in the AppDelegate didFinishLaunchingWithOptions method.

🚧

Note:

You must have initialized the SDK before registering the Wallet plugin in AppDelegate.

@implementation AppDelegate - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [self registerPlugins]; // ... } -(void)registerPlugins { [AddToWalletPlugin registerPlugin]; // ... } @end
class AppDelegate: UIResponder, UIApplicationDelegate { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication. LaunchOptionsKey : Any]? = nil) -> Bool { registerPlugins() // ... } func registerPlugins(){ AddToWalletPlugin.register() // ... } }

Send an API push with Wallet support

To send a push notification with a Wallet pass, send the following to your payload.

πŸ“˜

Note:

The following payload is for the push/sends API (/channels/push/sends).

{ "channelQualifiers": [ "apxxxxxxxxx" ], "content": { "simple": { "apns": { "aps": { "alert": { "title": "Wallet", "subtitle": "subtitle here", "body": "subtitle here" } }, "notification-action": [ "name": "Wallet", "type": "passbook", "value": { "url": "URL TO THE .PKPASS FILE FOR THE WALLET TO USE" } ] } } }, "contacts": [ { "channel": { "qualifier": "apxxxxxxxxx", "destination": "wwwwww|yyyyyy" } } ], "campaignName": "Test Push Notifications" }

Where:

  • 'xxxxxxxxx' – is the value for the channelQualifiers in the payload. Replace it with your specific appKey.
  • 'wwwwww|yyyyyy' – is the destination value in the payload. Replace it with your specific values for userId and channelId.

To install the Wallet plugin, run the following command

npm install --save <sdk folder>/plugins/react-native-acoustic-mobile-push-wallet

πŸ“˜

Note:

The plugin is available only for iOS platform.

To register the plugin:

  • Import the Acoustic mobile wallet module to your React component:
import { NativeModules, Platform } from 'react-native'; const { // Other Native Modules... RNAcousticMobilePushWallet, } = NativeModules;
  • Add plugin registration using WalletAction value after the component is mounted.
componentDidMount() { if (Platform.OS == 'ios') { // Enable other plugins registration... RNAcousticMobilePushWallet.registerPlugin("WalletAction"); } }

Send an API push with wallet action support

To send a push notification with a wallet push notification action, send the following to your payload.

{ "campaignName": "iOS Simple Push", "pushes": [ { "userId": "{{userId}}", "simpleMessages": [ { "appKey": "{{appKey}}", "channelId": "{{channelId}}", "content": { "aps": { "alert": { "title": "Wallet/Passbook", "subtitle": "Test push notification", "body": "Push payload body" }, "sound": "default" }, "notification-action": { "name": "Wallet", "type": "passbook", "value": { "url": "https://acoustic-demo.s3.us-east-2. amazonaws.com/Acoustic.pkpass" } } } } ] } ] }

Where you must update the {{userId}},{{appKey}}, and {{channelId}} values to match the values in your environment.

To install the Wallet plugin, run the following command

cordova plugin add <path to downloaded directory>/plugins/co.acoustic. mobile.push.plugin.passbook cordova prepare

πŸ“˜

Note:

The plugin is available only for iOS platform.

To register the plugin:

@implementation AppDelegate - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [self registerPlugins]; // ... } -(void)registerPlugins { [AddToWalletPlugin registerPlugin]; // ... } @end

Send an API push with wallet action support

To send a push notification with a wallet push notification action, send the following to your payload.

{ "campaignName": "iOS Simple Push", "pushes": [ { "userId": "{{userId}}", "simpleMessages": [ { "appKey": "{{appKey}}", "channelId": "{{channelId}}", "content": { "aps": { "alert": { "title": "Wallet/Passbook", "subtitle": "Test push notification", "body": "Push payload body" }, "sound": "default" }, "notification-action": { "name": "Wallet", "type": "passbook", "value": { "url": "https://acoustic-demo.s3.us-east-2. amazonaws.com/Acoustic.pkpass" } } } } ] } ] }

Where you must update the {{userId}},{{appKey}}, and {{channelId}} values to match the values in your environment.

Action Menu plugin

The Action Menu plugin allows a push notification to display a menu of provided actions on tap. The provided actions can be any of the other plugins supported by the SDK (e.g. Dial, Display Web, Open App, etc.). Once a menu item is tapped, the action will be performed.

Install the Action Menu plugin

To add the Action Menu action,

  1. Go to Mobile > Developer Resources > Actions from the left navigation menu.
  2. From the Actions page, scroll to the iOS actions text area and click New Action.
  3. From the dropdown, select Action Menu, and the template code is automatically added to the iOS actions text area.
  4. Click Save in the top right of the screen before leaving the page.

When you create an Action Menu message, you must first add the Action Menu action to your message. After that, you can add any action that you would like to appear as an item in the action menu.

For example:

  1. Add the Action Menu action to your message first.
  2. Add a Dial action
  3. Add an Open App action.
  4. Add an Open URL action.

In your push notification, you will see that the notification shows a menu with the three actions (Dial, Open, URL) that each performs an action when tapped.

Enable the Action Menu action template

The following example shows how to register the plugins in your AppDelegate method for iOS:

  1. Create a registerPlugins method in the AppDelegate class if one does not already exist.
  2. In the registerPlugins method, add the following code to register the Action Menu plugin. The registerPlugins method should be called in the AppDelegate didFinishLaunchingWithOptions method.

🚧

Note:

You must have initialized the SDK before registering the Action Menu plugin in AppDelegate.

@implementation AppDelegate - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [self registerPlugins]; // ... } -(void)registerPlugins { [ActionMenuPlugin registerPlugin]; // ... } @end
class AppDelegate: UIResponder, UIApplicationDelegate { func registerPlugins(){ ActionMenuPlugin.register() // ... } func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication. LaunchOptionsKey : Any]? = nil) -> Bool { registerPlugins() // ... } }

Send an API push with Action Menu action support

To send a push notification with an action menu, send the following to your payload. Each action in the category-actions section of the payload can be interchanged with any of the action plugins supported by the SDK. The maximum amount of actions in a single payload is 10.

πŸ“˜

Note:

The following payload is for the push/sends API (/channels/push/sends).

{ "channelQualifiers": [ "apxxxxxxxxx" ], "content": { "simple": { "apns": { "aps": { "alert": { "title": "Action Menu", "subtitle": "subtitle here", "body": "subtitle here" } }, "notification-action": { "name": "Action Menu", "type": "showactions" }, "category-actions": [ { "name": "Open App", "type": "openApp" }, { "name": "Dial", "type": "dial", "value": "8456084889" }, { "name": "Display Web", "type": "displayWebView", "value": { "url": "https://www.google.com" } } ] } } }, "contacts": [ { "channel": { "qualifier": "apxxxxxxxxx", "destination": "wwwwww|yyyyyy" } } ], "campaignName": "Test Push Notifications" }

Where:

  • 'xxxxxxxxx' – is the value for the channelQualifiers in the payload. Replace it with your specific appKey.
  • 'wwwwww|yyyyyy' – is the destination value in the payload. Replace it with your specific values for userId and channelId.

To install the Action menu plugin, run the following command

npm install --save <sdk folder>/plugins/react-native-acoustic-mobile-push-action-menu

πŸ“˜

Note:

The plugin is available only for iOS platform.

To register the plugin:

  • Import the Acoustic mobile push action menu module to your React component:
import { NativeModules, Platform } from 'react-native'; const { // Other Native Modules... RNAcousticMobilePushActionMenu, } = NativeModules;
  • Add plugin registration using ActionMenuAction value after the component is mounted.
componentDidMount() { if (Platform.OS == 'ios') { // Enable other plugins registration... RNAcousticMobilePushActionMenu.registerPlugin("ActionMenuAction"); } }

Send an API push with action menu action support.

To send a push notification with an action menu push notification with the following three actions: open app, dial, and display web; send the following to your payload.

{ "campaignName": "iOS Simple Push", "pushes": [ { "userId": "{{userId}}", "simpleMessages": [ { "appKey": "{{appKey}}", "channelId": "{{channelId}}", "content": { "aps": { "alert": { "title": "Action Menu", "subtitle": "Test push notification", "body": "Push payload body" }, "sound": "default" }, "notification-action": { "name": "Action Menu", "type": "showactions" }, "category-actions":[ { "name": "Open App", "type": "openApp" }, { "name": "Dial", "type": "dial", "value":"1234567899" }, { "name": "Display Web", "type": "displayWebView", "value": { "url": "https://www.google.com" } } ] } } ] } ] }

Where you must update the {{userId}},{{appKey}}, and {{channelId}} values to match the values in your environment.

To install the Action menu plugin, run the following command

cordova plugin add <path to downloaded directory>/plugins/co.acoustic. mobile.push.plugin.action-menu cordova prepare

πŸ“˜

Note:

The plugin is available only for iOS platform.

To register the plugin:

@implementation AppDelegate - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [self registerPlugins]; // ... } -(void)registerPlugins { [ActionMenuPlugin registerPlugin]; // ... } @end

Send an API push with action menu action support

To send a push notification with an action menu push notification action, send the following to your payload.

{ "campaignName": "iOS Simple Push", "pushes": [ { "userId": "{{userId}}", "simpleMessages": [ { "appKey": "{{appKey}}", "channelId": "{{channelId}}", "content": { "aps": { "alert": { "title": "Action Menu", "subtitle": "Test push notification", "body": "Push payload body" }, "sound": "default" }, "notification-action": { "name": "Action Menu", "type": "showactions" }, "category-actions":[ { "name": "Open App", "type": "openApp" }, { "name": "Dial", "type": "dial", "value":"1234567899" }, { "name": "Display Web", "type": "displayWebView", "value": { "url": "https://www.google.com" } } ] } } ] } ] }

Where you must update the {{userId}},{{appKey}}, and {{channelId}} values to match the values in your environment.

Text input action plugin

You can create and send notifications that prompt users for text. When the user receives the input notification, the user clicks an action that expands and displays a text input field. After the user enters text into the field, the notification is canceled.

Android N devices and Android M (and lower devices) require different implementations for text input notifications. For Android N devices, you implement text input notifications by using the input notification action type in an expandable notification action. For Android M devices (and lower), you implement a retrieval mechanism that receives text inputs and cancels the notification.

Android N devices

Create an input notification action by overriding 'co.acoustic.mobile.push.sdk.api.notification. MceNotificationAction' with the following code, which extends 'co.acoustic.mobile.push.sdk.api.notification.MceNotificationAction.Handling' with the direct reply:

public void handleAction(Context context, String input, String type, String name, String attribution, Map payload, boolean fromNotification);

Android M (and lower) devices

  1. Implement co.acoustic.mobile.push.sdk.api.notification.MceNotificationInput and return an instance in the following method:
public MceCustomNotificationInput getCustomInput();
  1. Configure the following method to retrieve the text input and call the action when the user clicks the action.
public void createCustomInput(Context context, String type, String name, String attribution, Map payload)

To install the Text input plugin, run the following command

npm install --save <sdk folder>/plugins/react-native-acoustic-mobile-push-textinput

πŸ“˜

Note:

The plugin is available only for Android platform.

πŸ‘

Registration

The plugin registration is already completed in the Acoustic plugin code.

Send an API push with text input action support.

To send a push notification with a text input action, send the following to your payload.

{ "campaignName": "Android Simple Push", "pushes": [ { "userId": "{{userId}}", "simpleMessages": [ { "appKey": "{{appKey}}", "channelId": "{{channelId}}", "content": { "alert": { "subject": "Testing Text Input", "message": "Push payload body", "type": "textinput", "notification-action": { "name": "Text Input", "type": "textinput" } } } } ] } ] }

Where you must update the {{userId}},{{appKey}}, and {{channelId}} values to match the values in your environment.

Custom actions

You can customize the plugins provided to create custom actions or create custom action plugins. You can create your own custom action notification implementation for new action types. Custom action notifications override the predefined action types in the SDK, such as dial, URL, and openApp.

Custom action methods are defined by the developer and run when an action is selected by the user with the registered type value. An example of this would be for the developer to create a method that handles viewProduct action types. The developer registers that method with the MCEActionRegistry system. Then, a push message comes in with the "notification-action" set to type="viewProduct", and the app user opens the mobile app message.

Requirements for custom action types

When a custom action type for a mobile app message is used, the marketer must also include the destructive, authentication, and foreground keys in the action definition.

The "aps" section is used for system displayed notifications.

The {{type}} of action can be anything. Predefined action types include "dial" and "url". If the {{type}} is "rich", "dial", or "url", then the destructive is false, authentication is false, and foreground is true; otherwise, those attributes need to be included.

The {{value}} depends on the type of action. If the type is "dial", then the value is a phone number to be dialed. If the type is "url", then the value is the url that is to be viewed. If the type is "rich", then the value is the rich content ID to be displayed. When the type is anything else, it is handled by the plug-in that is defined for that type.

The {{name}} of the action is the title that shows on the button. If the {{type}} is not "rich", "dial", or "url", the following keys need to be defined in the action:

  • {{destructive}} can be either true or false. This sets the style of the action button.

  • {{authentication}} can be either true or false. This allows actions to be performed with the device is locked when true.

  • {{foreground}} can be either true or false. If it is true, then the app is opened when a selection is made. If it is false, then the app is not opened.

Create custom actions

The iOS SDK provides three custom actions that you can implement:

  • Custom action using a single argument type payload
  • Custom action using an action payload and a full iOS payload
  • Custom action for text entry fields

The following example shows implementing a custom action using a single argument type. You can customize your dynamic action category types by registering your object and selector with the MCEActionRegistry class. See the following code example:


-(instancetype)init { if(self=[super init]) { MCEActionRegistry * registry = [MCEActionRegistry sharedInstance]; [registry registerTarget: [self sharedInstance] withSelector:@selector(customAction:) forAction: @"customAction"]; } return self; ]

When a notification is opened with the customAction type, your custom method is run.


-(void)customAction:(NSDictionary*)action { // Do something neat with the action payload here! }

Example of custom action using an action payload and full iOS payload. This custom action is demonstrated in the Action Menu plug-in in the sample app. The following code sample shows how to register the custom action.


MCEActionRegistry * registry = [MCEActionRegistry sharedInstance]; [registry registerTarget: [self sharedInstance] withSelector: @selector(executeAction:withPayload:) forAction: @"custom"];

The following code shows how to implement the custom action.


-(void)executeAction:(NSDictionary*)action withPayload:(NSDictionary*)payload { // the action dictionary contains the action that is being executed, eg: {"type": "custom", "value":"foo"} // the payload dictionary includes the full APNS payload, e.g. {"aps": {...}} }

You can create your own custom action notification implementation for new action types. Custom action notifications override the pre-defined action types in the SDK, such as dial, url, and openApp.

  1. To create a custom action notification, you must implement co.acoustic.mobile.push.sdk.api.notification.MceNotificationAction.
    
    
    import co.acoustic.mobile.push.sdk.api.notification.MceNotificationAction public class MyCustomAction implements MceNotificationAction { /** * This method is called when a notification action is clicked. * @param context The application context * @param type The notification action type * @param name The notification action name (can be null) * @param attribution The notification attribution (can be null) * @param payload The notification payload. The map contains the key value pairs from the notification action payload. * @param fromNotification true if this action is called from a notification and false otherwise */ public void handleAction(Context context, String type, String name, String attribution, Map payload, boolean fromNotification) { // your implementation here } /** * Initiates the action with the given options * @param context The application's context * @param initOptions The initialization options */ public void init(Context context, JSONObject initOptions){ // your implementation here } /** * Updates the action with the given options - not is use yet * @param context The application's context * @param updateOptions The update options */ public void update(Context context, JSONObject updateOptions) { // your implementation here } /** * This method is called when a notification with this action as its main action. If it returns false, the notification will not be shown. * This can be used in case there are preparations needed before the notification can be shown. * @param context The application's context * @param notificationDetails The received notification * @param sourceBundle The bundle that contained the notification * @return true to show the notification and false to not show it */ public boolean shouldDisplayNotification(Context context, NotificationDetails notificationDetails, Bundle sourceBundle) { // your implementation here } }
  2. To register your custom action for a specific type, add the following code.
    
    
    import co.acoustic.mobile.push.sdk.api.notification.MceNotificationActionRegistry MceNotificationActionRegistry.registerNotificationAction("snooze", new MyCustomAction());

Action plugins can be used to extend the behavior executed when a message is interacted with. Push messages, InApp messages and Inbox messages all use actions to define what happens when a user interacts with them. You can register your own action handlers written in javascript using the registerAction function. (See the send-email-action.js in the sample application for an example).

Custom actions can also be written in javascript:


import {NativeEventEmitter} from 'react-native'; import {RNAcousticMobilePushActionHandler} from 'NativeModules'; const emitter = new NativeEventEmitter(RNAcousticMobilePushActionHandler); export default function demonstrationAction(details) { // details.action contains the specific action payload ie {"type": "demonstration", "value": "acoustic"} // details.payload contains the entire push payload ie { "aps": { "alert": "test" }, "notification-action": {"type": "demonstration", "value": "acoustic"} } // You can place code here to use the values in those payloads to perform work on behalf of the user } // The registerAction call tells the SDK that you intend to handle actions of this type. In addition the function passed will be called for any missed actions received while your code was not running. RNAcousticMobilePushActionHandler.registerAction('demonstration', demonstrationAction); // The listener call allows this function to be called when actions arrive emitter.addListener('demonstration', demonstrationAction);

To include custom actions in your application, you must put them in a space-separated list in the custom actions key in the config.xml file. After that, you can register for callbacks to those actions through the MCEPlugin.setRegisteredActionCallback function. The callback includes both the action payload and the entire push payload for processing that action.

Register custom action callback

You have to register a callback with one or two arguments, the action, and the payload, for a specific custom action using the following:

MCEPlugin.setRegisteredActionCallback(callback, customActionName);

The following is an example of how to register the callback for the custom action:

MCEPlugin.setRegisteredActionCallback(function (action, payload) { const elem = document.getElementById('title'); const newText = action['value']; elem.innerText = newText; }, 'customUrl');

To create a custom action, you must pass user input through a register() function and send it to the SDK. The Flutter SDK then registers it as a custom action.

  1. Import the following packages.
import 'package:flutter/material.dart'; import 'package:flutter_acoustic_mobile_push/flutter_acoustic_sdk_push.dart';
  1. Create local variable:
var value = CustomActionValue();
  1. Add the registerCustomAction function to send the data to the SDK.
Future<void> registerCustomAction(String actionType) async { value.registerCustomAction(actionType); value.registeredEvent.subscribe((args) { var data = args!.changedValue; print('registering'); print(data); setState(() { statusValue = data; }); }); }
  1. The register function then passes the user input data to the registerCustomAction function.
register() { _yourFormKeyHere.currentState?.save(); if (_customActionType == null) { return Text(statusValue, style: TextStyle(color: labelColor)); } else { registerCustomAction("CoolAction"); } }

In the example above, we are creating and registering a custom action called "CoolAction".

  1. To unregister a custom action, add the unregister function. The unregister function then passes the user input data to the unregisterCustomAction function.
Future<void> unregisterCustomAction(String actionType) async { value.unregisterCustomAction(actionType); value.unregisiteredEvent.subscribe((args) { var data = args!.changedValue; setState(() { statusValue = data; }); }); }

πŸ“˜

Note:

The register function must be tied to a register button or inkwell widget that is used to save the user input when the clicked or the tap action is performed.

For more information about registerCustomAction functionality, see
flutter_acoustic_sdk_push.dart

Override Actions

You can override actions and replace an old action with a new one. If you assigned a key to the actionType and did not use the default key to map the action to the SDK, you must first unregister the key and then assign a new one.

  1. Add the unregisterCustomAction function from the SDK.
Future<void> unregisterCustomAction(String actionType) async { value.unregisterCustomAction(actionType); value.unregisteredEvent.subscribe((args) { var data = args!.changedValue; setState(() { statusValue = data; }); }); }
  1. Add the unregister function.
unregister() { _yourFormKeyHere.currentState?.save(); unregisterCustomAction(_customActionType); }
  1. After unregistering the action type, you should now be able to register a new action type and override/update the key for the map (value) of the previous action.
    For more information, see