Track video in workspaces – Amazon Ads Help Center

Overview

The purpose of this guide is to document the use of the Amazon Ad Server (AAS) Video Module to track video interactions for workspace video assets. Throughout this guide and subsequent pages, we hope to provide a comprehensive overview of the native HTML video player, its attributes, methods, events, and common uses. Additionally, this guide should provide a complete understanding of how to assign your video asset to the AAS Video Module, and by doing so, allow developers to track video interactions, both manually and automatically, for all their video assets.

With the use of the HTML video tag, developers can easily add video content to their creative. By combining the video tag with the AAS Video Module, advertisers can track user interactions with their video content and use that data to improve future campaigns. Below we will outline the steps to adding video content to your Workspace and how to assign that video to the AAS Video Module for tracking.

Click on the links provided for additional documentation

How To Track Single Video

How To Track Multiple Videos

How to Manually Track a Single Video

How to Manually Track Multiple Videos

Adkit Video Module Events

Demos

The following table provides a link to the demo for the Track Video in workspaces feature.

Demo	Preview Demo

How to build

The first step is to add the EB Video Module include. This instructs AAS Adkit to enable video tracking in your workspace. Add the EB Video Module include to the head of your workspace index.html file. It is important to add this before adding the adkit include.
```
<script type="text/javascript">EBModulesToLoad = ['Video'];</script>
```
Next, add a video tag with video source to the body of your index.html file. Add any attributes you may need such as playsinline or autoplay. In the example below, the video tag will include the native video control bar and will autoplay on load with the audio muted. Additionally, the video will play inline (within the page content), preventing iOS devices from automatically entering fullscreen mode when playback begins.
```
<video id="video" controls autoplay muted playsinline>
	<source src="videos\sizmek.mp4" type="video/mp4" />
	Your browser does not support the video tag.
</video>
```
If needed, add additional sources tags for each new video format you want to provide. This allows the video tag to try another format if the first format provided is not supported. In the example below, the browser will try to autoplay the mp4 file first. If the browser does not support mp4 files, it will next try to autoplay the ogg file.
```
<video id="video" controls autoplay>
	<source src="videos\sizmek.mp4" type="video/mp4" />
	<source src="videos\sizmek.ogg" type="video/ogg" />
	Your browser does not support the video tag.
</video>
```
Once adkit has loaded, instantiate the EB Video Module and pass a video element reference to the video module. Your video is now ready to be tracked. Any time the video is played, paused, muted or put into fullscreen mode, these events, and more, will be tracked.
```
<script type="text/javascript">
    // Establish reference to video tag
    var theVideo = document.getElementById("video")
    // Create video module instance to track video events
    var trackedVideo = new EBG.VideoModule(theVideo);
</script>  
```

Advanced

Full code snippet

Please see the full script, below, needed to implement the video player into your ad.

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.


<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <title>Sizmek Video Player Ad Feature</title>
        <script type="text/javascript">EBModulesToLoad = ['Video'];</script>
        <script type="text/javascript" src="https://secure-ds.serving-sys.com/BurstingScript/adKit/adkit.js"></script>
    </head>
    <body>

        <!-- Begin Sizmek Video Player Ad Feature -->

        <video id="video" controls muted>
	    <source src="videos/sizmek.mp4" type="video/mp4" />
	    Your browser does not support the video tag.
	</video>

        <script type="text/javascript">
            adkit.onReady( function() {
	        // Establish reference to video tag
		var theVideo = document.getElementById('video');
		// Create video module instance to track video events
		var trackedVideo = new EBG.VideoModule(theVideo);

		// Play the video and track the play action as user-initiated.
                // Pass true for user-initiated and false for auto
		trackedVideo.playVideo(true);

		// Add listener for volume change event
		theVideo.addEventListener("volumechange", handleVolumeChange, false);

		function handleVolumeChange(e) {
		    // do something on volume change
		}
	    });
        </script>

        <!-- End Sizmek Video Player Ad Feature -->

    </body>
</html>

Common configurations

Below are two common use cases for video setup in workspace creatives.

Note: The code snippets 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.

