Embedded Content for the Web SDK

Integrate Embedded Content into your website to display Scene content directly within your web pages. Web SDK 2+

For information about Embedded Content, including overview, use cases, and how to create Embedded Content view styles and Scenes, see Embedded Content.

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.

Registering an embedded container

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:

React hook for creating 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.

Important

This method of embedding content is not recommended for elements under the control of a client-side rendering framework, such as React, Angular, or Vue, as this may create a significant performance impact.

If using one of these frameworks, instead integrate using the API described above.

Configuring selectors during SDK initialization

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

Modifying selectors at runtime

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

Feedback

Was this page helpful?