HomeUser GuideDeveloper GuideChangelog
Developer Guide

Custom Templates

Our in-app messaging templates are open-source, which means you can modify them, delete them, or create your own. The Leanplum dashboard will reflect your new templates the next time you run your app and sync the templates.

Once the templates are created or customized, they can be synced with Leanplum, just like Variables, by running the app in Development mode on a registered test device. The process of customizing these templates differs slightly depending on the platform:

iOS custom templates

To define a new template, use the method:

[Leanplum defineAction:ofKind:withArguments:withOptions:presentHandler:dismissHandler]

Leanplum.defineAction(name:kind:args:options:present:dismiss:)

Here's how it works:

  • defineAction: The name of the action or message type you are defining.
  • ofKind: One or more action kinds OR'ed together. kLeanplumActionKindMessage (.message) will appear in the Message Type list for creating message campaigns. kLeanplumActionKindAction (.action) will appear in the dropdown when choosing an action within a message.
  • withArguments: A list of LPActionArg (ActionArg) objects, with each one being an argument that the marketer can fill out on the dashboard. For example, Title, Message Text, or Color. Action argument names need to end with lowercase action, for example Accept action. The Action arguments can be of type:
    • String
    • Number
    • Boolean
    • Color
    • File
    • Array
    • Dictionary
    • Action
  • presentHandler: A block that accepts an LPActionContext (ActionContext) and returns a BOOL whether the action was handled or not. You may decide not to handle the action based on some additional logic defined in the responder. From the context, you can access the values for any argument you defined in the template, as well as some other special methods:
  • [LPActionContext onActionDismissed] You must call this method when your message template has been dismissed.
  • dismissHandler: A block that will be called in a request to dismiss your message template.
    Such occasions occur rarely, for example, when a user opens a notification that needs to present an in-app message, but your message template is already presented and it must be dismissed in order to present the notification's payload.

📘

In order for the in-app message to be shown on every trigger/preview, make sure to call context.actionDismissed() method in the present handler. Otherwise, the queue believes the message is still presented and will not present any other messages.

Actions and tracking

In the responder, you can call the following methods to track and/or run message actions or track message associated events.

  • [LPActionContext runActionNamed:]: Runs an action, for example, Open URL. The action name should correspond to a named LPActionArg of kind Action.
  • [LPActionContext runTrackedActionNamed:]: Runs an action and tracks an event that the action occurred. The event is tracked in the context of the message with the name of the action.
  • [LPActionContext track:withValue:andParameters:]: Tracks an event associated with the current message.

Example of events tracked using runTrackedActionNamed:

iOS sample project: custom template

👍

Updated sample projects for Swift and Objective-C

The samples can be found in this Github repo

In the sample, we are adding a new in-app message template — specifically, a three-button Confirm message (Alert based).

Check where the "#### example" comments are placed — you'll find the code parts being added to create the new in-app message template and comments describing each code part being added.

//#### example Call to Leanplum.defineAction
        Leanplum.defineAction(name: Name,
                              kind:  .message,
                              //#### example Define the arguments for the template, configurable from the Dashboard
                              args: [
                                ActionArg.init(name: TitleArg, string: TitleVal),
                                ActionArg.init(name: MessageArg, string: MessageVal),
                                ActionArg.init(name: AcceptStr, string: AcceptStr),
                                ActionArg.init(name: CancelStr, string: CancelStr),
                                ActionArg.init(name: LaterArg, string: LaterVal),
                                ActionArg.init(name: AcceptActionArg, action: nil),
                                ActionArg.init(name: CancelActionArg, action: nil),
                                ActionArg.init(name: LaterActionArg, action: nil)],
                              present: presentHandler,
                              dismiss: dismissHandler)

