How to use Freewheel AdManager with Vega

[freewheelvi]

Editor’s note: *Current code in this document has been tested on Vega 0.10.4. 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:

Medhod	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 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 width. 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.

0. Download the SDK

   • Download the SDK the file name is AdManager_Kepler_beta.js
   • input the file into your project.

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

1. Obtain Content Metadata

   • For video playback, use a KeplerVideoView element:

   <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();
   const videoRef = useRef(null);
    
   // 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);
   

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

3. 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 XMLHTTRequests 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 ...
   };
   
   

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();
   }
   

5. 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:
AdManager SDK API Documentation