Overview

In addition to the standard actions that are provided by Acoustic Campaign, developers can define custom actions and add these actions to mobile app messages. For example, you can define a custom action that opens a special product detail page for customers with loyalty IDs or opens a customer's abandoned cart. To help you define your own custom actions, Mobile App Messaging provides an "example" template that you can modify. The template demonstrates how to implement a custom action that prints a payload. Follow the instructions in this tutorial to modify the "example" template to create your own custom action.

Prerequisites

Before you begin, ensure that the following prerequisites are met:

You have an account with Acoustic Campaign
You downloaded the sample app and SDK
You properly configured your client app so that it can receive and display mobile app messages

1. Create a class for your custom action plug-in.

To create a class for your custom action plugin-in, you can modify the "ExamplePlugin.h" and "ExamplePlugin.m" files that are provided as part of the "example" template in the sample app. Rename the files for your plug-in and update the performAction: method, shown below, to perform the action that you want your custom action to perform. The performAction: method is located in the ExamplePlugin.m file. When a payload for this plug-in type is received, the performAction: method is executed.

For example, if you are creating a custom action that opens the mobile user's abandoned cart, you might rename the files to CartPlugin.h and CartPlugin.m.

-(void)performAction:(NSDictionary*)payload
{
//get the dictionary which contains the custom properties defined in the action
    NSDictionary *customProperties = [payload objectForKey:@"value"];
   
    if (customProperties) {
           //Get custom properties. These properties correspond to the ones created in the action
           NSNumber *openForActionValue = [customProperties objectForKey:@"openForAction"];
           NSNumber *sendEventValue = [customProperties objectForKey:@"sendCustomEvent"];
       //send custom metric to server
           if ([sendEventValue boolValue]) {
                   MCEEvent * event = [[MCEEvent alloc] init];
                   //name and attributes must be updated, but type needs to be custom since we are sending a custom event
                   [ event fromDictionary:@{ @"name":@"examplePluginActionTaken", @"type":@"custom",
                       @"timestamp":[NSDate date], @"attributes":@{@"customData1":openForActionValue, 
                       @"customData2":sendEventValue}}];
                   [[MCEEventService sharedInstance] addEvent: event immediate: FALSE];
           }
           //send payload to screen
           if ([openForActionValue boolValue]) {
                   ExampleViewController * viewController = [[ExampleViewController alloc] initWithPayload: payload];
                   UIViewController * controller = MCESdk.sharedInstance.findCurrentViewController;
           [controller presentViewController:viewController animated:TRUE completion:nil];
       }
           //send payload to log
           else {
               NSLog(@"Payload is:%@", payload);
           }
    }
}

2. In the AppDelegate's init method, add your custom action plug-in to the list of import statements.

For example, to add the custom action plug-in for the "example" custom action plug-in, add #import "ExamplePlugin.h", as shown in the following code sample.

// Action Plugins
#import "ActionMenuPlugin.h"
#import "AddToCalendarPlugin.h"
#import "AddToPassbookPlugin.h"
#import "SnoozeActionPlugin.h"
#import "DisplayWebViewPlugin.h"
#import "TextInputActionPlugin.h"
#import "ExamplePlugin.h" // add this line

// MCE Inbox Plugins
#import "MCEInboxActionPlugin.h"
#import "MCEInboxPostTemplate.h"
#import "MCEInboxDefaultTemplate.h"

// MCE InApp Plugins
#import "MCEInAppVideoTemplate.h"
#import "MCEInAppImageTemplate.h"
#import "MCEInAppBannerTemplate.h"

3. In the AppDelegate's init method, register the custom action plug-in.

For example, to register the "example" custom action plug-in, add [ExamplePlugin registerPlugin]; as shown in the following code sample.

// MCE Inbox plugins
    [MCEInboxActionPlugin registerPlugin];
    [MCEInboxPostTemplate registerTemplate];
    [MCEInboxDefaultTemplate registerTemplate];
       
    // MCE InApp Plugins
    [MCEInAppVideoTemplate registerTemplate];
    [MCEInAppImageTemplate registerTemplate];
    [MCEInAppBannerTemplate registerTemplate];
       
    // Action Plugins
    [ActionMenuPlugin registerPlugin];
    [AddToCalendarPlugin registerPlugin];
    [AddToPassbookPlugin registerPlugin];
    [SnoozeActionPlugin registerPlugin];
    [DisplayWebViewPlugin registerPlugin];
    [TextInputActionPlugin registerPlugin];
    [ExamplePlugin registerPlugin]; // add this line

4. Configure the custom action in Acoustic Campaign.

In Acoustic Campaign, configure the action to send the appropriate fields. Follow these steps:

Open Acoustic Campaign and go to Development > Actions. The Actions window opens.
In the iOS actions box, click the New action button and then select Custom action. The following code is added to the iOS actions box:

{
        		"label": "Custom action",
        		"type": "custom",
        		"destructive": false,
        		"description": "Opens the product detail page for the product specified for this push",
        		"customProperties": [
        			{
        				"id": "hasLoyaltyId",
        				"inputRequired": true,
        				"type": "boolean",
        				"placeholder": "Does the customer have a loyalty ID?",
        				"value": true
        			},
        			{
        				"id": "greeting",
        				"inputRequired": true,
        				"type": "string",
        				"placeholder": "Greeting",
        				"value": "hello world"
        			},
        			{
        				"id": "productId",
        				"inputRequired": true,
        				"type": "number",
        				"placeholder": "product id",
        				"value": 1234
        			},
        			{
        				"id": "recipients",
        				"inputRequired": false,
        				"type": "object",
        				"placeholder": "",
        				"value": [
        					"[email protected]",
        					"[email protected]"
        				]
        			}
        		],
        		"authenticationRequired": false,
        		"activationMode": true
        	},

Customize the action by updating the code in the iOS actions box.

Ensure that the action type corresponds to the forAction: value in the registerPlugin method in the ExamplePlugin.m file. For example, the example template uses "example" for the forAction: value, as shown in the code sample below, and for the action "type".

+(void)registerPlugin
            {
             MCEActionRegistry * registry = [MCEActionRegistry sharedInstance];
             [registry registerTarget: [self sharedInstance] withSelector:@selector(performAction:)
             forAction: @"example"];
            }

Update the custom properties for your custom action. For information about action custom properties, see https://help.goacoustic.com/hc/en-us/articles/360044166273-Create-and-set-up-mobile-app-message-templates.

The following code shows how the code is updated for the "example" action that is defined in the template.

{
   "label":"Example action",
   "type":"example",
   "description":"Prints all the details about push",
   "customProperties":[
      {
         "id":"sendCustomEvent",
         "inputRequired":true,
         "type":"boolean",
         "placeholder":"Send custom event to server?",
         "value":true
      },
      {
         "id":"openForAction",
         "inputRequired":true,
         "type":"boolean",
         "placeholder":"Open view controller?",
         "value":true
      }
   ]
}

Save the action.

5. Add the custom action to mobile app messages.

After the developer creates the custom action, the marketer can add the action to mobile app messages by following these steps:

In Acoustic Campaign, go to Content > Create Mobile App Message. The Set up your message window opens.
Configure a Simple message type for iOS. In the iOS content window, add the custom action to the message by clicking the Add action button. The Action window opens.
Select the custom action and click Select action. The Action window closes, and the Set up your message window displays the parameters for the custom action.
Configure the action and then complete the configuration for the mobile app message. You can either send, schedule, or publish the message.

Expected outcome

By following the steps in this tutorial, you modified the custom action "example" template to create your own custom action.