How to use Freewheel AdManager with Vega

freewheelvi · July 15, 2024, 2:09pm

Editor’s note: Current code in this document has been tested on Vega 0.21. The Vega SDK is continuously being updated, and the Freewheel Video Integration team will also keep this document updated. Feel free to email vis@freewheel.com or create a Zendesk ticket for Freewheel team for any questions or concerns.

Overview

This document gives a general description of how to build a video player integrating with the Freewheel Vega AdManager Beta SDK.
Please contact Freewheel team to ask detailed User Guide document file and Demo player

Prerequisites

To use Freewheel Vega AdManager, please ask your dedicated Solutions Engineer to create a player profile for your integration that supports the CustomPlayerRenderer.
Currently, Vega AdManager only supports video and VAST ads.
Vega AdManager uses the CustomPlayerRenderer to play video ads.

See the JavaScript/HTML5 AdManager CustomPlayerRenderer User Guide for additional info.

Basic Knowledge

CustomerPlayerRenderer

AdManager’s CustomPlayerRenderer expects clients to provide AdManager with their own Custom Player object to render advertisements. This Custom Player object should implement the following methods:

Method	Description
`getDuration()`	(number) Returns the duration of the currently playing video.
`getPlayheadTime()`	(number) Returns the playhead time of the currently playing video.
`open(creativeRendition, adListener)`	Set the ad source url and starts playback. Called by renderer during ‘start’ method.
`playPause(isPause)`	Pause or resume video playback.

After implementing the CustomPlayerRenderer, you can use the following method to register it using the Context. registerCustomPlayer(customPlayer) method:

const customPlayer = useRef({
  open: function(creativeRendition, listener) {
    const url = creativeRendition.getPrimaryCreativeRenditionAsset().getProxiedUrl();
    console.log('DemoVideoPlayer.open url:', url);
    adListener.current = listener;
    videoRef.current.src = url;
    VideoPlayer.playerSessionClient.setDefaultSeekIntervalInSec(0);
    videoRef.current.play();
  },
  playPause: function(isPause) {
    console.log('DemoVideoPlayer.playPause isPause:', isPause);
    if (isPause) {
      videoRef.current.pause();
    } else {
      videoRef.current.play();
    }
  },
  getDuration: function() {
    return videoRef.current.duration;
  },
  getPlayheadTime: function() {
    return videoRef.current.currentTime;
  },
});

adContext.current.registerCustomPlayer(customPlayer.current);

Polyfill

AdManager’s Vega SDK already includes the following polyfills.

Polyfill functions/properties	(Type) default value	Description
global.window.frames	(Array)	The default value is an empty array. Currently, there are no sub-frames supported in the Amazon Vega SDK.
global.window.screen	(Object) {}	The default value is an empty object. This object is used as a container of screen width and screen height.
global.window.screen.width	(number) 1920	The value of current device width. This value will be used to set up compatible dimensions.
global.window.screen.height	(number) 1080	The value of current device height. This value will be used to set up compatible dimensions.
global.window.location	(Object) {}	The default value is an empty object. This object is used as a container of protocol and host.
global.window.location.protocol	(string) ‘https’	The default value is https. We highly recommended using https as the transfer protocol.
global.window.location.host	(string) ‘amazon-vega’	Unlike the web page opened in a browser, there is no host value in the React Native app. We set the default value to amazon-vega to help our system know this ad request is coming from Amazon Vega SDK project.

Developers are allowed to write their own Polyfill file if necessary.

Mixing Polyfill values is also allowed The new Polyfill value will override the default Polyfill value.

// When developers want to override the polyfill value, make sure you override all of the values
// listed in the table, because these values are required for AdManager to function correctly.
// For example:
global.window.frames = []; //required
global.window.screen = {}; //required
global.window.screen.width = 3840; //required
global.window.screen.height = 2160; //required
global.window.screen.colorDepth = 8 //Your Polyfill property
global.window.location = {}; //required
global.window.location.protocol = 'https'; //required
global.window.location.host = 'amazon-vega-your-appname'; //required
global.window.location.hash = 'player'; //Your Polyfill property

Steps

For details on these steps, please refer to the detailed User Guide document.

Download the SDK

Download the SDK, the file name is AdManager_Vega.js
Input the file into your project.

import "/AdManager_Vega";

export const DemoVideoPlayer = (props) => {
  //...code...
  return (<View></View>)
}

Obtain Content Metadata

For video playback, import VideoPlayer and KeplerVideoView from @amazon-devices/react-native-w3cmedia and use a KeplerVideoView element:

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

<KeplerVideoView
  showControls={false}
  videoPlayer={videoRef.current}
/>

Set up AdManager variables. Please contact your dedicated Solutions Engineer to get the following values.

