Embed Integration

The FanFest SDK lets you embed a full fan engagement experience directly into your website using an iframe-based widget. This page covers the complete embed setup beyond the Quickstart.

Already have a working embed?

If you followed the Quickstart, you already have a running embed. This section goes deeper into configuration, advanced callbacks, and customization.

How the Embed Works

When you call FanFestSDK.init(), the SDK:

1. Validates your configuration options against an internal schema
2. Fetches your web app configuration from the FanFest API
3. Finds any <div id="fanfest-embed"> elements on the page
4. Creates an iframe inside each container, loading your channel's FanFest experience
5. Sets up a PostMessage bridge for communication between your page and the embed
6. Watches for DOM changes to auto-detect new embed containers added dynamically

The embed container is identified by the HTML id attribute fanfest-embed. The SDK uses a MutationObserver to detect when containers are added or removed from the DOM, so you can dynamically insert embed containers at any time after initialization.

Installation

Add the SDK script to your HTML:

<!-- IIFE build (recommended for most sites) -->
<script src="https://sdk.production.fanfest.vip/{version}/fanfest-sdk.js"></script>

<!-- ESM build (for module-based setups) -->
<script type="module" src="https://sdk.production.fanfest.vip/{version}/esm/fanfest-sdk.esm.js"></script>

Replace {version} with the SDK version you want to use (e.g., 1.0.20). Use a pinned version in production for stability.

SDK init() Options

All options are passed to FanFestSDK.init(). The SDK validates these at runtime and throws an error if required options are missing or types are wrong.

Option	Type	Required	Default	Description
clientId	string	Yes	--	Your web app ID from the FanFest dashboard
apiBase	string	No	"https://api.fanfest.vip"	API base URL (override for staging/testing)
appOrigin	string	No	"https://fanfest.vip"	FanFest app origin (override for staging/testing)
iframe.backgroundColor	string	No	"var(--color-brand-background)"	CSS background color for the embed iframe
hostLoginFn	() => void	No	undefined	Callback invoked when the embed needs to trigger a login on your site. Requires SSO integration.
hostRewardsFn	() => void	No	undefined	Callback invoked when the embed needs to show rewards on your site. Requires SSO integration.

No apiKey option

The SDK does not have an apiKey init option. Authentication is handled through the clientId (your web app ID). If you see references to apiKey elsewhere, they refer to server-side API keys used for the Loyalty REST API, not the client-side SDK.

Minimal Configuration

FanFestSDK.init({
  clientId: "your-web-app-id",
});

Full Configuration

FanFestSDK.init({
  clientId: "your-web-app-id",
  apiBase: "https://api.fanfest.vip",
  appOrigin: "https://fanfest.vip",
  iframe: {
    backgroundColor: "#1a1a2e",
  },
  hostLoginFn: () => {
    // Trigger your site's login flow
    myAuthProvider.login();
  },
  hostRewardsFn: () => {
    // Open your rewards page
    window.location.href = "/rewards";
  },
});

Embed Container

Add a container element anywhere in your page:

<div id="fanfest-embed" style="width: 100%; height: 600px;"></div>

The SDK looks for elements with id="fanfest-embed". You control the size of the embed by styling this container — the iframe fills 100% of its parent's width and height.

Dynamic containers

The SDK uses a MutationObserver to watch for new fanfest-embed containers. You can add containers to the DOM at any time after calling init() and the SDK will automatically set up the embed inside them.

Public SDK Methods

After initialization, the SDK exposes these methods:

Method	Signature	Description
init()	(options: object) => Promise<void>	Initialize the SDK. Can only be called once.
trackEvent()	(payload: TrackEventPayload) => Promise<TrackEventResponse>	Track a user engagement event. See Event Tracking.
registerActionMapping()	(payload: ActionMappingPayload) => void	Map action names to channel action IDs. See Advanced Patterns.
login()	() => Promise<void>	Initiate silent SSO authentication. See SSO Integration.
logout()	() => Promise<void>	Clear the current auth state.

Static Properties

Property	Value	Description
SDK.embedElementId	"fanfest-embed-element"	The id attribute of the generated iframe element
SDK.embedContainerId	"fanfest-embed"	The id attribute expected on the container div

Next Steps

• Configuration Reference — Detailed options reference with code examples and troubleshooting
• Advanced Patterns — Custom callbacks, multiple embeds, responsive sizing, action mapping
• Event Tracking — Track user engagement with declarative or imperative APIs
• SSO Integration — Add user identification and cross-platform tracking
• SDK Architecture — How the SDK works internally