How to Embed an Audience Experience Using the SDK (v2)

This guide walks you through how to embed an Audience Experience or Grid on your website using the Audience SDK v2. You can display experiences as an embedded iframe, a modal lightbox, or a banner that opens on click.

This article covers:

Basic embed setup
Supported embed types
Load behaviors (embed, lightbox, banner)
Trigger-based embeds
Page targeting
SPA considerations
Common troubleshooting tips

What the Audience SDK Does

The Audience SDK allows you to mount an Audience Experience or Grid directly into your site using JavaScript. The SDK automatically creates and manages an iframe for you and supports:

Embedded experiences (in-page)
Lightbox (modal) experiences
Banner CTAs that open a lightbox
Script-tag embeds or manual JavaScript initialization

Quick Start: Embed an Experience on Your Page

Step 1: Load the SDK

Add this script tag to your page (preferably in the <head> or before the closing </body> tag):

<script async defer src="https://xp.audience.io/sdk.js"></script>

Step 2: Add an Audience Container

Place the following <div> where you want the experience to appear:

<div
  class="audience-container"
  data-id="1680886"
  data-type="experience"
  data-load-enabled="true"
  data-load-behavior="embed"
  data-load-revisit-enabled="true"
  data-load-revisit-behavior="embed"
></div>

What happens next:

The SDK scans the page for .audience-container elements
It automatically loads the experience inside an iframe
The experience appears inline on the page

Supported Experience Types

Experience vs Grid

Type	`data-type` value	Notes
Experience	`experience`	Subtype optional
Grid	`grid`	Requires `data-subtype="v2"`

Grid example:

<div
  class="audience-container"
  data-id="456"
  data-type="grid"
  data-subtype="v2"
></div>

Display Behaviors

Display Behaviors

You can control how the experience appears using behavior settings.

Available behaviors

embed — shows directly on the page
lightbox — opens as a modal overlay
banner — displays a banner CTA that opens a lightbox

Example: Lightbox on Page Load

<div
  class="audience-container"
  data-id="1680886"
  data-type="experience"
  data-load-enabled="true"
  data-load-behavior="lightbox"
></div>

Example: Banner CTA

<div
  class="audience-container"
  data-id="1680886"
  data-type="experience"
  data-text="Enter Now"
  data-primary-color="#111827"
  data-secondary-color="#ffffff"
  data-load-enabled="true"
  data-load-behavior="banner"
></div>

Trigger-Based Experiences (User Action)

If you don’t want the experience to load immediately, you can trigger it based on a user action like a button click.

Example: Button Opens Lightbox

<button id="open-audience">Open Experience</button>

<div
  class="audience-container"
  data-id="1680886"
  data-type="experience"
  data-load-enabled="false"
  data-trigger-enabled="true"
  data-trigger-element="#open-audience"
  data-trigger-event="click"
  data-trigger-behavior="lightbox"
></div>

Important

Triggered experiences require:
- data-trigger-element
- data-trigger-behavior
You cannot mix embed load behavior with triggers.

Embedding Using an Iframe (Advanced)

If you prefer to manage the iframe directly, you can make the iframe itself the container.

<iframe
  class="audience-container"
  src="https://xp.audience.io/experience/1680886"
  style="width:100%;border:0;"
  allow="clipboard-write"
></iframe>

Notes

The URL must follow this format: /experience/{id} or /grid/{id}
The SDK automatically handles resizing
Defaults to embedded behavior

Page Targeting (Optional)

You can control which pages are allowed to show an experience.

Whitelist Example

<div
  class="audience-container"
  data-id="1680886"
  data-type="experience"
  data-use-whitelist="true"
  data-whitelist="products|pricing|about"
  data-load-behavior="lightbox"
></div>

Blacklist Example

<div
  class="audience-container"
  data-id="1680886"
  data-type="experience"
  data-use-blacklist="true"
  data-blacklist="checkout|account"
  data-load-behavior="lightbox"
></div>

Single-Page Application (SPA) Support

Single-Page Application (SPA) Support

If your site uses React, Vue, Next.js, or another SPA framework, you may need to re-scan the page after route changes.

Re-initialize after route changes

if (window.Audience?.initializeFromEmbed) {
  window.Audience.initializeFromEmbed()
}

This ensures newly added containers are detected.

Common Troubleshooting

Nothing appears

Confirm data-id is numeric
Confirm data-type is set correctly
Grid embeds must include data-subtype="v2"
Ensure a load or trigger behavior is configured

Trigger doesn’t work

Confirm the trigger element exists in the DOM
Confirm data-trigger-event is set
Confirm data-trigger-behavior is defined

Ad blockers

If an ad blocker interferes, the SDK will show a fallback message with a direct link to the experience.

Need Help?

If you’re unsure which embed approach is best, or you’re embedding into a complex site or SPA, reach out to our support team and include:

The page URL
Your experience ID
The embed code you’re using

We’re happy to help you get it set up correctly.