// These values are used for set up AdManager
// These values can be constants or come from props.
const networkId = 42015;
const server = "https://demo.v.fwmrm.net/ad/g/1";
const profile = "42015:kepler-player-demo"
const videoAssetId = "KeplerVideoAsset";
const siteSectionId = "KeplerSiteSection";

// Video variables and video references
// if the video is playing full screen, use this function to get width and height
const { width: deviceWidth, height: deviceHeight } = useWindowDimensions();

// Initialize VideoPlayer — explicit initialize() call is required before playback
const videoRef = useRef(new VideoPlayer());

// other references
const buttonRef = useRef(null);
const isSlotPaused = useRef(false);
const adManager = useRef(null);
const adContext = useRef(null);
const adSlots = useRef([]);
const currentSlot = useRef(null);
const adListener = useRef(null);

Set up AdManager

Set up AdManager with the following code.

const initAdManager = () => {
  console.log('DemoVideoPlayer.initAdManager');
  tv.freewheel.SDK.disableConsentAutoRetrieval();
  adManager.current = new tv.freewheel.SDK.AdManager();
  adManager.current.setNetwork(data.networkId);
  adManager.current.setServer(data.server);
};

Set up AdContext

Create Context instance and configure the Ad Request

const requestAds = () => {
  console.log('DemoVideoPlayer.requestAds');
  adContext.current = adManager.current.newContext();

  // Setting this parameter will cause AdManager to use XMLHttpRequests for the ad request and beacons
  adContext.current.setParameter(tv.freewheel.SDK.PARAMETER_ENABLE_JS_TRANSPORT, true, tv.freewheel.SDK.PARAMETER_LEVEL_GLOBAL);
  adContext.current.setProfile(data.profile);

  // Set the target
  adContext.current.setVideoAsset('KeplerVideoAsset', 500);
  adContext.current.setSiteSection('KeplerSiteSection');

  // Optional if using custom key-value targeting: Add key-values in the ad request
  adContext.current.addKeyValue('customTargetingKey', 'JSAMDemoPlayer');

  // Add 1 preroll, 1 midroll, 1 postroll slot
  adContext.current.addTemporalSlot('Preroll_1', tv.freewheel.SDK.ADUNIT_PREROLL, 0);
  adContext.current.addTemporalSlot('Midroll_1', tv.freewheel.SDK.ADUNIT_MIDROLL, 5);
  adContext.current.addTemporalSlot('Postroll_1', tv.freewheel.SDK.ADUNIT_POSTROLL, 60);

  // This method is for use with the CustomPlayerRenderer
  adContext.current.registerCustomPlayer(customPlayer.current);

  // Pass the video display base size
  // This value will help video rendition selection to properly select the correct video size
  // if the video is played full screen pass device width and height
  adContext.current.setVideoDisplaySize(0, 0, deviceWidth, deviceHeight);

  // continued in step 4 ...
};

Register Event Listeners and Submit Request

Create Context instance and Configure the Ad Request

const onRequestComplete = (event) => {
  //...function code...
}

const onSlotEnded = (event) => {
  // ...function code...
}

const onRequestContentVideoResume = (event) => {
  // ...function code...
}

const requestAds = () => {
  // ... code from step 3 ...

  // Step #4: Submit ad request
  // Listen to request_complete and slot_ended events.
  adContext.current.addEventListener(tv.freewheel.SDK.EVENT_REQUEST_COMPLETE, onRequestComplete);
  adContext.current.addEventListener(tv.freewheel.SDK.EVENT_SLOT_ENDED, onSlotEnded);
  adContext.current.addEventListener(tv.freewheel.SDK.EVENT_CONTENT_VIDEO_RESUME_REQUEST, onRequestContentVideoResume);
  adContext.current.submitRequest();
}

Handle Ad Playback

Please check the detailed document for more details of the code. Make sure the following functionalities are implemented.

Play preroll — Make sure the content starts playing after the preroll ad ends.
Play midroll — Detect the Timeline of the content and play the midroll ad at the right time.
Play postroll — Play the postroll ad after the content ends.

References

For more detailed API information, please refer to the following documents:

Last updated: Dec 3, 2025

Topic		Replies	Views
Sample Code for Client Side Ad-Insertion (CSAI) Knowledge Base	0	450	March 2, 2026
Shaka Player Admanager MediaTailor Integration Issue Q&A	8	143	December 4, 2025
Logix Google IMA Ads Manager Knowledge Base knowledge-base	0	402	November 8, 2024
Playback freeze and app crash when seeking to an ad break start time Bug Reports	3	61	January 13, 2026
Bitmovin Player Support for Vega Knowledge Base	0	526	December 15, 2023