Articles in this section

Sending In-App Messages

Avatar
Brad
  • Updated
Follow

This document describes how to use Iterable to send in-app messages. In-app messages can optionally make use of a mobile inbox, if you have enabled one in your app.

NOTE

To learn more about in-app messages and Iterable's Mobile Inbox feature, read In-App Messages and Mobile Inbox.

Table of contents

Setting up Iterable's mobile SDKs

Before sending in-app messages, have your mobile engineers add Iterable's iOS SDK and Android SDK to your mobile apps and configure them to work with in-app messages.

NOTE

It is possible for your apps to receive in-app messages without the SDKs, but using the SDK simplifies the implementation.

Configuring your app to include Mobile Inbox

Before sending an in-app message that users can save to a mobile inbox, you must configure your apps to support the Mobile Inbox feature. To do this, have your mobile engineers follow the instructions in Setting up Mobile Inbox on iOS and Setting up Mobile Inbox on Android.

Iterable's iOS and Android SDKs include a default mobile inbox UI for you to use in your apps. This default interface can be customized and stylized as necessary.

Creating and sending an in-app message campaign

To send in-app messages to your users, follow these instructions:

1. Create a new campaign

Campaign details

First, create a new campaign:

  • Navigate to Messaging > Campaigns and click Create New Campaign.

  • Specify various campaign details:

    • Provide a Campaign Name.

    • Choose whether or not to use a custom conversion metric.

    • Add labels, as necessary.

    • For Campaign Type, choose Blast or Triggered.

    • For Message Medium, select In-App.

    • For a blast campaign, choose send and suppression lists.

  • Click Continue to Templates.

2. Select whether to create or edit a template

Template list

Then, select an existing template or choose to create a new one:

If there's an existing base template that you'd like to use for the in-app message campaign, select it and click Continue to Design. Otherwise, click Create a New Template.

If you're creating a new template, you'll be prompted to select an editor. To learn about the differences between these editors, read Template Editor Overview.

3. Configure the In-App Template tab

In-App Template tab

Configure the options on the the In-App Template tab:

  • Show in Inbox

    Enabling this toggle does two things:

    • Enables the template editor's Mobile Inbox-related options
    • Causes the in-app message to be displayed in your app's mobile inbox

    While you're editing the template, use the Inbox toggle button at the top of the preview to view how the message will look in a user's mobile inbox.

  • Template Name

    The name of the template, so you can reference the same template in later campaigns (if necessary).

  • Message Type

    The message type to associate with the campaign. For more information, read Message Channels and Message Types Overview.

  • Expiration Time

    The last time that an in-app message can be viewed or will be listed in the app's inbox.

    By default, in-app messages expire 24 hours after a campaign is sent. That is, if a mobile app does not retrieve an in-app campaign from Iterable within 24 hours of when it was sent, the recipient will never see it. However, this field makes it possible to specify a custom in-app message expiration time.

    Click the calendar icon on the Expiration Time input to bring up a calendar control. Use this control in one of two ways:

    Selecting a date for in-app expiration

    • Set a specific expiration time

      Use the calendar to select a specific expiration date (in the local time zone of the web browser making the selection). Select a month and day, then select an hour, then select a minute.

      The expiration date for an in-app message can be up to 90 days in the future.

    • Set a relative expiration time

      Use the relative date text input on the bottom of the calendar control to choose an expiration date relative to the campaign send date. Use the following syntax:

      • y: years
      • M: months
      • w: weeks
      • h: hours
      • m: minutes
      • s: seconds
      • Examples:
        • [send time]+3h+14m+7d: 3 hours, 14 minutes, 7 days after send time
        • [send time]+1M+1w: 1 month and 1 week after send time
        • [send time]/d+3d: 3 days after midnight on the day of send time

    WARNING

    If a specific or relative expiration date falls before a campaign's send date, users will not receive the in-app message.

  • Title in Inbox

    As users scroll through their inboxes, titles help them understand what each message contains. Titles can be up to three lines long, at which point they truncate with an ellipsis. The title is not visible after the user opens the message.

  • Body in Inbox

    Message bodies provide further descriptive text about the content of a message. They can be up to three lines long, at which point they truncate with an ellipsis. The Body in Inbox is distinct from the actual message body.

  • Thumbnail in Inbox

    By default, each inbox message displays a thumbnail image on the right-hand side of its item in the list. Iterable crops the image to a 1:1 aspect ratio, so it's best to provide content that can be presented in this way.

  • Deliver Silently to Inbox

    This option sends the message directly to an app's mobile inbox without first showing it to the user. To read the message, users will need to open the inbox and select it.

  • Display Type

    • Dictates how the message will display on a user's device. Bottom, Center and Top cause messages to cover only a portion of the screen,and leave a portion of the background showing.
    • Vertical space rendered when using the Bottom, Center and Top options depends on the amount of content in the template.
    • A scroll bar will appear on the right side of a message if its content exceeds the height of the screen.

  • Custom Payload (Optional)

    Any data you would like to send from Iterable to your application in the background (formatted as JSON).

