About Scenes

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

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

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.

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 through all screens or dismissing the scene.

Modal and fullscreen styles are supported. Each screen can contain these elements:

• Text — May include header, body, and footer fields. The footer field functions as a button and 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. 15 text elements maximum per screen.

• Buttons — Each style supports a different number of buttons, and you will associate an action for each. If two 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.

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

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

Styles and dismiss button

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.

Appearance can vary based on device size. We recommend testing on devices to ensure your scenes appear as intended.

The Dismiss button appears as an X in the upper right corner of the scene. You can enter a hexadecimal value to customize its color or opt to hide it.

Design

You can customize the appearance of each screen:

• Background — You can set a color or provide media. See: Media guidelines.
• Text — For Header, Body, and Footer. Body text also applies to each item in a list.
  • Font family
  • Color
  • Text Size — Numeric value defined as points, not pixels
  • Alignment — Left, right, center
  • Style — Underline, bold, italic
• Buttons
  • Text — Font, color, size (numeric value defined as points, not pixels), style (underline, bold, italic)
  • Background color
  • Border — Color, radius

Tags

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

Templates

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 screen from scratch.

App Onboarding

App Update

Account Upgrade

Feature Awareness

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

Design defaults

You can set scene appearance and behavior defaults in your project settings. These can be overridden for an individual scene in the Design settings in the composer.

Reporting

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.

The Performance section 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:

  • Total Displayed — The total number of times at least the first screen of the scene was displayed on user devices.
  • Total Completed — The total number of times all screens in a scene were viewed. This count is only displayed for scenes with more than one screen.
  • Total Dismissed — The total number of times the scene was dismissed before the last screen was viewed.
  • Total Push Opt-in — If the scene contains a button using the Push Opt-in action, the total number of users that clicked the button.
     Note

    Ideally, Total Displayed = Total Completed + Total 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.

The Scene Detail section displays the same information shown in the Review step of the Scene composer. Click the arrows to page through the previews of each screen.

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

The Events section 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.

Minimum SDK versions

iOS: 16.2.0

• Changelog 
• Getting Started Guide
• iOS Migration Guide 

Android: 16.2.0

• Changelog 
• Getting Started Guide
• Android Migration Guide