Create an in-stream video interactive in a code editor – Amazon Ads Help Center

Note

Note: To learn more about this format, preview a demo, or to see build guides for other authoring tools, see About in-stream video interactive.

Creating an ad using an Amazon Ad Server template

When creating a in-stream video interactive in a code editor, it is recommended that you start with our official template bundle.

Files within the bundle:

Amz_InStreamVideoInteractive_1_0_1_DCO_AdditionalAssets

Amz_InStreamVideoInteractive_1_0_1.zip

Amz_InStreamVideoInteractive_1_0_1_DCO.zip

README.txt

Included files

The following table describes the list of files that are included in the downloadable template.

File Name	Description	Required
`index.html`	The entry point for the template. Provides the basic HTML structure for reference in `script.js` and `style.css`.	Required
`js/script.js`	Contains the logic for manipulating the HTML elements at runtime and interacting with the VPAID API.	Required
`css/styles.css`	Provides style information to the structure of `index.html`.	Optional (if code is included in the HTML file)
`images/logo.png`	An example image displayed in the template. When replacing or removing this file, make sure to address its references in `index.html` and `styles.css`.	Optional
`videos/preview.mp4`	A video that can be used while testing locally without depending on AAS. When replacing or removing this file, make sure to address its references in `script.js`.	Optional

Setting up Your Ad in Amazon Ad Server

After you finish creating your ad, proceed to setting up your ad in AAS. For more information, see Set up an in-stream video interactive.

Additional resources

Shared libraries

If you are developing ads with third-party libraries, we recommend that you call these libraries from a CDN (Content Delivery Network) when possible. This will help improve loading time and caching.

Advanced configuration

The following tables provide additional variables, functions, and methods that are available for this format. You can use these additional items to fully customize your ad.

Methods and properties

adEventListner: Allows for VPAID to notify the ad about internal events. VPAID dispatches events related to the primary video state only.

adkit.vpaid.addEventListener(eventType:String, callback:Function)

Name	Description
`eventType`	Type of event as a string.
`callback`	Refers to a function that operates as an event handler.

removeEventListener: This function removes an event subscription previously added using the addEventListener function.

adkit.vpaid.removeEventListener(eventType:String, callback:Function)

Name	Description
`eventType`	Type of event as a string.
`callback`	Refers to a function that operates as an event handler.

pause(): Pauses primary video playback.

Calling pause() on a adkit.vpaid object will not have an effect other than pausing the primary video. It will not pause any other HTML sound or animation in the ad outside of the primary video file.

adkit.vpaid.onVideoEvents(adkit.vpaid.VIDEO_EVENTS.PAUSE, function(event){
    adkit.vpaid.pause();
});

play(): Resumes video playback or restarts video if video playback is finished.

Calling play() on a adkit.vpaid object will not have an effect other than playing or resuming the primary video. It will not restart any other HTML sound or animation in the ad outside of the primary video file.

adkit.vpaid.onVideoEvents(adkit.vpaid.VIDEO_EVENTS.PLAY, function(event){
     adkit.vpaid.play();
});

skipAd() : Calling skipAd() on adkit.vpaid object will stop the primary video and close the ad.

skip_btn.addEventListener("click", onClickSkip);

function onClickSkip(event) {
    adkit.vpaid.skipAd();
}

onSkipEnabled() : onSkipEnabled method is called when ‘Skip ad unit’ setting in the Ad Setup on AAS is activated and the playback position is reached to the seconds that defines in the setup. If the seconds set ‘0’, the ad will execute onSkipEnabled when it starts to play the primary video.

skip_btn.style.visibility = "hidden";
adkit.vpaid.onSkipEnabled(function() {
    skip_btn.style.visibility = "visible";
});

muted: Indicates whether the sound is muted.

True: Primary video will be muted (volume set to zero).

False: Primary video will be unmuted (volume will be set to user-preferred volume).

Changing the adkit.vpaid.muted value affects the primary video only and will not propagate to other objects that handle sound, including the secondary video.

toggle_audio_btn.addEventListener("click", toggleAudio);

function toggleAudio(){    adkit.vpaid.muted = !adkit.vpaid.muted;

}

adkit.vpaid.onVideoEvents(adkit.vpaid.VIDEO_EVENTS.VOLUME_CHANGE, function(event){     toggle_audio_btn.innerHTML = adkit.vpaid.muted ? "unmute" : "mute";
});

Note

Note: A user can take advantage of config.js to configure or add an attribute (width, height, left or top). This moves the bounding box for the video that displays behind/beneath the ad and doesn't alter the full ad/player size nor will it crop the video. This should be used carefully and only when needed, as not to run the risk of providing any incorrect values.

Example:

define({
    "vpaid": {
        "primaryVideo": {
            "sources": [1],
            "designModeVideoUrl": "videos/video.mp4",
            "width": 1280,
            "height": 720, 
            "top": 0,
            "left": 0
        }
    }
});

Setting the primary video with a dynamic value

Note

Note: If you need to add Dynamic Creative Optimization (DCO) elements to your creative, see Add Dynamic Elements to Your HTML Ads Using a Code Editor.

VPAID API contains configure method that sets initial ad configuration values. Via this configuration, you can get the primary video from DCO elements. This function should be called once; subsequent calls are ignored.

The following table describes the properties of the object for the configuration values.

Name	Description
`primaryVideoId`	ID of additional asset for the primary video. The value is either integer or string. This property and valid value are mandatory. Failure providing of this property will result in unusable ad. Value of `primaryVideoId` can be passed only once. Subsequent calls are ignored.
`designModeVideoUrl`	URL to video displayed in `Design mode`. This parameter is optional. Value can be provided as a relative URL to local video asset or as a fully qualified URL. If a value is not provided, the video will not be rendered in `Design mode`. The presence of value does not affect runtime video display. There is no need to remove the value when published ads.
`closeButton`	Reference to HTML element that acts as ad close button. If a value is omitted or the value is null, VPAID will draw default close button.
`skipButton`	Reference to HTML element that acts as ad skip button. This parameter is optional. There is no default skip button in the current VPAID iteration.

Events

A VPAID instance dispatches all events that the <video/> tag handles at the time that the tag dispatches them. Here is a list of video events that our VPAID API supports.

Event Name	Description
`abort`	Fires when the loading of the video is aborted.
`canplay`	Fires when the ad can start playing the video.
`canplaythrough`	Fires when the ad can play through the video without stopping for buffering.
`durationchange`	Fires when the duration of the video is changed.
`error`	Fires when an error occurred during the loading of the video.
`loadeddata`	Fires when the ad has loaded the current frame of the video.
`loadedmetadata`	Fires when the ad has loaded meta data for the video.
`loadstart`	Fires when the ad starts looking for the video.
`pause`	Fires when the video has been paused.
`play`	Fires when the video has been started or is no longer paused.
`playing`	Fires when the video is playing after having been paused or stopped for buffering.
`seeked`	Fires when the user is finished moving/skipping to a new position in the video.
`suspend`	Fires when the ad is intentionally not getting media data.
`timeupdate`	Fires when the current playback position has changed.
`volumechange`	Fires when the volume has been changed.
`waiting`	Fires when the video stops because it needs to buffer the next frame.

Script.js

The script.js file in the template is designed as self-sufficient and the only JavaScript code that manages all template functionality. Ad developers are encouraged to preserve this structure, if possible, to avoid possible inadvertent changes that may negatively affect core JavaScript functionality. Code in the file is thoroughly documented. Comments and the build guide mutually complement each other.

Demo

Click here to preview a demo of in-stream video interactive format.