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 plays ads during ad breaks, either on a video surface shared with the main player or on its own dedicated surface. 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
Set up the video surfaces for shared or dual surface mode
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, session IDs, and surface handles.

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

import {
  IPlayerSessionId,
  IPlayerSessionMediaInfo,
  IPlayerSessionStatus,
  IPlayerSessionState,
  IViewHandle,
} 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);

// Surface handles
const surfaceHandleRef = useRef<IViewHandle | undefined>(undefined);   // Main surface (shared surface mode uses it for both players)
const adSurfaceHandleRef = useRef<IViewHandle | undefined>(undefined); // Ad surface (dual surface mode only)

// 'sharedSurface' or 'dualSurface'
const surfaceMode: 'sharedSurface' | 'dualSurface' = 'dualSurface';

Set up the video surfaces

Choose a surface mode. For the differences between the modes, see Surface modes.

Shared surface: Render one KeplerVideoSurfaceView and store its handle in surfaceHandleRef. Both player sessions use this surface in turn.
Dual surface: Render a second KeplerVideoSurfaceView on top of the main surface for the ad player session, and store its handle in adSurfaceHandleRef.

const onAdSurfaceViewCreated = useCallback((surfaceHandle: string): void => {
  adSurfaceHandleRef.current = { handle: surfaceHandle };
}, []);

const onAdSurfaceViewDestroyed = useCallback((surfaceHandle: string): void => {
  adSurfaceHandleRef.current = undefined;
}, []);

// In your render output:
{/* Main content surface */}
<View style={{ position: 'absolute', top: 0, bottom: 0, left: 0, right: 0, zIndex: 1 }}>
  <KeplerVideoSurfaceView
    scalingmode='fit'
    onSurfaceViewCreated={onSurfaceViewCreated}
    onSurfaceViewDestroyed={onSurfaceViewDestroyed}
  />
</View>

{/* Ad surface: dual surface mode only */}
{surfaceMode === 'dualSurface' && (
  <View style={{ position: 'absolute', top: 0, bottom: 0, left: 0, right: 0, zIndex: 2 }}>
    <KeplerVideoSurfaceView
      scalingmode='fit'
      onSurfaceViewCreated={onAdSurfaceViewCreated}
      onSurfaceViewDestroyed={onAdSurfaceViewDestroyed}
    />
  </View>
)}

If your ads can have a different aspect ratio than the main content, see Handling ads with different aspect ratios.

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, give the ad player session a surface and play the ad.

Shared surface: Clear the main session’s surface, then set the same surface on the ad session.
Dual surface: Set the ad surface on the ad session. Don’t clear the main session’s surface.

const clearMainSurfaceHandle = async () => {
  await playerClient.current?.clearVideoView(playerSessionId.current);
};

const setAdSurfaceHandle = async () => {
  const surface = surfaceMode === 'dualSurface'
    ? adSurfaceHandleRef.current   // Ad renders on its own surface, on top of the main content
    : surfaceHandleRef.current;    // Ad reuses the main surface
  await adPlayerClient.current?.setVideoView(surface, adPlayerSessionId.current);
};

await playerClient.current?.registerStatusListener({
  onSessionStatusChanged: async (updatedStatus: Array<IPlayerSessionStatus>) => {
    const mainStatus = updatedStatus.find(
      s => s.sessionId?.id === playerSessionId.current?.id
    );
    if (mainStatus?.playbackState === IPlayerSessionState.PAUSED && adPlayerClient.current) {
      if (surfaceMode !== 'dualSurface') {
        // Shared surface: release the main surface so the ad can use it
        await clearMainSurfaceHandle();
      }
      await setAdSurfaceHandle();
      await 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. In shared surface mode, set the surface on the main session again before you resume. In dual surface mode, the main session still has its surface.

const clearAdSurfaceHandle = async () => {
  await adPlayerClient.current?.clearVideoView(adPlayerSessionId.current);
};

const setMainSurfaceHandle = async () => {
  await playerClient.current?.setVideoView(surfaceHandleRef.current, playerSessionId.current);
};

const onAdEnded = async () => {
  await clearAdSurfaceHandle();
  cleanupAdPlayer();
  if (surfaceMode !== 'dualSurface') {
    // Shared surface: give the surface back to the main session
    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

​Set up the video surfaces

​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