[Leanplum defineAction:Name
                    ofKind: kLeanplumActionKindMessage | kLeanplumActionKindAction
             //#### example Define the arguments for the template, configurable from the Dashboard
             withArguments:@[
                 [LPActionArg argNamed:TitleArg withString:TitleVal],
                 [LPActionArg argNamed:MessageArg withString:MessageVal],
                 [LPActionArg argNamed:AcceptStr withString:AcceptStr],
                 [LPActionArg argNamed:CancelStr withString:CancelStr],
                 [LPActionArg argNamed:LaterArg withString:LaterVal],
                 [LPActionArg argNamed:AcceptActionArg withAction:nil],
                 [LPActionArg argNamed:CancelActionArg withAction:nil],
                 [LPActionArg argNamed:LaterActionArg withAction:nil],
             ]
             presentHandler:presentHandler,
             dismissHandler:dismissHandler];

Next, build and run the project. If the device is registered as a Test Device, the 3-button Alert message template will be added to the available in-app templates in the Dashboard. You may also have to hit the 'sync templates' button in the dashboard to see the final template.

Once the custom message template is synced, it will show up in the In-app message templates to choose from.

Setup the message content and actions and preview it to see how it appears on the device.

Preview on the registered test device in Dev mode.

Android custom templates

To define a new template, use the method:

Leanplum.defineAction(name, kind, args, presentHandler, dismissHandler)

Here's how it works:

  • name: The name of the action or message type you are defining.
  • kind: One or more action kinds OR'ed together. Leanplum.ACTION_KIND_MESSAGE will appear in the Message Type list for creating message campaigns. Leanplum.ACTION_KIND_ACTION will appear in the dropdown when choosing an action within a message.
  • args: An ActionArgs instance, defining the options that the marketer can fill out on the dashboard. For example, Title, Message Text, or Color. Action argument names need to end with lowercase action, for example Accept action.
  • presentHandler: A callback that accepts an ActionContext and returns a boolean whether the action was handled or not. You may decide not to handle the action based on some additional logic defined in the responder. From the context, you can access the values for any argument you defined in the template, as well as some other special methods:
    • ActionContext.actionDismissed() You must call this method when your message template has been dismissed.
    • ActionContext.runActionNamed(): Runs another action when this action is done. The action name should correspond to a named action argument defined within ActionArgs.
    • ActionContext runTrackedActionNamed(): Runs another action and tracks an event that the action occurred.
    • ActionContext.track(): Tracks an event associated with the current action.
    • ActionContext.muteFutureMessagesOfSameKind(): Don't show the current message campaign again on this device. For example, if you have a survey popup every 10th session, you may want the ability for the user to decide to remind them later, which simply dismisses the message, or the option to never see this survey again.
  • dismissHandler: A callback that will be called in a request to dismiss your message template.
    Such occasions occur rarely, for example, when a user opens a notification that needs to present an in-app message, but your message template is already presented and it must be dismissed in order to present the notification's payload.

Starting from SDK version 5.5.0 you can use more convenient way to define action or template:

//Uses kind=Leanplum.ACTION_KIND_ACTION when defining the action
MessageTemplates.registerAction(MessageTemplate, Context)

//Uses kind=Leanplum.ACTION_KIND_MESSAGE|Leanplum.ACTION_KIND_ACTION
//when defining the template
MessageTemplates.registerTemplate(MessageTemplate, Context)

The difference between both is the kind parameter when defining the action. The MessageTemplate interface represents the parameters of the Leanplum.defineAction(name, kind, args, presentHandler, dismissHandler) method. Check its methods:

//Returns the name of the action to register.
String getName();

//Creates the user-customisable options for the action.
ActionArgs createActionArgs(Context context);

//Called in response to the registered action.
//Use it to show your message to the user.
boolean present(ActionContext context);

//Called in request to dismiss your message template.
boolean dismiss(ActionContext context);

Android sample project: custom template

👍

Updated sample project for Android

The samples can be found in this Github repo

In this sample we are implementing several new In-App messages:

  • Three-button Confirm message
  • Slider message
  • Request App Rating action

Check the Github home page for more details on each new message type.