Embedded Content

About Embedded Content

Use Embedded Content to insert SceneA 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. content anywhere within your website. This content can be non-interruptive, but it has full feature parity with mobile app Scenes. There are three primary components:

Once the Scene is triggered for display and matches the specified audience conditions, its content is available to users visiting a web page with a view/container.

The view is populated with the content from all active Scenes with the matching ID, sorted based on priority. When an embedded view loads content, the highest priority Scene that is queued for display will be shown. The same content will be shown across app and web sessions until it is dismissed by the user or is no longer available. The view will then show the next Scene with the highest priority from the display queue.

Airship first prepares the content when the triggering event occurs and then refreshes it upon every app open or web session start. This ensures that users always experience the most up-to-date message. So, after updating active Embedded Content, users will see the latest version the next time they open the app or load the app or web page containing the view.

Embedded Content behavior in web pages is the same as for mobile app In-App AutomationsMessages cached on users’ devices and displayed when users meet certain conditions within your app, such as viewing a particular screen or opening the app a certain number of times. and modal and fullscreen Scenes:

• The content displays only within the website.
• When the user leaves or closes the web page, the content is not automatically dismissed. It continues to display in the next web session.

Getting Started

In order to use Embedded Content, you must first update to version 2 of the Airship Web SDK. If you’re implementing the SDK for the first time, you will already be using version 2. If not, please read our guide on upgrading to the v2 SDK.

You will need to decide on website locations to display content, give each content container a unique name, and integrate our SDK with those containers. How you integrate will depend on how your website is built.

Integration

How you best integrate Embedded Content into your website or web application will depend on the tools and frameworks used to build your website. The Airship Web SDK provides a framework-agnostic API, which should be capable of integrating into any web framework, as well as some tools for integrating into plain HTML websites.

API

The Airship Web SDK exposes the EmbeddedViewManager API for registering an element as a container for embedded views.

In this example, we’ll select an element with HTML attribute rel="airship-embedded-banner" and register it as a container for the embedded ID banner:

const sdk = await UA
const el = document.querySelector('[rel=airship-embedded-banner]')
const view = sdk.components.embeddedViews.create(el, 'banner')

This will cause the Airship SDK to render any pending Embedded Content displays for that embedded ID in the given element.

The returned View exposes a destroy method that can be used to remove the element as an embedded target:

view.destroy()

Using these building blocks, you can integrate with any existing framework.

React

When integrating with React , you can create a hook to register an element as an embedded target:

import React from 'react'

export default function useAirshipEmbeddedContent(ref, embeddedId) {
  const [sdk, setSDK] = React.useState(null)
  React.useEffect(() => {
    UA.then(setSDK)
  })

  React.useEffect(() => {
    if (!sdk) return
    const view = sdk.components.embeddedViews.create(ref, embeddedId)
    return () => {
      view.destroy()
    }
  }, [sdk, ref, embeddedId])
}

You can then use the hook on any ref within your react components.

import React from "react"

import useAirshipEmbeddedContent from './hooks/use-airship-embedded-content'

const SomeComponent = () => {
  const ref = React.useRef(null)
  useAirshipEmbeddedContent(ref, 'my-embedded-id')

  return <div ref={ref} />
}

export default SomeComponent 

Static HTML

If you have a static HTML website or are not integrating with a framework that handles client-side rendering, such as React, Angular, or Vue, you can provide a map of CSS Selectors  to embedded IDs. You can provide these while initializing the SDK or programmatically within your application. The SDK matches selectors upon add using document.querySelectorAll . When selectors are present, the SDK adds a mutation observer to ensure elements are captured as they are added or removed.

<script type="text/javascript">
var options = {
  appKey: '<your_app_key>',
  token: '<your_token>',
  vapidPublicKey: '<your_vapid_public_key>',
  components: {
    embeddedViews: {
      // the selectors map is a mapping of CSS selector -> embedded id
      selectors: {
        // selecting using a `rel` attribute on an element
        '[rel=airship-embedded-banner]': 'banner',
        // selecting an element by id
        '#airship-cta', 'airship-cta'
      }
    }
  }
}
!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>

You may also add or remove selectors at runtime using the EmbeddedSelectorManager API:

const sdk = await UA

// set a new selector; this will replace any existing identical selector
sdk.components.embeddedViews.selectors.set('[rel=airship-embedded-banner]', 'banner')

// set all selectors; this will replace all currently set selectors with the map
// provided
sdk.components.embeddedViews.selectors.setAll({
  '[rel=airship-embedded-banner]': 'banner',
  '#airship-cta', 'airship-cta'
})

// remove a selector
sdk.components.embeddedViews.selectors.remove('[rel=airship-embedded-banner]')

// remove all selectors
sdk.components.embeddedViews.selectors.removeAll()