PRODUCT
Follow

Overview

The purpose of this guide is to document the use of Sizmek's Video Cue Points Feature to synchronize visual elements or animations in a separate interactive layer above video in Workspace based ads. Throughout this guide and subsequent pages, we hope to provide a comprehensive overview of the native HTML5 video player, its attributes, methods, events, and common uses. Additionally, this guide should provide a complete understanding of how to attach the Video Cue Points Feature to your video assets. Thus allowing developers to both synchronize animations or visibility of elements and programmatically add third party tracking pixels.

video.jpg

Demos/Downloads

The following table provides links to the template and demos for the Sizmek Cue Points ad feature.

Template

Sizmek_Cue_Points_1_0_0.zip

Demos

Preview demo

By combining the video tag with the Sizmek Cue Points Feature, developers can easily synchronize animations and interactivity with their video content to enrich the user experience and foster improved user interaction rates. The steps are detailed below, for adding the Sizmek Cue Point Feature to your Workspace with Video and how to trigger your animation files when those Cue Points fire in the video to the coordinate additional timed content and/or animation.

 

Cue Points can be defined, updated and in some case searched by:

  • name
  • start time & end time or single event time
  • start function & end function or single function
  • percentage (when true, time is a calculated percentage of video duration, otherwise, time values will be in seconds, ex. 1, 2.5, etc. )
  • uniqueness (when true, this only fires once per ad impression, otherwise the event will occur everytime Cue Point is fired.)
  • disabled (when true, cuepoint must be enabled programmatically, otherwise it will execute when Cue Point is reached.)
  • video ("all" is default or use exact video filename without file extension)

 

Support Matrix

Supported Platforms     Supported Properties  
Windows Internet Explorer 11, Microsoft Edge, Firefox, Chrome   Polite Loading Yes
Mac Safari, Firefox, Chrome   Safeframe Support Yes
iPhone iOS 11 and later   MRAID (in App Support) No
iPad iOS 11 and later   Adkit Ready Yes
Android Phone Android 6 and later   Secure Serving Yes
Android Tablet Android 6 and later   SAS Supported Yes

 

 

Ad Setup Instruction

  1. The first step is to include the cuepoints.js to your index.html file. This should occur before adkit is loaded so the Sizmek Cue Points Feature object is available. It is important to add this before adding the adkit include head of your Workspace index.html file.
    <script src="scripts/cuepoints.js"></script> 
    // your animation script below
    <script src="scripts/your_animations.js"></script>
  2. Next, the config object must be defined before creating a Sizmek Cue Points Feature Object.

    var config = {currentEnviro: 'feature'};
    var sizmekCuePointsManager = sizmekCuePointsManager(config);

  3. Thirdly, the when adkit has loaded, config object is passed into the creation of the new sizmekCuepointManager.

    sizmekCuePointsManager.initCuePoints();

  4. It is also important to attach event listeners to your video tag in order to enhance your ad with synchronized, rich content that is not encoded in the video.

    theVideo.addEventListener("timeupdate", sizmekCuePointsManager.checkCuepointElem, false);
    theVideo.addEventListener("ended", sizmekCuePointsManager.vidEndPercentCheck, false);
    theVideo.addEventListener("seeked", sizmekCuePointsManager.resetCuePoints, false);

  5. When you are finished authoring your ad, put all of its files in one folder and compress that folder to a ZIP. When uploaded to the platform, the ZIP's files will automatically be extracted, creating a Workspace on the platform.

 

Example HTML <head> tag snippet

Please see the full script, below, needed to implement the video player into your ad.
You can code your specific cue points in your favorite code/text editor or create your Cue Points with this tool.

Note: the code snippet below does not include styling which can affect the display and layout of the page. In the absence of styling, the video will load at the width and height of the video source possibly leading to undesirable results.



<!-- BEGIN Cue Points Feature inclusion <head> tag portion -->
<script >

var config = {currentEnviro: 'feature'};
var sizmekCuePointsManager = sizmekCuePointsManager(config);

