Skill Level: Any

This article provides information on default actions, register action types, and custom action requirements for mobile app messages.


Not what you’re looking for? Check out all our available tutorials for mobile app messaging here.




  1. Default actions for mobile app messages

    Your app users can choose two predefined actions in response to a notification being opened or a specific action being chosen from a dynamic action category message you create.

    The three standard, or predefined, actions are:

    • url – opens Safari for the website that is specified in the “value” key.
    • dial – opens a dialer to call the number that is specified in the “value” key. Tip: You must have iCloud set up on both devices to use “dial.” If you dial on an iPad, nothing happens unless you set up iCloud. If you test with an app without iCloud, the dialer does not show.
    • openApp – opens the app.

    The default standard actions, such as url, dial, and openApp, can be overridden by a custom plug-in. In fact, this is specifically what WebActionPlugin does. It takes over the default action of opening a URL in Safari and instead opens the page in a WebView in the app.

    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 actions. 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.

    Remember: All actions, default and custom, send a Universal Behavior (UB) to the Acoustic Campaign servers.

    Adding a deep link for a url action

    You can add a deep link that is tied to a url action or through a custom action.

    1. Integrate the iOS SDK with a deep link sample app.
    2. Set up the deep linking schema.
    3. Send a mobile app message with a url type that activates your schema.

    {"aps": {
    "alert":"Testing.. (3)",
  2. Register action types

    You can plug in to action handling by registering your own actions, or custom actions. You can register for handling any action type, and you can override the default handling of any predefined type.

    Custom actions 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. Additionally, both custom actions and standard actions (url, dial, openApp) can be within the “category-actions” section of the payload, which would run in response to a user selecting the specific button that is attached to the action.

    There are two types of dynamic action category plug-ins: the Action Menu plug-in and the Web Action plug-in. The Action Menu plug-in displays a list of available actions as the target of an action. It registers with the showactions dynamic action type. The Web Action plug-in overwrites the url dynamic action type with the ability to display the specified web page in the app instead of opening it in Safari.

    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

    Example: 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:

     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.

     // Do something neat with the action payload here!

    Example: 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": {...}}
  3. 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.

Expected outcome

Need more help? Check out all of our available tutorials for mobile app messaging here.


Join The Discussion

Your email address will not be published. Required fields are marked *