In-App Experiences

The Airship Web SDK v2 supports ScenesA single or multi-screen in-app experience cached on users’ devices and displayed when users meet certain conditions in your app or website, such as viewing a particular screen or when a Custom Event occurs. They can be presented in fullscreen, modal, or embedded format using the default swipe/click mode or as a Story. Scenes can also contain survey questions.. See also Upgrading to the Web SDK v2.

Instrumenting your Application

In order for Scenes to function, you must Create a channel. This will count the current browser toward your Monthly Unique Visitors.

To get the most out of Scenes, instrument your website or web application to emit events for triggering and event segmentation. The following sections describe the events and provide code samples.

See also:

• In-App Experience Triggers
• Event segmentation in our API reference

Custom Events

Custom EventsEvents 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, including 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. can be used to track any interaction you wish, for example a purchase or a product view.

const sdk = await UA
const evt = new sdk.CustomEvent('purchase', 34.5, {productId: 1337})
await evt.track()

Screen View Events

Tracking App Screens can make it easy to trigger a Scene or to ensure a Scene is only displayed when currently on a given screen. You must define App Screens in the Airship dashboard.

In the context of a website or web application, you can think of a “screen” as a page with a general purpose. For example, home, product_listing, and product_detail are good generic screen names, whereas product_id_18957 is too specific and unlikely to be generally useful for reporting or targeting.

const sdk = await UA
await sdk.analytics.trackScreen('home')

Feature Flag Interactions

When using Feature FlagsA toggle for controlling the availability of content or functionality in your app or website. Flag properties enable making immediate app or website code updates., you should track when a user has interacted with the feature the flag controls. The interaction event is included in Feature Flag reporting and can also be used for triggering:

const sdk = await UA
const flag = await sdk.components.featureFlags.get('new_product_pages')

// later, when the user interacts with the new product pages
await sdk.components.featureFlags.trackInteraction(flag)

App Version Updates

If you version your web app and wish to be able to target users who may have seen an earlier version of the app, when initializing the SDK, use the appVersion property set to your app’s version number. This will be passed in your snippet as well as your push worker:

<script type="text/javascript">
var options = {
  appKey: '<your_app_key>',
  token: '<your_token>',
  vapidPublicKey: '<your_vapid_public_key>',
  // your app version, as `<major>.<minor>.<patch>`
  appVersion: '1.2.1'
}
!function(n,r,e,t,c){var i,o="Promise"in n,u={then:function(){return u},catch:function(n){
return n(new Error("Airship SDK Error: Unsupported browser")),u}},s=o?new Promise((function(n,r){i=function(e,t){e?r(e):n(t)}})):u
;s._async_setup=function(n){if(o)try{i(null,n(c))}catch(n){i(n)}},n[t]=s;var a=r.createElement("script");a.src=e,a.async=!0,a.id="_uasdk",
a.rel=t,r.head.appendChild(a)}(window,document,'https://aswpsdkus.com/notify/v2/ua-sdk.min.js','UA', options);
</script>

Controlling Scenes

If Scenes are enabled for your project, they will display according to their trigger and conditions settings. You can control their display programatically or disable them completely, if desired.

Disabling

To permanently disable Scenes in the current browser, pass the following options in your SDK initialization snippet:

components: {
  inAppAutomation: {
    enabled: false
  }
}

Pausing and Resuming Display

You can choose to pause and resume Scene display. For example, you might wish to only disable showing new Scenes when opening a modal on your site or during a checkout flow.

const sdk = await UA

// pause display of scenes
await sdk.components.inAppAutomation.setPaused(true)
// get the paused status; resolves to a boolean value
await sdk.components.inAppAutomation.isPaused()
// resume display
await sdk.components.inAppAutomation.setPaused(false)

By default, displays are not paused. If you’d like to start in a paused state so that you can manually unpause at a time of your choosing, pass the following configuration in your SDK initialization snippet:

components: {
  inAppAutomation: {
    startInPausedState: true
  }
}

Delegating Display

You can choose to implement your own display delegate, which can control if a Scene is allowed to be displayed. It can also be notified when a Scene is displayed or has finished displaying.

Your display delegate must implement the InAppDisplayDelegate interface. All methods are optional.

const delegate = {
  isMessageReadyToDisplay: (message) => {
    if (myApp.canDisplayMessage(message)) {
      return true
    }
    return false
  }
}
await sdk.components.inAppAutomation.setDisplayDelegate(delegate)
await sdk.components.inAppAutomation.setPaused(false)

If you need to pass additional information to your application, you can use Custom Keys when composing your Scene. They will be available on the extras property of the InAppAutomationDetails that are passed to your delegate.

Dark Mode

By default, Scenes follow the browser preferences for dark mode. This behavior can be disabled by a configuration value. When disabled, all displayed content will use the colors configured for light mode.

components: {
  inAppAutomation: {
    matchBrowserDarkMode: false
  }
}