About Scenes

You can create scenes from scratch or by selecting a template for these experiences:

• App Onboarding
• App Update
• Account Upgrade
• Feature Awareness
• NPS Feedback
• User Feedback

Use cases

In addition to the ready-made use case templates, scenes can be used for a variety of custom experiences that you define. Examples:

• Welcome messages — Communicate the value of your app and highlight key features.
• Push opt-in prompts — Explain the value of your notifications to drive opt-in rates.
• App reviews — Prompt users to rate your app after positive experiences.
• Registration/login — Drive registrations and logins to your loyalty program or account.
• NPS (Net Promoter Score) — Display an NPS survey to gauge how likely your users are to recommend your app.
• Customer service rating — Display a customer service satisfaction survey after they end a support chat.
• Purchase confirmation — Display a survey after they complete a purchase to get feedback on your checkout process.
• General feedback — Display a survey in response to a button click.
• Account closure — Display a survey at the end of an account closing asking why they closed their account.

Appearance and behavior

Scenes are cached on users’ devices 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 scenes during the next app open.

They appear regardless of a user’s opt-in/out status for notifications and remain on screen until the user interacts with them, either by swiping or tapping through all screens or dismissing the scene.

For scenes with multiple screens, dots appear at the bottom, indicating the number of screens. You can hide these indicators. You can also disable the swipe requirement to require interacting with buttons and prevent swiping between screens.

Scenes can be customized for device Light and Dark modes by creating Color SetsA named pair of hexadecimal color values supporting device Light and Dark modes. Color sets can be selected for any color field in a scene and when configuring the default appearance of surveys, scenes, and in-app automations. Dark mode is supported for scenes only. and assigning them for design elements, e.g., background and text.

Styles

There are two scene styles:

• A modal scene takes over the user’s screen, compelling the user to interact with it. The modal window is smaller than the full width of the screen, superimposed on the app with a translucent background, indicating that the interruption is temporary.

• Fullscreen scenes have the same design as modal but use the entire screen. You can set fullscreen scenes to extend to the full height and width of a device or display only within the area of your app’s interface that is not covered by physical or UI elements, such as a status bar or notch.

Previewing

A preview of your message updates as you design its content. You can use these tools to create a more accurate representation of how your content may appear to users:

• Devices — Select from a list of iOS and Android devices to reflect the device’s viewport dimensions.
• Light/Dark mode — See the appearance of elements with an assigned Color SetA named pair of hexadecimal color values supporting device Light and Dark modes. Color sets can be selected for any color field in a scene and when configuring the default appearance of surveys, scenes, and in-app automations. Dark mode is supported for scenes only. .
• Text scaling — Adjust the text scale between 70% and 200% of the current text size to see how the content will appear on devices using text size accessibility features.

If you are using personalized content, the preview displays the default values. You can also preview personalization by entering your own JSON sample data or by selecting a Preview GroupA preview group is an audience group you create for previewing personalized content in the dashboard. Wherever a personalization preview is available, you can select a preview group, and those users’ attributes will appear for any Handlebars references to attributes. You can enable any preview group as a test group so the users can receive test messages sent to the group. These messages appear as tests in Messages Overview. user. See: Previewing personalized content.

If using custom fonts, you can set a web font URL for the primary font in each of the font stacks in your design defaults, and the font will be rendered in Scene previews.

Screen elements

Each screen can contain these elements:

• Text — You can make the text function as a link by setting an action: Web Page, Deep Link, or Adaptive Link. If configuring text for a footer, you can 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 the message. 15 text elements maximum per screen.

• List — A bulleted list, where the bullet is an image you provide, followed by text.

• Question — Questions can be designated as required. Screens support multiple questions, with 10 questions maximum per scene.

  • Open Text questions are followed by a text field where users can enter a response.

  • Single Choice questions are followed by radio buttons for selecting one of multiple answers you provide. Answers can be presented in random order. Responses can be stored as text or number AttributesMetadata that you can use for audience segmentation. Attributes differ from tags in that when evaluating users with attributes, Airship uses operators, e.g., equals, less than/greater than, contains, before/after, to determine whether or not to target a user. Supported attribute types are TEXT, NUMBER, and DATE. .

  • Multiple Choice questions are followed by check boxes for selecting one or more answers you provide. Answers can be presented in random order.

  Story mode does not support questions.

• Media — An image or video. 10 media elements maximum per screen. See: Media guidelines.

  Video displays in landscape mode and does not start until a user clicks the Play button. (Orientation and behavior are different for background video.) Story mode does not support video. Video requires iOS and Android SDKs 17+.