var cuepoints = [
{name:'FirstCuepoint', start: 1, end: 10, percent: false, startCueFn: 'beginCuePoint1', endCueFn: 'endCuePoint1', unique: false, disabled: false, video: 'all'},
{name:'SecondCuepoint', start: 4, end: 9.7, percent: false, startCueFn: 'beginCuePoint2', endCueFn: 'endCuePoint2', unique: false, disabled: false, video: 'all'},
{name:'ThirdCuepoint', start: 30, end: 100, percent: false, startCueFn: 'beginCuePoint3', endCueFn: 'endCuePoint3', unique: false, disabled: false, video: 'all'},
{name:'FinalCuepoint', start: 20.1, end: 30, percent: false, startCueFn: 'beginCuePoint4', endCueFn: 'endCuePoint4', unique: false, disabled: false, video: 'all'}
];
var singleevent = [
{name: "BEGIN", start: 1, percent: true, fn: 'PixelTracker1', unique: false, disabled: false, video: 'all'},
{name: "25_COMPLETE", start: 25, percent: true, fn: 'PixelTracker2', unique: false, disabled: false, video: 'all'},
{name: "50_COMPLETE", start: 50, percent: true, fn: 'PixelTracker3', unique: false, disabled: false, video: 'all'},
{name: "75_COMPLETE", start: 75, percent: true, fn: 'PixelTracker4', unique: false, disabled: false, video: 'all'},
{name: "100_COMPLETE", start: 100, percent: true, fn: 'PixelTracker5', unique: false, disabled: false, video: 'all'}
];

</script>
<!-- END Cue Points Feature inclusion <head> tag portion -->


 

  1. The first step is to include the cuepoints.js and your animation.js to your index.html file. This should occur before Adkit is loaded so the Sizmek Cue Points Feature object is available. It is important to add this before adding the adkit include in the head tag of your Workspace index.html file.
    <script src="scripts/cuepoints.js"></script> 
    // your animation script below
    <script src="scripts/your_animations.js"></script>
  2. Next, the config object must be defined before creating a Sizmek Cue Points Feature Object, in the VPAID workspace, it should occur in within the script.js and NOT in the index.html due to VPAID restrictions.

    var config = {currentEnviro: 'vpaid'};
    var Sizmek Cue Points Feature = sizmekCuePointsManager(config);

  3. Thirdly, the when adkit has loaded, config object is passed into the creation of the new sizmekCuepointManager.

    function initCreative(){
    initButtons();
    addVideoEvents();
    sizmekCuePointsManager.initCuePoints.call();
    sizmekCuePointsManager.initCuepointAnimations.call();
    }
  4. It is also important to attach event listeners to your video tag in order to enhance your ad with synchronized, rich content that is not encoded in the video.

    var isEnded = false;
    function resetIsEnded(){
    isEnded = false;
    }

    function onVideoEvent(event){
    switch(event.type){
    case "ended" :
    isEnded = true;
    setTimeout( resetIsEnded, 3000);
    sizmekCuePointsManager.vidEndFinalCheck();
    break;
    case "pause" : case "play" :
    onPlaybackChanged(event);
    break;
    case "volumechange":
    onAudioChanged(event);
    break;
    case "timeupdate" :
    if(isEnded == false){
    timesupdated++;
    sizmekCuePointsManager.checkCuepointElem();
    }
    break;
    }
    }

  5. When you are finished authoring your ad, put all of its files in one folder and compress that folder to a ZIP. When uploaded to the platform, the ZIP's files will automatically be extracted, creating a Workspace on the platform.

 

Example script.js inclusion snippet

Please see the full script, below, needed to implement the video player into your ad.
You can code your specific cue points in your favorite editor or create your Cue Points with this tool.

Note: the code snippet below does not include styling which can affect the display and layout of the page. In the absence of styling, the video will load at the width and height of the video source possibly leading to undesirable results.


/* BEGIN Cue Points Feature inclusion portion */

var config = {currentEnviro: 'vpaid'};
var Sizmek Cue Points Feature = sizmekCuePointsManager(config);

var cuepoints = [
{name:'FirstCuepoint', start: 1, end: 10, percent: false, startCueFn: 'beginCuePoint1', endCueFn: 'endCuePoint1', unique: false, disabled: false, video: 'all'},
{name:'SecondCuepoint', start: 4, end: 9.7, percent: false, startCueFn: 'beginCuePoint2', endCueFn: 'endCuePoint2', unique: false, disabled: false, video: 'all'},
{name:'ThirdCuepoint', start: 30, end: 100, percent: false, startCueFn: 'beginCuePoint3', endCueFn: 'endCuePoint3', unique: false, disabled: false, video: 'all'},
{name:'FinalCuepoint', start: 20.1, end: 30, percent: false, startCueFn: 'beginCuePoint4', endCueFn: 'endCuePoint4', unique: false, disabled: false, video: 'all'}
];
var singleevent = [
{name: "BEGIN", start: 1, percent: true, fn: 'PixelTracker1', unique: false, disabled: false, video: 'all'},
{name: "25_COMPLETE", start: 25, percent: true, fn: 'PixelTracker2', unique: false, disabled: false, video: 'all'},
{name: "50_COMPLETE", start: 50, percent: true, fn: 'PixelTracker3', unique: false, disabled: false, video: 'all'},
{name: "75_COMPLETE", start: 75, percent: true, fn: 'PixelTracker4', unique: false, disabled: false, video: 'all'},
{name: "100_COMPLETE", start: 100, percent: true, fn: 'PixelTracker5', unique: false, disabled: false, video: 'all'}
];