Autoplay without the use of the autoplay attribute

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <title>Sizmek Video Player Ad Feature</title>
        <script type="text/javascript">EBModulesToLoad = ['Video'];</script>
        <script type="text/javascript" src="https://secure-ds.serving-sys.com/BurstingScript/adKit/adkit.js"></script>
    </head>
    <body>

        <!-- Begin Sizmek Video Player Ad Feature -->

        <video id="video" controls muted>
	    <source src="videos\sizmek.mp4" type="video/mp4" />
	    Your browser does not support the video tag.
	</video>

        <script type="text/javascript">
            adkit.onReady( function() {
	        // Establish reference to video tag
		var theVideo = document.getElementById('video');
		// Create video module instance to track video events
		var trackedVideo = new EBG.VideoModule(theVideo);

		// Play the video and track the play action as user-initiated.
                // Pass true for user-initiated and false for auto
		trackedVideo.playVideo(false);
	    });
        </script>

        <!-- End Sizmek Video Player Ad Feature -->

    </body>
</html>

Click to play with audio on mobile devices.

To limit the bandwidth use on mobile devices mobile browsers require user intent before playing audio. For this reason, mobiles devices will not allow autoplay with audio. In cases where audio is preferred when viewing video on mobile devices, it is common practice to trigger the play method on a click, which signifies the users intent. The example below provides a simple example of this use case.

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <title>Sizmek Video Player Ad Feature</title>
        <script type="text/javascript">EBModulesToLoad = ['Video'];</script>
        <script type="text/javascript" src="https://secure-ds.serving-sys.com/BurstingScript/adKit/adkit.js"></script>
    </head>
    <body>

        <!-- Begin Sizmek Video Player Ad Feature -->
        <!-- The autoplay attribute will be ignored by mobile devices -->
        <video id="video" controls autoplay muted>
	    <source src="videos\sizmek.mp4" type="video/mp4" />
	    Your browser does not support the video tag.
	</video>

        <button id="button1">Click to watch video</button>

        <script type="text/javascript">
            adkit.onReady( function() {
	        // Establish reference to video tag
		var theVideo = document.getElementById('video');
		// Create video module instance to track video events
		var trackedVideo = new EBG.VideoModule(theVideo);

		// Save reference to button
                var button = document.getElementById("button1");

                // Add listener to button and play video on click
                button.addEventListener("click", function(){
		    trackedVideo.playVideo(false);
                });
	    });
        </script>

        <!-- End Sizmek Video Player Ad Feature -->

    </body>
</html>

How to view video events in preview

AAS provides users with the ability to view video events with the interactions monitor. Follow the steps below.

Edit an existing ad under Manage > Ads (or select an ad from the list and click the preview button)
Click Preview (log in necessary for AAS)
Once the preview has loaded, view the Interactions Monitor in the right-hand panel.
- All video events will be recorded in the Interactions Monitor as that event occurs in real-time.

How to generate analytics report for video metrics

AAS provides users the ability to generate analytics reports for a wide variety of metrics, including a full spectrum of video events such as quartiles, pause, play, mute and more.

Generating analytics reports on AAS

To generate an analytics report on AAS, see Generate an Aggregated Report. For more information about video metrics, see Video Metrics.

Video tag optional attributes

For a full list of Native HTML Video Player methods, go to www.w3schools.com

Attribute	Value	Description
autoplay	autoplay	Specifies that the video will start playing as soon as it is ready
controls	controls	Specifies that video controls should be displayed (such as a play/pause button etc).
muted	muted	Specifies that the audio output of the video should be muted.
loop	loop	Specifies that the video will start over again, every time it is finished.
playsinline	playsinline	Prevents iOS devices from automatically enter fullscreen mode when playback begins. Supported in iOS 10+. Use webkit-playsinline for iOS 4-9.
poster	URL	Specifies an image to be shown while the video is downloading, or until the user hits the play button.
preload	auto metadata none	Specifies if and how the author thinks the video should be loaded when the page loads.

Video module player method