• NPS — A survey based on the net promoter score  metric, which measures how likely it is that your users would recommend your brand or product to a friend or colleague. The survey format is a question with answer scale 0-10. You can add one NPS survey per scene. Story mode does not support NPS.

• Button group — One button group per screen is allowed. A button group can support up to five buttons, and you will associate an action for each. If two or more buttons are added, choose a button layout: Separate, Joined, or Stacked. You can also pin buttons to the bottom of the screen when the user scrolls. You can also configure options:

  • Accessibility description — Text that can be announced by assistive technology, such as screen readers. This overrides announcement of the button text.

  • Event name — By default, the total clicks for all buttons in the scene are reported using Custom EventEvents that indicate that a user performed a predefined action, such as adding an item to a shopping cart, viewing a screen, or clicking an Unsubscribe button. Custom events can trigger automation, sequences, scenes, and surveys. You can code them into your app or website, or send them to Airship from an external source using the custom event API. Custom events contain properties that you can use to personalize messages. button_action. To differentiate the clicks for a specific button, you can enter your own event name. Event names also support HandlebarsHandlebars is Airship’s templating language for personalization. Handlebars expressions use double curly braces wrapped around a content template, ranging from a simple variable, e.g., {{first_name}}, to complex evaluations of personalization data. .

  • Tags and subscription list opt-in/out — Add or remove a TagMetadata that you can associate with channels or named users for audience segmentation. Generally, they are descriptive terms indicating user preferences or other categorizations, e.g., wine_enthusiast or weather_alerts_los_angeles. Tags are case-sensitive. or opt a user in to or out of a Subscription ListAn audience list of users who are opted in to messaging about a specific topic. Users can manage their opt-in status per list using a preference center. when they tap the button.

  • Fix at bottom on scroll — Keep buttons visible at the bottom of the screen when the user scrolls.

  • Scene behavior — In addition to the button action, determine how the scene behaves when a button is tapped. Use cases:

    • Give the option Don't ask me again. How to set it up: For a scene configured to repeat, label a button Don't ask me again and set the scene behavior to Dismiss and cancel repeat.

    • Close the scene in the background while the system opt-in prompt is in the foreground. How to set it up: For a button configured with the action Subscription List Opt In/Out or Push Opt-in, set the scene behavior to Dismiss.

    • Advance to the next screen after opting in, without requiring a swipe. How to set it up: For a button a button configured with the action Subscription List Opt In/Out or Push Opt-in, set the scene behavior to Next screen.

    For all scene behavior options, see: Create a scene: Button group.

Design

You can set appearance and behavior defaults for surveys, scenes, and in-app automations, including Color SetsA named pair of hexadecimal color values supporting device Light and Dark modes. Color sets can be selected for any color field in a scene and when configuring the default appearance of surveys, scenes, and in-app automations. Dark mode is supported for scenes only. and custom fonts. See: In-App Experience Design Defaults.

When configuring scene content, you have the option to override the defaults. You can customize the appearance of each screen’s background and style the text for each element, as well as the background and border of each button. For details, see: Create a scene: Design.

Scenes support using media as background. Background video displays in portrait mode, starts automatically, and plays in a loop. (Orientation and behavior are different for video used in the Media element.) Story mode does not support background video. Video requires iOS and Android SDKs 17+.

The Dismiss button appears as an X in the upper right corner of the scene. You can select a Color SetA named pair of hexadecimal color values supporting device Light and Dark modes. Color sets can be selected for any color field in a scene and when configuring the default appearance of surveys, scenes, and in-app automations. Dark mode is supported for scenes only. or enter a hexadecimal color value to customize its color or opt to hide it.

Dark mode is supported when using a Color SetA named pair of hexadecimal color values supporting device Light and Dark modes. Color sets can be selected for any color field in a scene and when configuring the default appearance of surveys, scenes, and in-app automations. Dark mode is supported for scenes only. with a Dark Mode color configured.

Story mode

The default behavior of a scene requires the user to swipe between screens. Story mode enables automatic transitions to the next screen without requiring swiping. Minimum SDKs required: iOS and Android 17.0.

When configuring Story mode, you set how long each screen is displayed (1-60 seconds) and determine what happens after the story ends:

• Loop — The scene replays indefinitely.
• Display last screen — The last screen of the scene continues to display.
• Dismiss — The scene closes.

When viewing a story, a progress bar indicates the number of screens and their remaining duration. The user can:

