Implement client-side ad insertion using the Headless approach

• 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 {
  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

1. 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);
    }
     },
   };
   
2. 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

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

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

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

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

​

Related content

• Client-side ad insertion in Vega
• Implement client-side ad insertion using the JS approach