This document describes how to work with in-app messages and Mobile Inbox without Iterable's mobile SDKs.
The steps described in this document are relevant only if your app does not use one of Iterable's mobile SDKs, which do these things automatically. For more information, take a look at Iterable's iOS SDK and Android SDK.
Table of contents
Fetching in-app messages
To send in-app messages, Iterable places them in a user-specific queue where they
wait for an app to download and display them. Mobile apps can download this queue's
messages by calling
at strategic moments (when the app comes to the foreground, when users navigate
to a particular screen, etc.). Then, they can display the messages as necessary.
This API always returns non-selective in-app messages sent broadly to your
project's users. If you'd also like to retrieve selective in-app messages sent to
a particular app, include its
platform in the request.
The in-app message queue contains three kinds of messages:
- New in-app messages that are not inbox-enabled (after a user views these messages and closes them, they should not be available in the mobile inbox)
- New inbox-only in-app messages (which never appear to the user unless they are selected in the inbox)
- Previously displayed messages that have been closed and now reside in the inbox
To differentiate between these messages, your app should inspect message metadata and locally track which ones have already been displayed.
After fetching in-app messages, track their delivery by calling
(for each new message). Be careful not to call this endpoint a second time for
any previously delivered message (that still comes back from the API because it
was saved to the mobile inbox), since you don't want to create multiple delivery
events for the same message/user/device combination.
Displaying in-app messages
To display an in-app message to a user, present its HTML in a web view or use its metadata to create a custom, native rendering. Be sure to pay attention to scaling, positioning, scrolling, etc.
When displaying an in-app message (either when it arrives or when a user selects
it in the mobile inbox), track an in-app open
event by calling
This also marks the message as read.
If the displayed message is not inbox-enabled, "consume" (remove) it from the
server queue by calling
When displaying an in-app message without Iterable's mobile SDKs, you'll need to set up click handlers to respond to taps on buttons or links contained in the message content. These click handlers should correctly respond to the following types of URLs:
- External content (visible in another app or on the web)
- Deep links (content in the same app)
- Dismiss actions (which close the message)
- Delete actions (which delete an inbox-enabled message from the server queue)
When responding to these taps, call the following APIs as necessary:
- To delete an inbox-enabled message from the server queue (so that it is no longer
shown in the inbox), call
POST /api/events/inAppConsume. If you provide a
deleteActionto this API call, Iterable will also capture an in-app delete event.
- To track an in-app click
event when a user taps on a button or link, call
- To track an in-app close
event when a user closes an in-app message, call
Displaying a custom mobile inbox
To display a mobile inbox without using the UI provided by Iterable's mobile SDKs, fetch the in-app messages from the server queue and render them in the way that makes most sense for your app. As described in the previous sections, be sure to use Iterable's API to capture events as users open, interact with, and delete them.
Syncing a mobile inbox across many devices
Iterable's iOS and Android SDKs automatically sync a mobile inbox across all the devices on which a user has logged in to your app. Additionally, they sync the read state for each message.
If you're not using one of Iterable's mobile SDKs:
- To determine whether or not a message has been read, examine its
readfield, as returned by
- To mark a message as read, call
For more information about cross-device read state syncing, see:
- Iterable's Android SDK, v3.2.12 release notes
- Iterable's iOS SDK, v6.2.21 release notes
Event types supported only by Iterable's mobile SDKs
Iterable's mobile SDKs capture two types of events that cannot be captured manually:
- Inbox session_ events, which track how long a mobile inbox was open during a single session.
- Inbox message impression events, which track how many times a message was visible in the mobile inbox (shown as an item in the list) during a single session.
Please sign in to leave a comment.