• Tap the right side of a screen to go to the next screen and tap the left side to go to the previous screen
• Tap and hold anywhere on the screen to pause
• Swipe down or tap the Dismiss (X) button to close

The progress bar appears in the device preview after you enable Story mode.

Story mode does not support:

• Scrolling — Make sure to design screens for small device dimensions to eliminate the appearance of a non-functional scroll bar.
• Video
• Questions or NPS

Tags

You have the option to set a tag when a scene is displayed.

Templates

When creating a scene, you can start from scratch or select a template. Each template has various screens with content placeholders supporting the template purpose. You can add, duplicate, reorder, and remove screens. The same design options are available if you choose to create a scene from scratch.

App Onboarding

Onboard new users to your app.

App Update

Alert users that the latest version of your app is now available.

Account Upgrade

Inform users that their subscription has ended or that it is time to upgrade.

Feature Awareness

Educate users about specific features to encourage them to try them out.

NPS (Net Promoter Score)

A survey based on the net promoter score  metric, which measures how likely it is that your users would recommend your brand or product to a friend or colleague. This can be used to measure their overall sentiment about your brand or product (known as relational NPS) or about a specific experience or transaction, such as booking a flight (known as transactional NPS). After selecting a template, you customize the questions and design. You also have the option to create a confirmation screen that appears when a user submits the survey.

User Feedback

A general purpose survey with multiple question options to collect a wide range of user feedback. After selecting a template, you customize the questions and design. You also have the option to create a confirmation screen that appears when a user submits the survey.

Optional features

In addition to configuring when the scene will display and its appearance and content, you can also set optional features:

• Priority — Because multiple scenes can become eligible for display at the same time, you can assign a priority value to each one. If no priority is assigned, by default, the most recently updated scene will appear first. Priority is shared across Scenes, SurveysQuestion-and-answer experiences used to collect and aggregate feedback or generate a net promoter score. They are cached on users’ devices and displayed when your users meet certain conditions within your app, such as viewing a particular screen or opening the app a certain number of times. , and In-App AutomationMessages that are cached on users’ devices and displayed when your users meet certain conditions within your app, such as viewing a particular screen or opening the app a certain number of times. .

• Repeat — To prevent over-messaging, our SDK waits 30 seconds after one scene is closed before displaying the next eligible scene. This delay value can be updated through native code. You can also control the number of times an individual scene is displayed and the minimum waiting period before it is eligible for redisplay. Redisplaying your scene is useful because users can dismiss or ignore scenes.

• Start and end dates — Set the dates and times during which your scene can be displayed. Specifying a window of time is useful for scenes that are time-bound or tied to scheduled events.

• Missed behavior — Override the project-level setting for how the scene is handled when audience conditions are not fully met.

• Ignore Message LimitsLimits that cap the number of messages you can send within a specified time frame, preventing you from over-messaging your users. They are set at the project level. — Override the project-level limit for a single scene.

• Campaign categories — Group scenes of a similar type or messaging strategy for aggregate reporting.

• Custom keys — Custom keys are additional key-value pairs you can send to a device along with the scene, 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.

Scene status

Scene status is either Active, Expired, Canceled, or Pending. When you first create a scene it is Active. It remains active until either:

1. It expires according to its end date.

   OR

2. You stop it. Stopped scenes are considered canceled.

• Active scenes can be edited or canceled at any time.
• An Expired or Canceled scene 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.

A recently created or edited scene has the status Pending for a few seconds until it completes processing and becomes Active.

See: Change status.

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

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 scenes. Without the use of background push, your app will not receive necessary updates of scenes until the next time the app is opened.

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

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

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

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 scene list before the app is open, making it more likely that your user sees the correct scene.

Enable background push in your project settings.

Segmentation

If your scene contains an NPS survey, Airship automatically generates AttributesMetadata that you can use for audience segmentation. Attributes differ from tags in that when evaluating users with attributes, Airship uses operators, e.g., equals, less than/greater than, contains, before/after, to determine whether or not to target a user. Supported attribute types are TEXT, NUMBER, and DATE. based on the following data:

• NPS Score is the score submitted by the user: 0-10.
• NPS Category is one of three categories based on the NPS Score. Ratings 9 and 10 have category Promoter, 7 and 8 are Passive, and 6 or lower are Detractor.

See also: Segmenting your audience.

Reporting

We provide aggregate information about responses to questions and NPS surveys in your scene at Reports » Surveys. See: Engagement Reports: Surveys.

