In-App Message Reference

An In-app message is a message that appears inside of your app.

There are two variations of in-app messages.

TypeDisplay FormatDisplay TimingCreation Methods
StandardBannerUpon opening the app. May also be controlled via automation.
In-App AutomationBanner, modal, or fullscreenStored on the user’s device then displayed according to defined triggers.
  • Dashboard

Standard In-App Messages

See the tutorials for usage information.

Resources:

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

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   . This image shows both the top and bottom display styles for both Android and iOS devices:

Device Examples

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

The first Android 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.

Composer Options and Settings

These options are available for in-app messages created in the Message, A/B Test, and Automation composers and their equivalent API endpoints.

StepComposerDetail
AudienceMessage and A/B Test
  • Mobile app channels can be combined with any other channel.1
SetupAutomation
ContentMessage, A/B Test, and Automation
DeliveryMessage and A/B Test
DeliveryAutomation

1 A/B Tests support mobile app and web channels only.
2 Schedule supports Delivery By Time Zone An option for scheduled messages that delivers the messages according to recipient device's current time zone. . Message composer only.
3 Optimal Send Time is a predictive feature and does not appear by default. Message composer only.

Push Template Options and Settings

These options are available when creating push templates.

StepDetail
Content

In-App Automation

See the tutorials for usage information.

Resources:

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: Repeat This Message.
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 in Settings » Configuration » In-App Automation.

Styles

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

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

 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: Set In-App Automation Defaults.

Message Status

A message created via In-App Automation is either Active, Expired, Canceled, or Pending.

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.

Composer Options and Settings

These options are available for in-app messages created in the In-App Automation composer.

StepDetail
StyleAvailable styles: Banner, modal, fullscreen, custom HTML
LayoutAvailable layouts per style:1

  • Banner: Left or right image orientation, or a text-only banner.
  • Modal: Media at the top, middle, or bottom of the message, or text-only.
  • Fullscreen: Media at the top, middle, or bottom of the message, or text-only option
ContentFooter:

  • Fullscreen messages include a Footer field, which is designed to link to your Terms and Conditions, Privacy Policy, or additional information to help the user make a more informed decision about the actions they could take in this message.
  • The footer inherits the styling of the body text and functions as a button.
Media:

  • Ensure the URL will be accessible by your mobile audience. HTTPS is required.
  • If your account has CDN enabled, you have the option to upload media rather than entering a URL. Contact Airship Support if you are interested in enabling CDN media hosting.
  • Supported images: JPEG, PNG. 2 MB maximum.
  • Supported video: MPEG, MPEG2, MP4, YouTube. 2 MB Maximum.
Buttons:

  • Banner and modal style messages support up to two buttons.
  • Fullscreen style messages support up to five buttons.
  • If more than one button is added, you may choose a button layout: Separate, Joined, or Stacked.
Custom Keys:

  • Custom keys are additional key-value pairs in your push notification payload for use by custom code in your app. You can use custom keys to pass additional campaign identifiers for analytics, pass user information to the device, control the look and feel of the app, provide image links, etc.
Actions
  • Available button actions vary per message style.
  • Fullscreen messages include a footer, which functions as a configurable button. The actions available for the footer button are Deep Link and Web Page.
BehaviorDisplay triggers

1 The appearance of Custom HTML messages is determined by your provided code.

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.