Creating Embedded Message Templates

You've defined your placements, added them to your Iterable project, designed message interfaces for them, and updated your mobile apps and websites to display messages using those interfaces.

Now, the fun part: creating and testing an embedded message template!

# In this article

# Permissions

To work with embedded message templates in Iterable, you'll need these permissions:

# Creating a template

First, you'll need to create an embedded message placement in your Iterable project. Without a placement, you can't create a template or a campaign. For more information, read Defining Placements for Embedded Messages.

Embedded message templates are similar to other Iterable templates. However, each embedded message template must be associated with a placement. Placements define the fields for which the template should provide data, how many buttons the template should display, where it displays in the app or website, and more.

For example, you might define a carousel placement called "Home screen messages" in your Iterable project, and give it various features: a title, a body, a media URL, a default action, and two buttons. Then, you'll create a template for that placement that has these properties defined for a specific campaign.

To create a template for a placement, follow these steps:

1. Go to Content > Templates, and click New Template > Embedded.

2. Enter a name for the template, choose an existing placement where the template displays, and click Create Template.

3. On the template configuration page, enter values for the various configuration options required of the template by its placement.

   NOTE

   Like other kinds of templates in Iterable, embedded message templates support locales.

   • Title – A text string that displays at the top of the message. There is no character limit enforced. Work with your developer to determine the best length for your title, which can vary by placement.

   • Body – A text string that provides the body of the message. There is no character limit enforced. Work with your developer to determine the best length for your body, which can vary by placement.

   • Media URL – (optional) An image URL to display in the message. Must use HTTPS. Work with your developer to determine the best image size and format for your placement.

     TIP

     To see image guidelines for out-of-the-box views, read Out-of-the-Box Views for Embedded Messages.

   • Data feeds - (optional) Connect the template to a data feed to fetch data for the message. Check the box to select an existing data feed from the dropdown, or click Add a new data feed to create a new data feed.

     • Cache Data Feed Response - (optional) When using data feeds, check this box to cache the response from the data feed for up to 1 hour. This reduces the number of requests to the data feed and improves performance.

   • Custom Text Fields - (optional) These are present when the placement has text fields enabled. Provide a value for each text field that will be displayed in the message. For example, you could use Handlebars expressions to display the value of a user's firstName and lastName fields.

   • Open Action - (optional) This is the action that occurs when the user taps the message itself. This turns the embedded message into a functional button that can be tapped to open a URL or perform a custom action (select one).

   • Action Buttons - (optional) You can add one or two buttons that display in the message. Each button can be assigned a URL or custom action (select one).

     • Button Name – A text string that displays the button text. By default, Iterable labels the buttons as "Button 1" and "Button 2". If these were customized in your placement, those names will be displayed here. If you need to change the button name, click the pencil icon to edit the button name.
     • Button Action - Select either Open URL or Custom Action to define the action that occurs when the user taps the button.
     • Identifier – A unique identifier for the button for event tracking.

   Buttons and default actions can be assigned URLs or deep links. Custom actions (such as action://joinClass/1) trigger specific functionality in your app.

As configured, the template looks like this:

# Open URLs

Available for Open Action and Button Action.

When the user taps the embedded message container or button, the URL will be opened in the app. The URL can be a deep link or a regular URL. These are handled by your app's URL handler.

To learn about URL handling for your platform, read:

• Define a URL Handler for Android SDK
• Define a URL Handler for iOS SDK
• Handle URLs in the Web SDK

# Custom actions

Available for Open Action and Button Action.

Custom actions are a way to trigger specific functionality in your app when the user taps the embedded message container or button. Custom actions are defined in your app.

To learn more about custom actions for your platform, read:

• Define a Custom Action Handler for Android SDK
• Define a Custom Action Handler for iOS SDK
• Handle Custom Actions in the Web SDK

# Closing, dismissing, or hiding an embedded message

Some types of actions are unavailable for embedded messages. For example, you can't use custom actions to close or dismiss the message like you can with in-app messages.

Alternatively, you can use one of the following tactics to end the display of an embedded message campaign:

• Set an expiration date for the campaign (simplest, but not dismissable by the end-user).

• Create a solution that changes the eligibility criteria for the user so they are removed from the campaign. Then, the next time the page is refreshed (or via mobile defaults, automatically via silent push) the user's message array would just no longer return that campaign.

  To do this, you'll need to make a user profile or list update by either:

  • Directly posting user profile updates using the SDK or API that triggers when a button is tapped.

  • Creating a custom action in your app that tracks a custom event in Iterable when a button is tapped. Then, create a journey in Iterable that is triggered by that custom event, and performs a user profile update or list update that removes the user from the campaign eligibility criteria in some manner (user profile field update, or list membership update).

# Testing a template

After creating a template, it's a good idea to test it. By testing, you can verify that the content of your template comes across as you expect, and that your apps are display it properly.

While editing a template, test it by clicking Display Test Message and choosing one of these options:

• To Yourself

  • In email-based projects, activates a test embedded message to the email address of the signed-in Iterable user, regardless of whether there is an Iterable user profile identified by that email.

  • In userID-based projects, activates a test embedded message to an Iterable user profile whose email field matches the email address of the signed-in Iterable user (since Iterable users sign in by email, not userId). If no such user profile exists, an error message displays. If multiple such user profiles exist (this can happen because email is not an identifier in userID-based projects), one and only one of them will receive the test message.

  • In hybrid projects, activates a test message to the Iterable user profile whose email matches the email address of the signed-in Iterable user (since Iterable users sign in by email, not userId). If no such user exists, an error displays.

• To an Internal List – Activates a test embedded message to each Iterable user profile included on a selected internal list. (Internal lists are defined on the Audience > Lists page.)

• To Another Address – Activates a test embedded message to various user profiles you enter after selecting this option.

  • In email-based projects, you can provide one or many email addresses, regardless of whether or not they identify existing Iterable user profiles.

  • In userID-based projects, you can provide one or many userId values that identify existing Iterable user profiles. If any provided userId does not identify an existing Iterable user profile, you'll see an error, and that userId won't receive the message — but valid profiles will.

  • In hybrid projects, you can provide one or many email and userId values that identify existing Iterable user profiles. If any provided userId or email does not identify an existing Iterable user profile, you'll see an error, and that userId or email won't receive the message — but valid profiles will.

# Verifying a test message

There are a couple of ways to verify the test message:

• Query Iterable's API to fetch all embedded messages available for the test user. Then, verify that the test message is present in the response. And, while you're there, inspect the API response to get a sense of the data payload Iterable uses when sending an embedded message to your apps.

• Sign in to your app or website as the test user, navigate to the placement associated with the message, and make sure everything looks right. This will only work if you've already updated your app or website to display embedded messages.

# API verification

To verify that your test message is available for your test user, you can use a mobile or web API key for your Iterable project to manually call the same API endpoint that your apps call to fetch embedded messages.

Calling this API can give you confidence that your test message is available for apps to download. It can also help you (and your engineers) develop an understanding of the precise data payload Iterable sends for an embedded message.

For example, to fetch embedded messages for test user user@example.com, you'd call:

GET /api/embedded-messaging/messages?email=user@example.com

For the test message described above, the response would be similar to:

{
  "placements": [
    {
      "placementId": 141,
      "embeddedMessages": [
        {
          "metadata": {
            "messageId": "",
            "placementId": 141,
            "isProof": true
          },
          "elements": {
            "title": "Summer Sale - Up to 50% Off!",
            "body": "Discover amazing deals on summer essentials. Shop now and save!",
            "mediaUrl": "https://example.com/400/300",
            "buttons": [
              {
                "id": "shopNowButton",
                "title": "Shop Now",
                "action": {
                  "type": "openUrl",
                  "data": "myapp://products/sale"
                }
              },
              {
                "id": "viewDealsButton",
                "title": "View Deals",
                "action": {
                  "type": "openUrl",
                  "data": "myapp://deals"
                }
              }
            ],
            "text": [],
            "defaultAction": {
              "type": "openUrl",
              "data": "myapp://sale"
            }
          },
          "payload": {}
        }
      ]
    }
  ]
}

# Verifying your test message in your app or website

You can also have the test user view the message in an app or on a website that is configured to display messages for that placement.

For example, here's the test message from above, rendered in an iOS app, using an out-of-the-box banner view (included in Iterable's iOS SDK) with no styling adjustments. In this case, the test user (user@example.com) has signed in to the app and navigated to the screen that displays messages associated with the "Home screen message" placement:

# Want to learn more?

To learn more about templates in Iterable, read Templates Overview.

# Next steps

Before creating an embedded message campaign, you'll need to define its audience. To learn how, read Defining Eligibility Lists for Embedded Messages.