Performance reports are available for individual scenes in the same format as Message Reports. From Messages OverviewA view of all your project’s messages, with options for editing their settings, content, status, and more. click   for a scene to open its report.

The header displays the scene name and creation date, time and time zone, as well as its status. Options in the header:

  — Changes the status of an Active scene to Canceled. This is effectively the same as specifying an end date, immediately applying an end date of “now.” Active messages can be canceled at any time.

  — Changes the status of a Canceled or Expired scene to Active. See: Restart an in-app automation, scene, or survey. This is effectively a shortcut to editing the scene and either eliminating or specifying an end date. Expired scenes can be restarted within a grace period of 14 days. After 14 days they can only be duplicated.

  — Opens the scene for editing. Availability depends on its status. Active scenes can be edited at any time. An Expired or Canceled scene 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.

  — Creates a copy of the scene and opens it for editing. You must complete the composer steps in order to save the new scene.

Performance

The Performance section of a scene report displays:

• Latest Message Activity — The username, date, time, and activity associated with the most recent change to the scene. Last Message Activity data is available for 90 days after scene creation. For scenes with more than one activity, click Show all to open a modal window that displays all activity.

• Statistics:

  • Scene Displayed — The total number of times at least the first screen of the scene was displayed.
  • Scene Completed — The total number of times all screens in a scene were displayed and the rate of completion. This only appears for scenes with more than one screen.
  • Scene Dismissed — The total number of times the scene was dismissed before the last screen was displayed.
  • Survey Displayed — For scenes with questions or NPS, the total number of times the first screen with questions/NPS was displayed.
  • Survey Submitted — For scenes with questions or NPS, the total number of times users clicked the button with action Submit Responses and the rate of submission.
  • Survey Not Submitted — For scenes with questions or NPS, the total number of times users dismissed the scene without clicking the button with action Submit Responses.
  • Total Push Opt-in — The total number of users that opted in from the system prompt or app settings after clicking a button with action Push Opt-in.
   Note

  Ideally, Scene Displayed = Scene Completed + Scene Dismissed, however there may be discrepancies due to:

  • Users currently viewing a scene — Users triggered the scene but have not yet dismissed or completed it.
  • Users closed the app, or users used the Back button on Android — These behaviors are not reported by the SDK, so the related events are not tracked or counted.

• Engagement Over Time — A chart displaying daily Completed, Dismissed, and Push Opt-in counts over the last 7 days. Hover over a date to see counts per day. You can select another time frame, and the chart will reload with the data for that period.

Scene detail

The Scene Detail section of a scene report displays the same information shown in the Review step of the Scene composer and counts for screen displays and dismissals. Click the arrows to page through the previews of each screen.

If you are currently running an A/B test, you will see performance metrics for each variant. For more information, see: Select the winning message.

If you included questions or an NPS survey in your A/B test, responses are includes in the aggregate report in Reports » Surveys. You can click the link in Scene Details to go to that report.

Events

The Events section of a scene report displays a list of events directly and indirectly attributed to the scene. Click Download CSV to export the data.

• Event Name — Human-readable name assigned to a particular custom event.
• Notification Attribution — Displays whether your event was directly or indirectly attributed to the scene.
• Count — The number of instances of this event.
• Value — The value (monetary or otherwise) generated by the event.
• Average Value — Value divided by Count.
• % of Total Count — Count divided by the Total Count (listed on the bottom row).

Message limits

Message limits cap the number of messages you can send within a specified time frame, preventing you from over-messaging your users. They are set at the project level. The limit for Scenes, SurveysQuestion-and-answer experiences used to collect and aggregate feedback or generate a net promoter score. They are cached on users’ devices and displayed when your users meet certain conditions within your app, such as viewing a particular screen or opening the app a certain number of times. , and In-App AutomationMessages that are cached on users’ devices and displayed when your users meet certain conditions within your app, such as viewing a particular screen or opening the app a certain number of times. are combined. See: Message Limits.

Requirements

Minimum SDKs:

• iOS: 16.2.0

  • Changelog 
  • Getting Started Guide
  • iOS Migration Guide 

• Android: 16.2.0

  • Changelog 
  • Getting Started Guide
  • Android Migration Guide 

Some individual features require later SDKs. They are noted with their descriptions on this page and in Create a scene.

Questions and NPS surveys in scenes require analytics be enabled in the SDK. Analytics are enabled by default, and disabling them renders certain features, nonfunctional. See the Analytics and Reporting section of the SDK documentation for information about enabling analytics.