4. Configure the Advanced Options tab

On the Advanced Options tab, configure the following settings:

  • Enable Template Generation Using Data Feeds

    Data feeds allow Iterable to include data retrieved from an external API in the content of a message. To learn more, read Rendering Templates with Data Feeds.

  • Enable Template Generation Using Data Feeds > Merge the Data Feed and User Contexts

    • Enables the use of double curly braces (for example, {{example}}) to reference data feed data.
    • If this option is disabled, use double square brackets (for example, [[example]]) to reference data feed data.
    • With this option enabled, you can continue to reference user profile data with double curly braces, too. If the data feed and user profile contain data with the same name, the user profile data takes precedence.

5. Specify the template's content

Back on the In-App Template tab, use the template editor to configure the template's content.

The device preview shown above the template editor updates each time you save the in-app message template while building it (it does not update as you type). Use the Preview drop-down menu to select a device on which to preview the in-app message.

Mobile apps run on devices having various screen sizes and in different orientations. When using the WYSIWYG editor, use HTML that scales dynamically and is pinned to the edges of the screen (when it makes sense to do so).

For information about how to add buttons to your in-app messages (for closing the message, deleting it or navigating to specific content), read Buttons and links.

6. Send yourself a preview of the message

Send Proof button

After having your mobile engineers configuring your mobile app to display in-app messages (by setting up the SDK or writing custom code), use the Send Proof button to send yourself a preview. Proofs send to the specified user in all apps associated with the project.

Alternatively, use the Preview With Data button, which renders the in-app message in the browser. This option will render any Handlebars expressions in the template with user profile data from a user of your choosing.

When you are done editing the template, click Save & Continue to Review.

7. Review and launch the campaign

On the Review & Launch screen:

  • To send the campaign immediately, click Send Campaign Right Now.
  • To schedule the campaign for later, click Schedule Campaign for Later.

In-app messages should contain links and buttons that allow users to navigate to content on the web or in the app, trigger custom actions in the app or simply close the message.

Every in-app message must contain at least a single link or button so that the user has a way to close it. If an in-app message template does not have a link or button with a valid URL, Iterable's template editor displays an error when you try to save it.

A valid URL takes one of the following forms:

  • Web URL

    For example, https://www.example.com/sample/content

  • Custom action

    For example, action://customActionName, where customActionName is the name of any custom action supported by your mobile app's custom action handler. If you omit customActionName (leaving only action://), tapping the button or link will simply close the in-app message.

    WARNING

    Earlier versions of the SDK used itbl:// URLs for custom actions. The SDK still supports itbl:// URLs, but they're deprecated and support will eventually be removed. Migrate to action:// as it's possible to do so.

  • Iterable action

    For example, iterable://actionName, where actionName is the name of a pre-defined action supported by Iterable's SDK. For example, to create a delete button/or link, use URL iterable://delete. To create a close button/link, use URL iterable://dismiss.

Example in-app message buttons

Consider the following in-app message template, shown as it's being edited in Iterable:

Sample in-app message

  • The Close button might be associated with URL iterable://dismiss, which would simply close the message.
  • The View Feature button might be associated with URL action://feature, which would tell the app to invoke the custom action triggered by feature.
  • The Go To Home Screen button might be associated with URL action://home, which would tell the app to invoke the custom action triggered by home.

X-style close buttons

Circle close button

If you'd like to create an X-style close button, one option is to use the Bee Free editor with a configuration similar to the following:

  • Add a button to the message template
  • Set the button's text to X
  • Set the button's URL to action://, which will close the in-app message when tapped
  • Choose a Background Color for the button
  • Choose a Text Color for the button
  • For Align, choose right
  • Specify a Border Radius of 20
  • For Content Padding, specify:
    • 0 for Top and Bottom
    • 10 for Left and Right
  • Specify a Solid, 1-pixel border of any desired color.

Events for in-app messages and Mobile Inbox

To learn about in-app message and Mobile Inbox events, read Events for In-App Messages and Mobile Inbox

Further reading

User guides:

Developer documentation:

Related articles

Comments

0 comments

Article is closed for comments.