@turbo-player/integration-web-component

@turbo-player/integration-web-component

Introduction

@turbo-player/integration-web-component exposes a Web Component and types to easily integrate the turbo player.

If you use React, you can install the @turbo-player/integration-react package instead.

Usage

Loading & integrating the player (TypeScript)

import {
  IntegrationEvent,
  createIntegrationClient
} from '@turbo-player/integration-web-component';

// provided by the turbo player team
const MODULE_URL = 'https://player.example.com/integration.js';
// matches the custom element tag name defined in the integration script (MODULE_URL)
const TAG_NAME = 'my-integration';

const client = createIntegrationClient({
  moduleUrl: MODULE_URL,
  tagName: TAG_NAME
});

// Get the container element where the player will be placed
const container = document.getElementById('player-container-on-site');
const integrationId = 'FILL_IN_INTEGRATION_ID';
const playlistId = 'FILL_IN_PLAYLIST_ID';
// It makes sense to load integration css
// as early as possible to reduce layout shifts.
client.loadStyles(integrationId);
// load the integration web component
client.loadComponent();
// create the fully typed integration element
const integration = document.createElement(TAG_NAME);
integration.setAttribute('integration-id', integrationId);
integration.setAttribute('playlist-id', playlistId);
integration.addEventListener(IntegrationEvent.CONTENT_START, () => {
  console.log('content start', integration.content);
});
// attach the integration element
container.appendChild(integration);
// wait until the integration was upgraded to access web component methods
await window.customElements.whenDefined(TAG_NAME);
integration.play();

Implementing a public API script (TypeScript)

import {
  IntegrationEvent,
  type ConnectIntegration
} from '@turbo-player/integration-web-component';

// with this you get a fully typed integration
export const connectIntegration: ConnectIntegration = (integration) => {
  integration.addEventListener(IntegrationEvent.CONTENT_PLAY, () => {
    console.log('play', integration.content);
  });
};

Host Context

Use getHostContext() to provide global application context and provider-specific user tokens to all integration instances on the page.

getHostContext() waits for the integration component to be loaded and returns the same singleton instance that the running player uses.

import { createIntegrationClient } from '@turbo-player/integration-web-component';

// provided by the turbo player team
const MODULE_URL = 'https://player.example.com/integration.js';
// matches the custom element tag name defined in the integration script (MODULE_URL)
const TAG_NAME = 'my-integration';

const client = createIntegrationClient({
  moduleUrl: MODULE_URL,
  tagName: TAG_NAME
});

const hostContext = await client.getHostContext();

hostContext.set({
  // Plain values — used as-is
  appVersion: '2.3.0',
  appName: 'my-app',
  deviceId: { id: '...', name: 'idfa' },

  // Resolver functions — called each time the player needs the value,
  // so they can return fresh data (e.g. after consent changes)
  userIds: {
    // Each key is the ID name; the value is a static definition or a resolver function.
    // Return null to explicitly opt out (e.g. when consent is missing).
    netId: async ({ consent }) => consent ? { id: await cmp.getNetId() } : null,
  },

  // Provider-specific context (tokens, subscription state, ...)
  providers: {
    'my-provider': async () => ({
      token: await myAuth.getToken(),
      subscriptionState: userState
    })
  }
});

Calling set() multiple times merges incrementally — previously set values are preserved unless overwritten:

// Initial setup
hostContext.set({ appVersion: '2.3.0', appName: 'my-app' });

// Later — adds providers without removing appVersion/appName
hostContext.set({
  providers: {
    'my-provider': async () => ({ token: await myAuth.getToken() })
  }
});