In-App Messages Without the SDK

This document describes how to work with in-app messages and Mobile Inbox without Iterable's mobile SDKs.

# In this article

# 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 GET /api/inApp/getMessages 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.

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 POST /api/events/trackInAppDelivery (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 POST /api/events/trackInAppOpen. This also marks the message as read.

If the displayed message is not inbox-enabled, "consume" (remove) it from the server queue by calling POST /api/events/inAppConsume.

# Handling clicks

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 deleteAction to 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 POST /api/events/trackInAppClick
• To track an in-app close event when a user closes an in-app message, call POST /api/events/trackInAppClose.

# 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 read field, as returned by GET /api/inApp/getMessages.
• To mark a message as read, call POST /api/events/trackInAppOpen.

# 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.