/* END cuepoints feature inclusion portion */


 

 

Cue Point Object definition details

Attribute

Value

Description

name

string

cuepoint name

start

integer

integer which represents when to start cuepoint animation

end

integer

integer which represents when to end cuepoint animation

percent

boolean

true/false: whether to interpret start and end value as percentage of video duration

startCueFn

string

this is the exact function name that will be called at the start animation time.

endCueFn

string

this is the exact function name that will be called at the end animation time.

unique

boolean

true/false: if set to true this cuepoint will only happen once per ad load.

disabled

boolean

true/false: whether the cuepoint is enabled or not.

video

string

the exact video file name without filetype extension or "all" to apply to all videos.

 

Attribute

Value

Description

name

string

cuepoint name

start

integer

integer which represents when to start cuepoint animation

percent

boolean

true/false: whether to interpret start and end value as percentage of video duration

fn

string

this is the exact function name that will be called at the start animation time.

unique

boolean

true/false: if set to true this cuepoint will only happen once per ad load.

disabled

boolean

true/false: whether the cuepoint is enabled or not.

video

string

the exact video file name without filetype extension or "all" to apply to all videos.

 

 

Sizmek Cue Points Feature Public Methods

Name

Description

checkCuepointElem();

method attached to video "timeupdate" event, can also be called manually

initCuePoints()
registers a cuepoint object after adkit completely loads
addPixelTracker()
registers a single event cuepoints on load.
resetCuePoints()
broadcasts an event to clear all cuepoints.
disableCuepointByName()
programmatically disable a cuepoint.
Sizmek Cue Points Feature.disableCuepointByName("cuepoint_name");
showCurrentQueue()
returns all cuepoints that are in the current Cuepoint object.
makeNewCuePoint()
register all animation cuepoints on load.
checkCuepointByName()
programmatically create a new cuepoint.
Sizmek Cue Points Feature.makeNewCuePoint("cuepoint_name");
checkCuepointByTime()

search registered Cuepoints within the two times provided.
Sizmek Cue Points Feature.checkCuepointByTime(rangeStart, rangeEnd);
Sizmek Cue Points Feature.checkCuepointByTime(3,10);

 

checkCuepointById()
search registered Cuepoints for matching Id value;

 

 

Cue Points Generator Tool

Generate the Cue Points code using this tool while viewing your video locally, to allow precise timing and hassle free creation at the click of a button. Video Cue Points Generator

tool_1a.png

This online tool allows you to preview a video from your local machine and generate the code needed to create Cue Points without the need to hand write the object code.

tool_2a.png
Video preview window with speed and seek controls

tool_3a.png
Create new Cue Points or delete previously created Cue Points with these buttons.

Feature Name

Description and Usage

browse

This will replace the default video with most .mp4 from your local machine

video speed options

if you need to slow down the video to synchronize your cuepoint with precision, you can view the video at speeds from .25, .50, .75 or normal.

seek to and play

This allows you to input a time and the player will jump to that specific time in your video and play the video.

seek to and stop

This allows you to input a time and the player will jump to that specific time in your video and the video hold.

build animation

This launches the Animation Cue Point creation screen.

build single event

This launches the Single Event Creation screen.

delete cuepoint

This launches the Cue Point deletion screen.

 

 

Requirements Checklist

  1. Supported in Rich Media Formats only. No Standard Banners.
  2. VPAID is supported with special considerations.

 

Known Issues

  • In certain VPAID Publisher environments, custom user interactions may not possible, due to VPAID encapsulation and publisher controlled restrictions. In these cases, animations will will still function but interaction may be limited or unavailable.

 

Change Log

November 16th, 2018
 
  • Initial Release

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments