Iframe Bridge

<script 
   src="https://cdn.bluebillywig.com/scripts/bbiframebridge/latest/bbiframebridge-standalone.js">
</script>

The standalone bundle bootstraps automatically (no further setup required).
Subresource Integrity
To pin a specific version and verify its integrity, use the versioned URL with an integrity attribute:

<script
  src="https://cdn.bluebillywig.com/scripts/bbiframebridge/{version}/bbiframebridge-standalone.js"
  integrity="sha384-{hash}"
  crossorigin="anonymous"
></script>

1.2 | NPM

"dependencies": {
  "bbiframebridge": "https://github.com/bluebillywig/bbiframebridge"
}

import BBIframeBridge from 'bbiframebridge';

BBIframeBridge.bootstrap();

2.0 | Setup

2.1 | Automatic (CDN standalone)

The standalone bundle calls BBIframeBridge.bootstrap() automatically when the script loads. It scans the page for Blue Billywig player iframes and creates a bridge instance for each one.

2.2 | Manual (NPM)

Call BBIframeBridge.bootstrap() after the page has loaded and your iframes are present in the DOM.

import BBIframeBridge from 'bbiframebridge';

document.addEventListener('DOMContentLoaded', () => {
  BBIframeBridge.bootstrap();
});

bootstrap() can only be called once per page load. It stores the created instances in window.bluebillywig.BBIframeBridges.

3.0 | Accessing Bridge Instances

After bootstrapping, one bridge instance is created per player iframe. Instances are available as an array:

const bridges = window.bluebillywig.BBIframeBridges;

const bridge = bridges[0]; // first player on the page

If you have multiple players, each has its own bridge at the corresponding index.

4.0 | Calling Player Methods

4.1 | Fire-and-forget – callChild(methodName, params)

Use this for methods that don’t return a value.

bridge.callChild('play');
bridge.callChild('pause');
bridge.callChild('seek', [30]); // seek to 30 seconds
bridge.callChild('setVolume', [0.5]); // set volume to 50%

Parameters:

4.2 | With return value – callChild(methodName, params)

Use this when you need a value back from the player. Returns a Promise that resolves with the return value, or null if no response is received within 240 ms.

const duration = await bridge.callChildPromise('getDuration');
const playoutData = await bridge.callChildPromise('getPlayoutData');

Parameters:

Returns: Promise<any> – resolves to the method’s return value, or null on timeout.

For a full list of available player methods, refer to the Blue Billywig Player API documentation.

5.0 | Resizing the Iframe

5.1 | setIframeSize(dimensions)

Resize the player iframe from the parent page.

bridge.setIframeSize({ width: '100%', height: '480px' });
bridge.setIframeSize({ height: '360px' }); // height only
bridge.setIframeSize({ width: 1280, height: 720 }); // numeric values become px

dimensions is an object with optional width and height keys. Values can be a number (converted to px) or a string with any standard CSS unit: px, %, em, rem, vh, vw, vmin, vmax.

Returns: true if the dimensions were applied, false if validation failed (e.g. invalid unit, negative value).

6.0 | Fullscreen

The bridge manages both native fullscreen and a CSS fallback (“full browser”) mode.

6.1 | enterFullScreen(element)

Request fullscreen for a given element. First attempts the native browser fullscreen API; falls back to CSS-based fullscreen if unavailable.

const iframe = document.querySelector('iframe');
bridge.enterFullScreen(iframe);

Returns: true if the request succeeded, false otherwise.

6.2 | cancelFullScreen(element)

Exit fullscreen.

bridge.cancelFullScreen(iframe);

Returns: true if exit succeeded, false otherwise.

6.3 | CSS-only fullscreen

If you want fullscreen-like appearance without the native browser API:

bridge.enterFullBrowser(element); // apply CSS fullscreen
bridge.cancelFullBrowser(element); // restore original styles

7.0 | localStorage Proxy

Sandboxed iframes cannot access localStorage directly. The bridge proxies storage through the parent page, making it transparent to the player.

These methods are primarily used internally by the bridge, but are available if needed.

7.1 | cancelFullScreen(element)

Store a value. Pass null or undefined to delete the key.

bridge.setLocalStorageItem('playerPrefs', { volume: 0.5 });
bridge.setLocalStorageItem('playerPrefs', null); // delete

7.2 | getLocalStorageItem(key)

Retrieve a stored value.

const prefs = bridge.getLocalStorageItem('playerPrefs'); // { volume: 0.5 }

Returns: the stored value, or null if the key does not exist.

7.3 | getLocalStorageItems()

Retrieve all stored items as an array.

const items = bridge.getLocalStorageItems(); 
// [{ key: 'playerPrefs', value: { volume: 0.5 } }, ...]

const items = bridge.getLocalStorageItems();
// [{ key: 'playerPrefs', value: { volume: 0.5 } }, ...]

8.0 | Events Forwarded to the Player

The bridge automatically forwards these events from the parent page to the iframe (no action required on your part).

9.0 | Cleanup

When removing a player from the page, call exit() to release all event listeners and observers associated with that bridge.

bridge.exit();

10.0 | Complete Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>BBIframeBridge example</title>
</head>
<body>

  <iframe
    src="https://your-publication.bbvms.com/p/your-playout/c/your-clip.html"
    width="640"
    height="360"
    allowfullscreen
  ></iframe>

  <script 
    src="https://cdn.bluebillywig.com/scripts/bbiframebridge/latest/bbiframebridge-standalone.js">
  </script>

  <script>
    // Bridge instances are ready after the standalone script loads and bootstraps.
    // Wait for the player's own ready event before calling methods.

    const bridge = window.bluebillywig.BBIframeBridges[0];

    // Play the video
    bridge.callChild('play');

    // Get the duration
    bridge.callChildPromise('getDuration').then(duration => {
      console.log('Duration:', duration);
    });

    // Resize the iframe
    bridge.setIframeSize({ width: '100%', height: '360px' });

    // Fullscreen on button click
    document.querySelector('#fs-btn').addEventListener('click', () => {
      const iframe = document.querySelector('iframe');
      bridge.enterFullScreen(iframe);
    });
  </script>

</body>
</html>

Notes 

• bootstrap() only discovers iframes from bbvms.com and mainroll.com domains. If you create a bridge manually via new BBIframeBridge(iframeElement), any iframe is supported.
• callChildPromise has a fixed 240 ms timeout. If the player method takes longer to respond, the promise resolves with null.