# Embedded Content for the Web SDK

Integrate Embedded Content into your website to display Scene content directly within your web pages. {{< badge_sdk_min web="2+" >}}

For information about Embedded Content, including overview, use cases, and how to create Embedded Content view styles and Scenes, see [Embedded Content](https://www.airship.com/docs/guides/features/messaging/scenes/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](https://www.airship.com/docs/developer/sdk-integration/web/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](https://www.airship.com/docs/reference/libraries/web-notify-sdk/v2-latest/EmbeddedViewManager.html#create)
 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`:

```js
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](https://www.airship.com/docs/reference/libraries/web-notify-sdk/v2-latest/View.html)
 exposes a [destroy method](https://www.airship.com/docs/reference/libraries/web-notify-sdk/v2-latest/View.html#destroy)
 that can be used to
remove the element as an embedded target:

```js
view.destroy()
```


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

### React

When integrating with [React](https://react.dev/), you can create a hook to
register an element as an embedded target:

**React hook for creating an embedded target**


```js
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.

```js
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](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/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`](https://developer.mozilla.org/en-US/docs/Web/API/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](#api)
> described above.


**Configuring selectors during SDK initialization**


```js
<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](https://www.airship.com/docs/reference/libraries/web-notify-sdk/v2-latest/EmbeddedSelectorManager.html)
 API:

**Modifying selectors at runtime**


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