Implement client-side ad insertion using the JS approach

In this tutorial, you’ll implement client-side ad insertion (CSAI) in your Vega app using the JS approach. This approach uses direct React Native component integration where VideoPlayer instances are created and managed within the UI component layer. You’ll set up a dual-player architecture with a main player for content and an ad player 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 references and imports
Set up the video surfaces for shared or dual surface mode
Detect an ad marker and pre-initialize the ad player
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/react-native-w3cmedia package installed
Main content player already initialized and playing
Basic knowledge of React Native and TypeScript

Set up player references

Import the required components and create refs for the main player, ad player, and surface handles.

import { VideoPlayer, KeplerVideoSurfaceView } from '@amazon-devices/react-native-w3cmedia';

// Player references
const videoPlayer = useRef<VideoPlayer | null>(null);       // Main content player (already initialized)
const adVideoPlayer = useRef<VideoPlayer | null>(null);     // Ad player
const cachedSurface = useRef<any>(null);                    // Main surface handle (shared surface mode uses it for both players)
const adCachedSurface = useRef<any>(null);                  // Ad surface handle (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 cache its handle in cachedSurface. Both players use this surface in turn.
Dual surface: Render a second KeplerVideoSurfaceView on top of the main surface for the ad player, and cache its handle in adCachedSurface.

const onAdSurfaceViewCreated = (surfaceHandle: string): void => {
  adCachedSurface.current = surfaceHandle;
};

const onAdSurfaceViewDestroyed = (surfaceHandle: string): void => {
  adCachedSurface.current = null;
};

// 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

When the app detects an upcoming ad break (for example, 5 seconds before the ad start time), pre-initialize the ad player and begin buffering the ad content with autoPlay=false.

videoPlayer.current.addEventListener('timeupdate', () => {
  const currentTime = videoPlayer.current?.currentTime || 0;
  // App-specific logic to determine if an ad break is approaching
  // (e.g., VMAP schedule, sidecar file, hardcoded list, or ad SDK callback)
  if (adBreakApproaching(currentTime)) {
    initializeAdPlayer(AD_CONTENT_URL);
  }
});

Create the ad player initialization function. Set autoPlay to false so you control when playback starts.

const initializeAdPlayer = async (adUrl: string) => {
  adVideoPlayer.current = new VideoPlayer();
  await adVideoPlayer.current.initialize();
  adVideoPlayer.current.autoplay = false;
  adVideoPlayer.current.addEventListener('canplay', onAdReady);
  adVideoPlayer.current.addEventListener('ended', onAdEnded);
  adVideoPlayer.current.src = adUrl;
};

Wait for the ad to buffer, then pause main content

After the ad player signals it is buffered (canplay) and the ad start time is reached, pause the main content.

const onAdReady = () => {
  // Ad is buffered — wait for the scheduled ad start time
  // When the position listener detects ad start time is reached:
  videoPlayer.current?.pause();
};

Switch the surface and play the ad

When the main content pauses, give the ad player a surface and play the ad.

Shared surface: Clear the main player’s surface, then assign the same surface to the ad player.
Dual surface: Assign the ad surface to the ad player. Don’t clear the main player’s surface.

videoPlayer.current.addEventListener('pause', () => {
  if (surfaceMode === 'dualSurface') {
    // Ad renders on its own surface, on top of the main content
    adVideoPlayer.current?.setSurfaceHandle(adCachedSurface.current);
  } else {
    // Clear main player surface and assign it to the ad player
    videoPlayer.current?.clearSurfaceHandle(cachedSurface.current);
    adVideoPlayer.current?.setSurfaceHandle(cachedSurface.current);
  }
  adVideoPlayer.current?.play();
});

Return to main content

After the ad finishes, clear the ad surface, clean up the ad player, and resume main content. In shared surface mode, set the surface on the main player again before you resume. In dual surface mode, the main player still has its surface.

const onAdEnded = async () => {
  if (surfaceMode === 'dualSurface') {
    adVideoPlayer.current?.clearSurfaceHandle(adCachedSurface.current);
  } else {
    adVideoPlayer.current?.clearSurfaceHandle(cachedSurface.current);
    videoPlayer.current?.setSurfaceHandle(cachedSurface.current);
  }
  videoPlayer.current?.play();
  await adVideoPlayer.current?.deinitialize();
  adVideoPlayer.current = null;
};

Clean up resources

When your component unmounts or the player session ends, deinitialize both players and release the surface handle.

const cleanup = async () => {
  if (adVideoPlayer.current) {
    await adVideoPlayer.current.deinitialize();
    adVideoPlayer.current = null;
  }
  // Main player cleanup handled by your existing teardown logic
};

​Prerequisites

​Set up player references

​Set up the video surfaces

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

​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