Function	Parameters	Description
playVideo	User (optional): Boolean true or false	Play Video. Optional to send true or false to track whether Play was user initiated ex: // tracks user initiated play trackedVideo.playVideo(true); // tracks auto play trackedVideo.playVideo(false); Please note: if you intend to report that the play is user-initiated, you must also fire the "USER_INITIATED_VIDEO" event (manual tracking only)
replayVideo	User (optional): Boolean true or false	Replay Video. Optional to send true or false to track whether Replay was user initiated ex: // tracks user initiated replay trackedVideo.replayVideo(true); // tracks auto replay trackedVideo.replayVideo(false);
setVideoSrc	asset (file name or url) or asset id number	Update the video asset that is tracked by the video module. // update video player source theVideo.src = "videos/sizmek.mp4"; // use API to update video source in video module trackedVideo.setVideoSrc(theVideo.src);
	default value = true

For a full list of the Video Module events, see Video Module.

Native video player methods

For a full list of Native HTML Video Player methods, go to www.w3schools.com

Name

Description

load

Re-loads the audio/video element

ex:

// Change the video source and re-load the video:

theVideo.src = "movie.mp4";
myVideo.load();

pause

Pauses the currently playing video

ex: theVideo.pause();

Native video player properties

For a full list of Native HTML Video Player properties, go to www.w3schools.com

Name	Description
muted	Sets or returns whether the audio/video is muted or not ex: // Mutes the video theVideo.muted = true; // UnMutes the video theVideo.muted = false;
volume	Sets or returns the volume of the video ex: // sets the video element 'theVideo' to 60% volume theVideo.volume = .6;
currentTime	Sets or returns the current position (in seconds) of the video playback. When setting this property, the playback will jump to the specified position. ex: // Updates the time position to 3 seconds theVideo.currentTime = 3;

Native video player events

For a full list of Native HTML Video Player events, go to www.w3schools.com

Event name	Description and usage
play	Fired when the video has been started or is no longer paused. theVideo.onplay=function(){myScript}; theVideo.addEventListener("play", myScript);
pause	Fired when the video is paused either by the user or programmatically. theVideo.onpause=function(){myScript}; theVideo.addEventListener("pause", myScript);
ended	Fired when the video has reached the end. theVideo.onended=function(){myScript}; theVideo.addEventListener("ended", myScript);
error	Fired when an error occurred during the loading of a video. theVideo.onerror=function(){myScript}; theVideo.addEventListener("error", myScript);
seeked	Fired when the user is finished moving/skipping to a new position in the video theVideo.onseeked=function(){myScript}; theVideo.addEventListener("seeked", myScript);
timeUpdate	Fired when the playing position of a video has changed. theVideo.ontimeupdate=function(){myScript}; theVideo.addEventListener("timeupdate", myScript);
volumeChange	Fired each time the volume of a video has been changed. theVideo.onvolumechange=function(){myScript}; theVideo.addEventListener("volumechange", myScript);

Support matrix

Supported platforms		Supported properties
Windows	Internet Explorer 10+, Microsoft Edge, Firefox, Chrome	Polite Loading	Yes
Mac	Safari, Firefox, Chrome	Safeframe Support	Yes
iPhone	iOS 9.0 and later	MRAID (in App Support)	Yes
iPad	iOS 9.0 and later	Adkit Ready	Yes
Android Phone	Android 6 and later	Secure Serving	Yes
Android Tablet	Android 6 and later	AAS Supported	Yes

Ad setup in Amazon Ad Server

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.

Requirements checklist

Requires Adkit, will not work with EBLoader only. For more information, see Methods.
Requires the EB Video Module include before the Adkit include.
Supported in rich media formats only. No standard banners.

Known issues

Due to the limited event data associated with native controls for HTML video, it is difficult to determine the origin of certain events as they pertain to video tracking. For instance, while we can track whether a custom play button built in JavaScript was clicked by the user, there is no reliable way to determine if the user clicked on the native play button, making it difficult to ascertain if the event was user-initiated. Likewise, it is difficult to determine if the "seeked" event is being fired because the user dragged the playhead, or if the user clicked the replay button. Similarly, if the video tag includes the "loop" attribute, the "seeked" event is fired automatically as the playhead updates. Please keep this in mind when using manual tracking.
When using the playVideo method with the EB.videoModule, please note, that the "IsUserInitiated" integer for the "ebVideoStarted" interaction will report as a 0. For manual tracking, the USER_INITIATED_VIDEO event must be fired for metrics to properly record user-initiated video. Additionally, once the user-initiated value is set to true, it will always be true for that impression.