In-App Messages

In-app messages are notifications that appear inside of your app. Use them to engage with users as they browse your app, and reach users who have not opted-in to push. You can create relevant, branded in-app notifications, and reach opted-out and opted-in users unobtrusively.

Key Terms

Workflow
A workflow is a method of creating messages via the dashboard.
Dashboard
The dashboard is the Urban Airship web interface located at go.urbanairship.com.

About

Aside from giving you the power to engage with users as they browse your app, in-app messages can reach users who have opted-out of receiving push notifications, a segment of the app audience previously unreachable with this type of messaging.

Use in-app messages to address users who have opted out of push, may not have seen the push notification, or who saw it but opened the app without interacting with it.

Additionally, you can apply Automation, a set of conditions that must be met before a message is either sent or displayed.

Standard vs. In-App Automation

In-app messages display differently depending on the creation method. The basics are listed in the table below, and Standard vs. In-App Automation details are specified throughout this document.

StandardIn-App Automation
Creation MethodsAPI, Dashboard, or Push TemplatesDashboard
Display FormatBannerBanner, modal, or fullscreen
Display LocationIn-appIn-app
Display TimingUpon opening the app, based on defined triggers. May also be controlled via automation.Stored on the user’s device then displayed according to defined triggers.

Benefits of In-App Automation

In-App Automation is designed to be highly contextual and displayed immediately in response to user behaviors, e.g., the user opens the app a specific number of times, views a specific screen, adds an item to the cart, makes a purchase, or views a video.

Respond to user behaviors instantly with customizable messages, giving you precise control of the user experience. In-App Automation are pre-cached locally on the device and leverage on-device automation rules for real-time responsiveness, as well as orchestrated display timing and screen context.

Real-time Display
In-App Automation uses our on-device automation framework, which means they can respond to a series of events in real-time (e.g., multiple game level changes, a sequence of screens, additions to a shopping cart) without round-trips to a server.
Guaranteed Delivery
In-App Automation is designed to use background push to reliably deliver in-app messages by sending a broadcast background push to all of your app users.

When background push is enabled for your project, we pre-load in-app messages in your app via a background push. When background push is disabled for your project, or for users opted out of background app refresh, our SDK downloads and refreshes the entire message list upon next app open.

Background push is disabled by default, though we strongly encourage enabling it if your app can handle it. For more information, see Background Push below.
Dashboard
Control all aspects of the message, including branding, through our dashboard UI.

Use Cases

Welcome Messages
Communicate the value of your app and highlight key features.
Push and Location Opt-In Prompts
Explain the value of your notifications to drive opt-in rates.
Feature Education
Drive adoption of critical/new features that promote retention.
Onboarding Messages
A series of messages educate users about the app over time.
App Reviews
Prompt users to rate your app after positive experiences.
Registration/Login
Drive registrations and logins to your loyalty program or account.
Profile Enhancement
Promote the benefits of a completed profile, and provide a link to the relevant page in your app. Encourage your users to take a second to personalize their experience, and increase engagement and retention.
App Updates
Send your users an in-app message highlighting your app's newest features, or encourage users on older versions to update the app. If you just added a new page or have some new content, make sure to include a Deep Link so that they can find it quickly.
Ongoing Promotions
If you have a promotion that users can take advantage of at any time — such as a discount for inviting a friend or for taking a survey — an in-app message serves as a convenient reminder.

These experiences are typically hard-coded by app developers and cannot be updated without custom development and app store updates. With In-App Automation, you create and update these on the fly via our dashboard UI, without custom development.

Behavior and Appearance

Standard

Behavior

In-app message banners can appear at either the top or bottom of your application. They behave largely like push notifications in that they can include any element of Urban Airship's rich feature set (interactive buttons, actions, etc.), and they can be dismissed as you would dismiss a push notification. However, there are a few key differences regarding in-app message display behavior:

Duration
By default, an in-app message will only appear on a user's screen for 15 seconds before disappearing. You can change this value via the dashboard in Settings: Configuration: In-App Message Design. When sending in-app messages via the API, you can override this value with the duration key.
Sending Multiple Messages
An app will only hold on to a single in-app message at a time. If a valid message is waiting to be displayed in a user's app and a new message comes along, the new message takes the place of the prior one. Moreover, there is no way to specify an in-app message's priority. A new message will always replace an old message.

Users will see an in-app message when and if:

  • They have not tapped an associated push, if any.
  • The in-app message is not expired.

By default, an in-app message will display while a user is browsing your app. If a user is not browsing your app while you send an in-app message, the message will be displayed the next time the they open the app.

Note

Urban Airship will only display the most recent in-app message.

For example, many media companies send breaking news push notifications with a deep link to the story within their app — when a user taps the notification, they’re taken directly to the story. For users that don’t tap notifications directly and instead open the app later, that news story may be difficult to find. An In-App Message appears the next time a user opens the app, providing a second opportunity to link them directly to the story, and a much more streamlined and delightful experience.

Note

In-app messages paired with a push notification are not displayed if the user taps the push notification, eliminating that potential redundancy.

Animation

In-app messages animate into the user's screen. Depending on the API request specifications or dashboard configuration, the message will animate in from either the top or bottom of the user's screen.

Colors

Notification colors can be specified via the API or Dashboard.

Dismissal

Notification dismissal on iOS is accomplished with a Drawer Pull, and dismissal on Android is accomplished by swiping the notification left or right, or by clicking the "X" icon. This image shows both the top and bottom display styles for both Android and iOS devices:


Device Examples

iOS

These in-app messages alert users about available app updates. The second and third include interactive buttons.

Android

The first in-app message alerts the user about available app updates. The second and third are reminders about the user's store credit and include interactive buttons.

In-App Automation

Behavior

Pre-Loaded on Device
In-app messages are loaded on the user's device upon receipt of a background push. When background push is disabled for your project, or for users opted out of background app refresh, our SDK downloads and refreshes the entire message list upon next app open. Up to 50 messages can be pre-loaded onto the device at a time, ready for display.
Priority
Because multiple messages can become eligible for display at the same time, you have the option of assigning a priority to each message. If no priority is assigned, by default, the most recently updated message will appear first. See: Optional Message Features: Message Priority.
Display Frequency
To prevent over-messaging, our SDK waits 30 seconds after one message is closed before displaying the next eligible message. This delay value can be updated through native code. You may also control the number of times an individual message is displayed. See: Optional Message Features: Display More Than Once.
Duration
Duration varies by message style.

  • Modal and fullscreen messages appear on screen until the user interacts with them, either by clicking one of the main buttons or clicking the Dismiss button.

  • Banner messages disappear automatically after 15 seconds but will disappear sooner if the user clicks any button or dismisses the message.

Background Push

Background push invokes any typical background actions your app takes when it is woken. For some apps this behavior can be too much to handle. Because of this, background push is disabled by default for use with In-App Automation.

If you are confident with you app’s ability to handle a larger number of background push notifications, for best results, we highly recommend enabling background push for In-App Automation. Without the use of background push, your app will not receive necessary updates of in-app messages until the next time the app is opened.

Here are some examples of what can happen if background push is not enabled:

  • New messages may not be available on the device before the user generates the event that triggers the message display.

  • Updates to or cancellations of in-app messages may not get applied in time, so your app may display the wrong version of your message or display a message that should not have been displayed.

  • Attempts to restore in-app messages may not work if the app is not opened by the user within the editing grace period (14 days), as the device only stores a message for 14 days.

Please note that while background push is not guaranteed to solve all of the issues above, it does give the SDK the best opportunity to update the message list before the app is open, making it more likely that your user sees the correct message.

Enable background push for your project via the Settings menu.

Style

There are four In-App Message styles: Banner, Modal, Fullscreen, and Custom HTML.

The appearance of Custom HTML messages is determined by your provided code. For the other styles, configure their default appearance in Settings: Configuration: In-App Automation.

Banner

Banner messages appear at the top or bottom of your screen, sliding up from the bottom of the screen, or down from the top. They are designed to be less obtrusive to users than modal or fullscreen messages, by taking only a portion of the screen and not fully interrupting the user from their current task. Example uses include informational messages, news alerts, or promotions that do not deserve a full user interruption.

Banner message elements:

  • Header: An optional headline for the message. Bolded by default to stand out from the message text.
  • Image: A small thumbnail image that appears on the right or left side of the message.
  • Text: The main text of the message.
  • Buttons: Display up to two buttons, allowing a user to respond to the message.
  • Dismiss: Ability to dismiss the message by swiping it back in the direction it came from.

Modal

A modal message takes over the user’s screen, compelling the user to interact with it. Modals are typically used to prompt users to reply to a question or make a quick decision. The message window is smaller than the full width of the screen, superimposed on the app with a translucent background, assuring the user that the interruption is temporary.

