Embed Configuration Reference

This page documents every configuration option available when calling FanFestSDK.init(). All options are validated at runtime using a schema — invalid options throw an error with details about what went wrong.

Options Reference

clientId

• Type: string
• Required: Yes

Your web app identifier from the FanFest dashboard. This tells the SDK which channel to load.

FanFestSDK.init({
  clientId: "abc123-def456-ghi789",
});

To find your client ID, go to your channel's admin panel and navigate to the API Keys section. The web app ID is listed under your web app configuration.

apiBase

• Type: string
• Required: No
• Default: "https://api.fanfest.vip"

The base URL for the FanFest API. Only override this if you are using a staging or testing environment.

FanFestSDK.init({
  clientId: "your-web-app-id",
  apiBase: "https://api.staging.fanfest.vip",
});

The SDK appends /graphql to this URL internally for GraphQL requests, and uses it as the base for REST endpoints like /auth/silent-initiate.

appOrigin

• Type: string
• Required: No
• Default: "https://fanfest.vip"

The origin of the FanFest web application. The SDK uses this to construct the iframe source URL and to validate PostMessage origins for secure communication.

FanFestSDK.init({
  clientId: "your-web-app-id",
  appOrigin: "https://staging.fanfest.vip",
});

Security consideration

The appOrigin is used to validate the origin of incoming PostMessage events. Only change this if you are intentionally targeting a non-production FanFest environment.

iframe

• Type: { backgroundColor: string }
• Required: No
• Default: { backgroundColor: "var(--color-brand-background)" }

Configuration for the embed iframe's appearance.

iframe.backgroundColor

• Type: string
• Required: No (required if iframe object is provided)
• Default: "var(--color-brand-background)"

The CSS background color applied to the iframe element while the embed content loads. This prevents a white flash before your channel's theme is applied.

FanFestSDK.init({
  clientId: "your-web-app-id",
  iframe: {
    backgroundColor: "#1a1a2e", // Dark background matching your site
  },
});

