PandaScore Iframe SDK

PandaScore Iframe SDK is built to help parent applications communicate reliably with the PandaScore sportsbook iframe. It lets you initialize the iframe, exchange typed messages, react to iframe navigation requests, and keep user context (such as balance) in sync.

Features

• Secure parent/iframe communication powered by MessageChannel.
• Typed TypeScript API
• Automatic iframe bootstrap and config handshake.
• Two navigation modes: parent-driven or iframe-driven.
• ESM, CJS, and global bundle support for flexible integration.

Table of Contents

• PandaScore Iframe SDK
  • Table of Contents
  • Installation
  • Usage
    • Constructor parameters
    • SDK status updates (onIframeStatusUpdate)
    • Navigation modes
    • Send balance updates
    • Destroy the SDK instance

Installation

Install the SDK with yarn:

yarn add @pandascore/iframe-sdk

If you use a script tag integration, build the SDK (or download it from the package) and load the global bundle:

<script src="path/to/pandascore-sdk.iife.js"></script>

The global bundle exposes PandascoreSDK on window.

Usage

To use the SDK, create a new PandascoreSDK instance and initialize it with your iframe settings and runtime options:

const sdk = new PandascoreSDK({
  container: document.getElementById('iframe-container')!,
  customerId: 'your-customer-id',
  token: 'your-auth-token',
  iframeUrl: 'https://iframe.pandascore.co',
  debugMode: false,
  rootUrl: '/play',
  onNavigate: (path, applyNavigation) => {
    // Optional: parent app handles routing, then notifies iframe
    applyNavigation();
  },
  onIframeStatusUpdate: state => {
    console.log('SDK state:', state);
  },
  options: {
    balance: {
      amount: 1000,
      currency: 'USD'
    },
    initialPath: '/',
    lang: 'en-GB',
    theme: 'default'
  }
});

Constructor parameters

Required parameters

• container (Element): DOM element where the iframe will be mounted.
• customerId (string): Your PandaScore customer ID.
• token (string): Authentication token used by the iframe.
• options (object): Runtime iframe options.
• options.balance (object): User balance payload.
• options.balance.amount (number): Non-negative integer amount.
• options.balance.currency (string): Currency code.

Optional parameters

• rootUrl (string): Parent app path prefix after the origin. Must start with /.
• parents (string[]): Ordered list of allowed parent origins.
• onNavigate ((path: string, applyNavigation: () => void) => void): Optional callback fired when iframe requests navigation.
• onIframeStatusUpdate ((state: PandascoreIframeStatus) => void): Callback fired when SDK lifecycle state changes.
• debugMode (boolean): Enables SDK debug logs when set to true.
• options.initialPath (string): Initial path inside iframe.
• options.lang (string): Language code.
• options.theme (string): Theme identifier.

Specificities

rootUrl behavior

rootUrl defines where your iframe integration lives inside your parent app, after the domain origin.

• Parent app origin: https://website.com
• rootUrl: '/iframe'
• Iframe internal route: /live
• Generated absolute link: https://website.com/iframe/esports

If your integration is mounted at the site root, you can omit this parameter.

Valid examples:

• '/iframe'
• '/sportsbook'
• '/'

Invalid examples:

• 'iframe' (missing leading slash)
• 'https://website.com/iframe' (must be path only, not full URL)

SDK status updates (onIframeStatusUpdate)

Use onIframeStatusUpdate to observe the SDK lifecycle and react in your app (loading states, fallbacks, or teardown logic).

onIframeStatusUpdate can receive:

• 'INITIALIZING': SDK constructor passed validation and initialization started.
• 'INITIALIZED': Message channel is ready and communication with the iframe is active.
• 'FAILED': Initialization failed due to invalid constructor params or setup issues.
• 'DESTROYED': destroy() was called and resources/listeners were cleaned up.

Navigation modes

The SDK automatically picks one of two navigation behaviors, depending on if you're using the onNavigate callback.

1) Parent-driven navigation (onNavigate provided)

When the iframe requests a navigation, the SDK triggers onNavigate(path, applyNavigation) in your parent app. Your app decides whether and how to navigate (router guards, redirects, analytics, permissions, etc.). The path value always starts with /.

After your app applies navigation, notify the iframe by calling either:

• applyNavigation() from inside the onNavigate callback (helper bound to the requested path)
• sdk.navigate(path) if you're handling navigation elsewhere (explicit call)

This requires more integration work, but it gives three important benefits:

• Shareable pages (URL stays synchronized in the parent app).
• Links can be opened in new tabs.
• Back/forward browser arrows work with proper parent/iframe sync.

const sdk = new PandascoreSDK({
  // ...other params
  onNavigate: (path, applyNavigation) => {
    console.log('Iframe requested path:', path);
    // Example: router.push(path)
    applyNavigation();
  },
  options: {
    balance: { amount: 1000, currency: 'USD' }
  }
});

When you call sdk.navigate(path), the SDK automatically strips the configured rootUrl (if present) before sending the path to the iframe. In most integrations, you do not need to handle that prefix yourself. It is still recommended to handle it defensively in your own router integration to avoid corner cases.

2) Iframe-driven navigation (onNavigate omitted)

If onNavigate is not provided, the iframe handles navigation internally. To avoid broken behavior, iframe links are rendered without shareable hrefs:

• They cannot be opened in a new tab.
• Their link URL cannot be copied from standard link interactions.

Methods

Navigate

To programmatically trigger a navigation in the iframe, call sdk.navigate(path). See the previous section Navigation modes for detailed information about navigation behaviors and integration with your app's router.

Send balance updates

Call sendBalance whenever the user balance changes in the parent app.

sdk.sendBalance({
  amount: 1500,
  currency: 'USD'
});

Destroy the SDK instance

Call destroy when the iframe should be unmounted or when leaving the page.

sdk.destroy();