Implement client-side ad insertion using the Headless approach

In this tutorial, you’ll implement client-side ad insertion (CSAI) in your Vega app using the Headless approach. This approach uses a client-server architecture where IPlayerClient instances in the UI layer communicate with VideoPlayer instances in a separate service layer via JavaScript Interface (JSI)-based inter-process communication (IPC). You’ll set up a dual-player architecture with a main player client for content and an ad player client that takes over a shared video surface during ad breaks. The examples in this tutorial demonstrate pre-buffered ads for seamless ad transitions. For background on CSAI concepts, techniques, and sync strategies, see Client-side ad insertion in Vega. In this tutorial, you learn how to:

Set up player client references and imports
Detect an ad marker and pre-initialize the ad player client
Wait for the ad to buffer, then pause main content
Switch the video surface and play the ad
Return to main content after the ad ends

Prerequisites

Vega development environment set up
Vega SDK v0.22 or later
@amazon-devices/kepler-player-client and @amazon-devices/kepler-player-server packages installed
Main content player client already initialized and connected to the service
Basic knowledge of React Native and TypeScript

Set up player client references

Import the required packages and create refs for the main player client, ad player client, and session IDs.

import {
  PlayerClientFactory,
  IPlayerClient,
  IPlayerSessionPositionListener,
} from '@amazon-devices/kepler-player-client';

import {
  IPlayerSessionId,
  IPlayerSessionMediaInfo,
  IPlayerSessionStatus,
  IPlayerSessionState,
} from '@amazon-devices/kepler-player-server';

// Player client references
const playerClient = useRef<IPlayerClient | undefined>(undefined);       // Main content player client (already initialized)
const adPlayerClient = useRef<IPlayerClient | undefined>(undefined);     // Ad player client
const playerSessionId = useRef<IPlayerSessionId | undefined>(undefined); // Main session ID
const adPlayerSessionId = useRef<IPlayerSessionId | undefined>(undefined); // Ad session ID
const sessionIdCounter = useRef(1);

Detect the ad marker and pre-initialize the ad player client

When the position listener detects an upcoming ad break, pre-initialize the ad player client with autoPlay=false and register listeners to know when the ad is buffered and when it ends.

Set up a position listener to detect upcoming ad breaks.

const positionListener: IPlayerSessionPositionListener = {
  onPositionUpdated: (updatedPosition) => {
    const currentTime = updatedPosition[0]?.position || 0;
    // App-specific logic to determine if an ad break is approaching
    if (adBreakApproaching(currentTime)) {
      initializeAdPlayer(adMediaInfo);
    }
  },
};

Create the ad player client initialization function. Register a status listener to detect the READY and ENDED states. On platforms where IPlayerSessionState.READY is not available, the service sends a playerReady message as a fallback.

const initializeAdPlayer = async (adMediaInfo: IPlayerSessionMediaInfo) => {
  const factory = new PlayerClientFactory();
  adPlayerClient.current = factory.getOrMakeClient(serviceComponentId);
  adPlayerSessionId.current = { id: sessionIdCounter.current++ };

  // Register status listener to detect ENDED state (and READY if available)
  await adPlayerClient.current?.registerStatusListener({
 onSessionStatusChanged: (updatedStatus: Array<IPlayerSessionStatus>) => {
   const adStatus = updatedStatus.find(
     s => s.sessionId?.id === adPlayerSessionId.current?.id
   );
   if (
     IPlayerSessionState.READY !== undefined &&
     adStatus?.playbackState === IPlayerSessionState.READY
   ) {
     onAdReady();
   } else if (adStatus?.playbackState === IPlayerSessionState.ENDED) {
     onAdEnded();
   }
 }
  }, adPlayerSessionId.current);

  // Fallback: On platforms where IPlayerSessionState.READY is not available,
  // the service sends a 'playerReady' message instead
  if (IPlayerSessionState.READY === undefined) {
 await adPlayerClient.current?.registerMessageListener(
   {
     onMessageReceived: (message: any) => {
       if (message.type === 'playerReady') {
         onAdReady();
       }
     },
   },
   adPlayerSessionId.current,
 );
  }

  // Load ad with autoPlay=false for manual control
  await adPlayerClient.current?.load(
 adMediaInfo,
 { startPosition: 0, autoPlay: false },
 adPlayerSessionId.current,
  );
};

Wait for the ad to buffer, then pause main content

After the ad player signals READY (buffered) and the position listener detects the ad start time is reached, pause the main content.

let adReady = false;

const onAdReady = () => {
  adReady = true;
  // Wait for position listener to detect ad start time
};

// In position listener, when ad start time is reached and ad is ready:
if (adReady && currentTime >= adStartTime) {
  playerClient.current?.pause(playerSessionId.current);
}

Switch the surface and play the ad

When the main content status changes to PAUSED, clear the main surface and hand it to the ad player.

await playerClient.current?.registerStatusListener({
  onSessionStatusChanged: (updatedStatus: Array<IPlayerSessionStatus>) => {
    const mainStatus = updatedStatus.find(
      s => s.sessionId?.id === playerSessionId.current?.id
    );
    if (mainStatus?.playbackState === IPlayerSessionState.PAUSED && adPlayerClient.current) {
      clearMainSurfaceHandle();
      setAdSurfaceHandle();
      adPlayerClient.current?.play(adPlayerSessionId.current);
    }
  }
}, playerSessionId.current);

Return to main content

After the ad ends, clear the ad surface, clean up the ad player client, and resume main content.

const onAdEnded = async () => {
  await clearAdSurfaceHandle();
  cleanupAdPlayer();
  await setMainSurfaceHandle();
  await playerClient.current?.play(playerSessionId.current);
};

const cleanupAdPlayer = () => {
  if (!adPlayerClient.current) return;
  adPlayerClient.current.unloadSync(1000, adPlayerSessionId.current);
  adPlayerClient.current = undefined;
  adReady = false;
};

Clean up resources

When your component unmounts or the player session ends, unload the ad player client and release resources.

const cleanup = () => {
  if (adPlayerClient.current) {
    adPlayerClient.current.unloadSync(1000, adPlayerSessionId.current);
    adPlayerClient.current = undefined;
  }
  // Main player client cleanup handled by your existing teardown logic
};

​Prerequisites

​Set up player client references

​Detect the ad marker and pre-initialize the ad player client

​Wait for the ad to buffer, then pause main content

​Switch the surface and play the ad

​Return to main content

​Clean up resources

​Related content