You can use any valid CSS color value: hex (#1a1a2e), RGB (rgb(26, 26, 46)), HSL, or CSS custom properties.

hostLoginFn

• Type: () => void
• Required: No
• Default: undefined

A callback function invoked when the embed needs to trigger a login on your host site. When provided, the SDK binds this function to the window object for security isolation.

FanFestSDK.init({
  clientId: "your-web-app-id",
  hostLoginFn: () => {
    // Trigger your site's authentication flow
    myAuthProvider.redirectToLogin();
  },
});

Requires SSO

hostLoginFn only has effect when you have SSO integration configured. Without SSO, the embed handles login internally using FanFest's built-in authentication.

hostRewardsFn

• Type: () => void
• Required: No
• Default: undefined

A callback function invoked when the embed needs to direct users to your rewards experience. When provided, the SDK binds this function to the window object for security isolation.

FanFestSDK.init({
  clientId: "your-web-app-id",
  hostRewardsFn: () => {
    // Navigate to your rewards page
    window.location.href = "/my-rewards";
  },
});

Requires SSO

hostRewardsFn only has effect when you have SSO integration configured. Without SSO, the embed handles rewards display internally.

enableAutoHeightEmbed

• Type: boolean
• Required: No
• Default: false

When true, the embed iframe automatically resizes its height to match the content inside it. This eliminates the need to set a fixed height on the container <div> and prevents clipped content or excess whitespace.

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

The feature uses the @open-iframe-resizer/core library, which communicates via postMessage between the host page and the embed. Both scripts are lazy-loaded at runtime — enabling this option adds zero bytes to the initial SDK bundle.

Container height

When enableAutoHeightEmbed is true, do not set a fixed height on the <div id="fanfest-embed"> container. Instead, omit the height entirely or use min-height to set a floor:

<!-- Correct: no fixed height -->
<div id="fanfest-embed" style="width: 100%;"></div>

<!-- Also acceptable: minimum floor height -->
<div id="fanfest-embed" style="width: 100%; min-height: 300px;"></div>

<!-- Incorrect: fixed height overrides the auto-resize -->
<div id="fanfest-embed" style="width: 100%; height: 600px;"></div>

Browser compatibility: Chrome 64+, Safari 13.1+, Firefox 69+, Opera 51+.

enableToastNotifications

• Type: boolean
• Required: No
• Default: true

When true (default), the SDK renders toast notifications on the host site — including loyalty reward toasts after tracked actions, the welcome toast shown after authentication, and the auth-state toast center.

Set to false to suppress all SDK-rendered toasts on the host page. Tracking, rewards, and authentication continue to work normally; only the visible toast UI is hidden.

FanFestSDK.init({
  clientId: "your-web-app-id",
  enableToastNotifications: false, // Suppress toasts on the host site
});

Use this when your host site already renders its own notification UI for reward/auth events, or when toasts conflict with the host site's design.

INFO

This option only affects toasts rendered by the SDK on the host page. Notifications shown inside the FanFest embed iframe (e.g. raffles, chat messages) are unaffected.

Complete Configuration Example

FanFestSDK.init({
  clientId: "abc123-def456-ghi789",
  apiBase: "https://api.fanfest.vip",
  appOrigin: "https://fanfest.vip",
  iframe: {
    backgroundColor: "#0f0f23",
  },
  hostLoginFn: () => {
    // Redirect to your identity provider
    auth0Client.loginWithRedirect({
      redirect_uri: window.location.origin + "/callback",
    });
  },
  hostRewardsFn: () => {
    // Open rewards in a modal or navigate
    rewardsModal.open();
  },
});

Validation Errors

The SDK validates all options on initialization. If validation fails, it throws an error with field-level details:

[FanfestSDK] Invalid SDK options

Check the browser console for the detailed field errors logged before the exception. Common validation failures:

Error	Cause	Fix
clientId is required	Missing clientId in options	Add your web app ID
Expected string, received number	Wrong type for a string option	Ensure all string options are strings

Troubleshooting

CORS Issues

If you see CORS errors in the console when the SDK makes API requests:

1. Verify your domain is registered in the FanFest dashboard as an allowed origin for your web app
2. Check that apiBase points to the correct environment
3. Ensure your site is served over HTTPS in production

Content Security Policy (CSP)

If your site uses a Content Security Policy, you need to allow the following:

frame-src https://fanfest.vip https://*.fanfest.vip;
connect-src https://api.fanfest.vip;
script-src https://sdk.production.fanfest.vip;

Adjust the domains if you are using a custom apiBase or appOrigin.

Iframe Sandbox

The SDK creates the embed iframe with the following sandbox permissions:

• allow-same-origin — Required for PostMessage communication
• allow-scripts — Required for the embed application to run
• allow-forms — Required for login and registration forms
• allow-modals — Required for confirmation dialogs
• allow-popups — Required for external links and OAuth flows

The iframe also requests these permissions via the allow attribute:

• autoplay — For video content in shows
• camera and microphone — For live show participation
• fullscreen — For full-screen video viewing
• clipboard-read and clipboard-write — For copy-to-clipboard features

If your CSP or iframe policy restricts any of these, the embed may not function correctly.

Embed Not Appearing

If the embed container exists but no iframe appears:

1. Check the container ID — The element must have id="fanfest-embed" (exact match)
2. Check container dimensions — The container must have a non-zero width and height. The iframe fills 100% of its parent.
3. Check initialization order — Ensure FanFestSDK.init() is called before or after the container is in the DOM (the SDK watches for both)
4. Check the console — Look for SDK error messages prefixed with [FanfestSDK]
5. Verify clientId — An invalid clientId will prevent the web app configuration from loading

Embed Shows White Screen

If the iframe appears but shows a blank page:

1. Check network requests — Verify the iframe URL resolves correctly
2. Check appOrigin — If overridden, ensure it points to a valid FanFest instance
3. Check CSP — Your Content Security Policy may be blocking the iframe content
4. Check browser console for errors — Both in the parent page and within the iframe (right-click the iframe, "Inspect frame")