Modal message elements:

  • Header: An optional headline for the message. Bolded by default to stand out from the message text.
  • Image: A large image embedded in the message.
  • Text: The main text of the message.
  • Buttons: Display up to two buttons, allowing a user to respond to the message.
  • Dismiss: Ability to dismiss the message by clicking the X button.
Tip

You can make a modal message display as fullscreen on small screen devices. Use this setting if you want your message to take over the entire screen on a phone but display as a modal on a tablet. See: Settings: Configuration: In-App Automation.

Fullscreen

Fullscreen messages are similar to modal messages but take over the entire screen, providing more real estate for your message.

Fullscreen message elements:

  • Header: An optional headline for the message. Bolded by default to stand out from the message text.
  • Image: A large image to embed in the message.
  • Video: Can be displayed instead of an image.
  • Text: The main text of the message.
  • Buttons: Display up to five buttons, allowing a user to respond to your message.
  • Dismiss: Ability to dismiss the message by clicking the X button.
  • Footer: A text link to content, e.g., Terms & Conditions, relevant to the message.

Custom HTML

Custom HTML messages have the same appearance as modal messages and also have the same message elements.

Write and design a notification in an HTML file, then upload the file in the Content step of the In-App Automation workflow.

General guidelines:

  • Set your layout, content text, media, buttons, and any actions you want to trigger.

  • Since much of the message's content and behavior are defined in your HTML, the settings and options available in the dashboard workflow are reduced to only those applicable to the Custom HTML message style.

  • Any images, CSS, and applicable scripts referenced in your HTML should be made available via a CDN or publicly available repository. You cannot upload additional files via the dashboard workflow.
Tip

You can make a custom HTML message display as fullscreen on small screen devices. Use this setting if you want your message to take over the entire screen on a phone but display as a modal on a tablet. See: Settings: Configuration: In-App Automation.

Layout

Layout options vary by message style: Banner, Modal, and Fullscreen.

Banner

Choose between left or right image orientation, or a text-only banner.

Modal

Choose among layouts that feature media at the top, middle, or bottom of the message, or a text-only option.

Fullscreen

Choose among layouts that feature media at the top, middle, or bottom of the message, or a text-only option.

Message Status

A message created via In-App Automation is either Active, Expired, Canceled, or Pending. This is shown in the Status column in the list of messages in Messages Overview.

When you first create an in-app automated message, it is Active. It remains active until either:

  1. It expires according to its end date. See: Optional Message Features: Specify Start and End Dates.
    OR
  2. You stop it. Stopped messages are considered canceled.

  • Active messages can be edited or canceled at any time.
  • An Expired or Canceled message can be edited and its end date extended, making it active again, within a grace period of 14 days. After 14 days they can only be duplicated.

Recently created or edited messages have the status Pending for a few seconds, until it completes processing and becomes Active.

Edit, duplicate, or cancel messages in Messages Overview: In-App Automation.

FAQ

Will opted-out users receive in-app messages?
Yes, in-app messages can be sent to your entire app audience, not just those opted-in to push notifications. There are a couple of caveats, however: there are platform restrictions (see What platforms are supported? below), and iOS users who have disabled the Background App Refresh feature will not receive messages. It is also possible to give your users the option to disable in-app messages.
What platforms are supported?
iOS8, Android API 14+ (Ice Cream Sandwich), and second generation or later Amazon devices are supported. iOS7 users can also receive in-app messages, though they must be opted in to push.

Configuration and Requirements

Standard

In-app messages require the SDK 6.0 or later. See the appropriate Platform page to get started. If you are using an earlier SDK, see our iOS and Android migration guides.

To use in-app messages in the dashboard, the feature must be enabled in Settings » Configuration » Composer. Set the toggle for In-App Messages to ON. By default, new projects have In-App Messages enabled.

Once you have enabled in-app messages, configure your messages' default display options in Settings: Configuration: In-App Message Design.

In-App Automation

In-App Automation requires the SDK 9.0 or later. See the appropriate Platform page to get started. If you are using an earlier SDK, see our iOS and Android migration guides.

Configure your messages' default display options in Settings: Configuration: In-App Automation.

Additional customization may be made via the SDK:

Send an In-App Message

Standard

Send via Dashboard

First enable them in your project, then head to the dashboard:

Send via API

If you want to use the API to send an in-app message, no setup is required! See the API documentation.

Tip

You may also use in-app messages in Push Templates.

In-App Automation

Send via Dashboard

Send via API

Note

There is currently no server API for In-App Automation.