Version 5.0
AdvertServe User Manual :: v5.0

HTML5

Introduction

The adoption of HTML5 in advertising has really opened up a world of endless possibilities. However, to really tap into the full capabilities of HTML5 you need good tools that abstract away the complexities of the underlying technologies. Many designers prefer to use tools such as Adobe Edge, Google Web Designer or Tumult Hype to produce HTML5 creatives. More experienced designers might even prefer to hand-code their creatives with HTML5 animation frameworks such as GreenSock or TweenJS and those are also great options.

Regardless of the path you take to produce your HTML5 creatives you are going to end up with a collection of files when you are done. Simple creatives might only have a couple of files, but it is not uncommon for interactive creatives to have dozens of files! This is why we have designed the ad server to accept a ZIP file when uploading HTML5 banners. You just package all of the HTML5 asset files into a single ZIP file and then you only have one file to upload.

The ZIP file cannot be larger than 2.5 MB and it must contain exactly one .html file. It may also contain any number of the following types of files, which can optionally be organized into sub-folders: .css, .eot, .gif, .htc, .ics, .jpg, .js, .json, .otf, .svg, .png, .ttf, .woff and .woff2

What about HTML5 video though? We do support creatives with HTML5 video and we can track their playback as well (see below). However, the ad server does not support streaming video content. For this reason, we recommend that you host video files on a CDN that supports streaming video.

clickTag

Anyone that has worked with Flash banners in the past will remember clickTag's well and honestly it might not be a good memory.

Working with a clickTag in HTML5 is thankfully a much more pleasurable experience! Not familiar with what a clickTag is? Essentially it is a global variable that the ad server inserts a click tracking redirect into. Rather than hard coding a link to your landing page into a creative you have a function that reads and opens that click tracking redirect, which in turn redirects to your landing page after doing its tracking.

That probably sounds complicated right? It is actually as simple as wrapping the following code around your creative:


<div id="MyCreative" onclick="window.open(window.clickTag)" style="cursor: pointer">
  ... more code here ...
</div>

In fact, you actually do not even need to implement a clickTag in most cases. The ad server will automatically insert a clickable layer with a clickTag on top of your banner if it doesn't detect one. However, that will unfortunately break interactive HTML5 banners that require user input. Manually implementing a clickTag for such banners is required.

If you do find yourself in a situation where you need to manually implement a clickTag in your HTML5 creative we do have detailed step-by-step instructions here: http://www.html5clicktag.org/

What if you need multiple clickTag's though? Consider using exit events (see below) for each of your links instead. You can only have one clickTag per creative, but you can have up to 25 exit events and they may each have their own unique redirect.

JavaScript API

One of the most powerful parts of HTML5 is JavaScript and the ad server takes full advantage of this by offering an API that allows you to track custom counter events, multiple exit events and HTML5 video playback. In fact, the API also enables expandable creatives. This includes support for pushdowns, lightboxes and full page overlays.

Loading the API

To load the API we recommend that you add a <SCRIPT> tag to the <HEAD> section of the .html file for your creative:


<script type="text/javascript" src="//youraccount.advertserve.com/js/events1.js"></script>

This will load and initialize the API. Notice that we also use a protocol relative URL, so it will work on both http and https.

Using Counter Events

Tracking of custom counter events can either be done by registering an event handler or by manually triggering the event.

FunctionDescription
AdvertEvents.registerCounterAction(id, event); Binds an event handler to a DOM element with the specified ID, which will increment the counter each time the event is triggered. The ID is also used as the event name in the reports. Thus you should take care to name your DOM elements clearly and use camel case to delimit multiple words (i.e. PurchaseButton).
AdvertEvents.counter(id); Manually triggers a counter event, which is useful when a custom event handler is required to implement additional functionality.
AdvertEvents.registerUniqueCounterAction(id, event); Binds an event handler to a DOM element with the specified ID, which will increment the counter the first time the event is triggered. The ID is also used as the event name in the reports. Thus you should take care to name your DOM elements clearly and use camel case to delimit multiple words (i.e. PurchaseButton).
AdvertEvents.unique(id); Manually triggers a unique counter event, which is useful when a custom event handler is required to implement additional functionality.
AdvertEvents.tally(id); Equivalent to the AdvertEvents.counter(id) function with the exception that the triggering event is not considered an engagement, which can be useful in situations where you want to count multiple events without counting multiple engagements.

Consider the following example with two buttons that each count when they are clicked on:


<div id="FirstButton" style="cursor: pointer">First Button</div>

<div id="SecondButton" style="cursor: pointer">Second Button</div>

<script type="text/javascript">
AdvertEvents.registerCounterAction('FirstButton', 'click');

document.getElementById('SecondButton').onclick = function(e) {
  AdvertEvents.counter('SecondButton');
};
</script>

Using the first method is simpler because you don't have to code your own event handler function. You can also use other hTML5 events such as mouseover to track roll overs. However, if you need to implement additional coding in response to the event the second method is preferable to minimize the number of event handlers.

Using Exit Events

Tracking of custom exit events can either be done by registering an event handler or by manually triggering the event. You must also define each Event ID and its associated Redirect URL when uploading the HTML5 banner to the ad server. If you fire an exit even that has no matching Event ID defined it will fall back on using the default Redirect URL for the media.

FunctionDescription
AdvertEvents.registerExitButton(id); Binds a click event handler to a DOM element with the specified ID, which will increment the counter each time the event is triggered. The ID is also used as the event name in the reports. There should also be a corresponding exit event defined in the media with the same ID, which allows the ad server to look up the redirect associated with it.
AdvertEvents.triggerExitEvent(e, id); Manually triggers an exit event, which is useful when a custom event handler is required to implement additional functionality. The first parameter is the DOM event that was received by your custom event handler. However, if no such event exists or it cannot be referenced you can use null instead.

Consider the following example with two buttons that each count when they are clicked on and perform an exit redirect:


<div id="FirstButton" style="cursor: pointer">First Button</div>

<div id="SecondButton" style="cursor: pointer">Second Button</div>

<script type="text/javascript">
AdvertEvents.registerExitButton('FirstButton');

document.getElementById('SecondButton').onclick = function(e) {
  AdvertEvents.triggerExitEvent(e, 'SecondButton');
};
</script>

Using the first method is simpler because you don't have to code your own event handler function, but if you need to implement additional coding in response to the event the second method is preferable to minimize the number of event handlers.

Using Video Events

Tracking of HTML5 video events can be done by simply registering the video tag with the API, which will set up all of the necessary event handlers to track start, first quartile, midpoint, third quartile, complete, pause, resume, replay, mute, unumute and fullscreen events.

FunctionDescription
AdvertEvents.registerVideoTag(id, options); Binds a collection of event handlers to a DOM element with the specified ID, which must be a HTML5 video tag. The ID is also used as the event name in the reports. Thus you should take care to name your DOM elements clearly and use camel case to delimit multiple words (i.e. SampleVideo). Optionally you can also enable video controls, which adds a play/pause and unmute button overlays when appropriate.
AdvertEvents.playVideo(id); Attempts to auto-play a DOM video element with the specified ID, which is tried first with sound enabled and if it is blocked then it is tried again with sound disabled and an unmute button is rendered over top of the video for the user to enable sound.
AdvertEvents.playVideoMutedIfNotPlaying(id); Checks if a DOM video element with the specified ID is playing, but if it is not then it will try to play it with sound disabled as well as display an unmute button over top of the video for the user to enable sound.
AdvertEvents.registerVideoPixel(id, event, url); Allows you to asynchronously execute a third-party image pixel when any of the following video events occur:
  • Start
  • FirstQuartile
  • Midpoint
  • ThirdQuartile
  • Complete
  • Pause
  • Resume
  • Replay
  • Mute
  • Unmute
  • Fullscreen

Multiple Video Tags

Consider the following example with two HTML5 video tags that will each be independently tracked:


<video id="FirstVideo" preload="none" width="100%" height="100%" poster="//cdn.example.com/video1.png" webkit-playsinline="" playsinline="">
  <source src="//cdn.example.com/video1.mp4" type="video/mp4" />
</video>

<video id="SecondVideo" preload="none" width="100%" height="100%" poster="//cdn.example.com/video2.png" webkit-playsinline="" playsinline="">
  <source src="//cdn.example.com/video2.mp4" type="video/mp4" />
</video>

<script type="text/javascript">
AdvertEvents.registerVideoTag('FirstVideo');
AdvertEvents.registerVideoTag('SecondVideo');
</script>

There is no limit on the number of video tags that you can register. It is important to note that some devices such as mobile phones and older tablets use a native app that plays video outside of the browser app. This prevents tracking of events that occur while inside the native player app, which typically means that only the start and complete events can be tracked.

Video Controls

How about video controls? You can use the native HTML5 player controls, design your own custom button overlays or save yourself a lot of work and simply use the built-in controls:


<div id="FirstVideoContainer" style="width: 640px; height: 360px">
  <video id="FirstVideo" preload="none" width="100%" height="100%" poster="//cdn.example.com/video1.png" webkit-playsinline="" playsinline="">
    <source src="//cdn.example.com/video1.mp4" type="video/mp4" />
  </video>
</div>

<script type="text/javascript">
AdvertEvents.registerVideoTag('FirstVideo', { 'controls': true });
AdvertEvents.registerExitButton('FirstVideo');
</script>

Take note that the video needs to be wrapped in a parent div in order for the control button overlays to have a place to be inserted. You might also notice we registered an exit button on the video? This makes the video itself a clickable hotspot and it will redirect to the landing page when clicked (except of course if you click on one of the controls!). It's also worth mentioning that the buttons will adapt and work properly if you set the autoplay and/or muted attributes on the video tag. If they are omitted the video will be click-to-play with sound enabled by default.

Tracking Pixels

You may also have cases where an advertiser wants to use pixels to track video events in their ad server, which could be accomplished as follows:


<script type="text/javascript">
AdvertEvents.registerVideoPixel('FirstVideo', 'Start', 'https://example.com/path/to/pixel.gif');
AdvertEvents.registerVideoPixel('FirstVideo', 'FirstQuartile', 'https://example.com/path/to/pixel.gif');
AdvertEvents.registerVideoPixel('FirstVideo', 'Midpoint', 'https://example.com/path/to/pixel.gif');
AdvertEvents.registerVideoPixel('FirstVideo', 'ThirdQuartile', 'https://example.com/path/to/pixel.gif');
AdvertEvents.registerVideoPixel('FirstVideo', 'Complete', 'https://example.com/path/to/pixel.gif');
</script>

The above code would trigger the advertisers pixels to be executed when the video starts, reaches the first quartile, midpoint, third quartile and upon completion.

Ignoring Unintentional Events

Sometimes you might run into a situation where your code will unintentionally fire a tracking event. For example, consider that you might have a creative with a HTML5 video that plays automatically with the sound muted. That is actually pretty common and usually you will have an unmute button for the viewer to enable sound. Maybe you also want to rewind the video back to the beginning as well so it plays from the start with sound enabled. This presents a problem because by performing these actions the browser will fire pause, unmute and replay events in response to them. Fortunately the API provides a way for you to temporarily ignore events while performing such actions.

FunctionDescription
AdvertEvents.ignore(callback); Disables tracking of counter, exit and video events while executing the provided callback function.

How this works is you put your logic to pause, unmute, rewind and replay the video into a callback function, which you pass to the API for it to execute while it ignores any events that get triggered unintentionally.


var btnSound = document.getElementById('btnSound');
var video = document.getElementById('myVideo');

function btnSoundClick (e) {
  AdvertEvents.counter('Sound Clicked');
  e.preventDefault();
  e.stopPropagation();
  AdvertEvents.ignore(function() {
    video.pause();
    video.muted = false;
    video.currentTime = 0;
    video.play();
  });
  btnSound.style.display = 'none';
}

As you can see there we first count that the viewer has clicked the button to enable sound. Then we stop the event from propagating to the video tag below that button. Next we then use the API ignore function to execute the logic to pause, unmute, rewind and replay the video so those events are not counted. Then finally we hide the button to enable sound since it is no longer needed.

Improving QA Testing

By default the media preview tool and test pages will show events as their event listeners are registered. However, it will not immediately show events that are manually triggered. This can be problematic for QA testing because it doesn't allow you to see untriggered events.

This problem can be solved by calling the AdvertEvents.loadManifest([...]) function when the creative is initialized, which allows you to pass a list of all events to the preview tool.


AdvertEvents.loadManifest([
  { type: 'counter', name: 'Creative Expanded', description: 'Counted when the creative is expanded' },
  { type: 'counter', name: 'Creative Collapsed', description: 'Counted when the creative is collapsed' },
  { type: 'video', name: 'mainVideo', description: 'This video appears when the creative is expanded' },
  { type: 'exit', name: 'Acme Logo' },
  { type: 'exit', name: 'Shop Now Button' },
  { type: 'exit', name: 'Background', description: 'Captures all other clicks on the expanded creative' }
]);

As you can see this list not only includes all of the tracking points, but it also documents them with a description. The description is optional though. In many cases the name of the event is self-explanatory and a description would most likely be redundant.

Expandable Functions

The API provides functions to enable expandable creatives, which includes pushdowns, lightboxes and full page overlays. These functions are necessary because the ad server actually loads HTML5 creatives into a friendly IFRAME tag. You would find that if you tried to expand your creative without calling these functions it would simply be clipped off since IFRAME tags by themselves are not resizeable.

FunctionDescription
AdvertEvents.autoExpand(width, height) This function can be called to auto-expand a creative without actually counting it as expanded and also to avoid immediately counting the impression as interactive. You might like to do this if the creative automatically times out and closes. Then if the user actually manually expands it again is when the expanded and interactive impression would be counted.
AdvertEvents.expand(width, height) This function can be called to expand the creative, which is usually in response to a user clicking an expand button or rolling their mouse over the creative. The impression is automatically counted as interactive when this event is fired. In addition that, a built-in "Creative Expanded" event is counted so it is not necessary to set up a separate tracking event for that.
AdvertEvents.isViewportResized(width, height) Returns true if the viewport is equal to or larger than the size specified by the width and height parameters, which is useful to provide a fallback creative in the event that an IFRAME breaker is not installed or failed to work properly.
AdvertEvents.collapse(width, height) This function can be called to collapse the creative, which is usually in response to a user clicking a close button or moving their mouse away from the creative. In addition that, a built-in "Creative Collapsed" event is counted so it is not necessary to set up a separate tracking event for that.
AdvertEvents.openLightbox(width, height, bgColor) This function works similarly to the expand() function except that it loads the expanded creative into a lightbox that stays centered on the screen. You may also specify a custom background color. It defaults to black and uses a CSS3 transition to fade it from 0% to 80% opacity.
AdvertEvents.closeLightbox(width, height) This function works similarly to the collapse() function except that it tears down the lightbox and moves the collapsed creative back into its original page position.
AdvertEvents.enterFullscreen(bgColor) This function internally calls the openLightbox() function with the width and height both set to 100% so the creative fills the entire viewport of the browser tab or window.
AdvertEvents.exitFullscreen(width, height) This function internally calls the closeLightbox() function.
AdvertEvents.unload() This function completely removes the HTML5 creative and any IFRAME containers from the DOM, which can be useful if you wish for a lightbox or fullscreen creative to disappear after being closed.

For an example, consider that we might have a 970x90 banner that we want to expand to 970x250 on mouse over and collapse when the close button is clicked.


var container = document.getElementById('container');
var closeButton = document.getElementById('closeButton');

container.addEventListener('mouseover', function() {
  AdvertEvents.expand(970, 250);
});

closeButton.addEventListener('click', function() {
  AdvertEvents.collapse(970, 90);
});

Of course, you will probably have additional logic and animation that needs to be performed. This example only demonstrates how to resize the "stage" for your creative. It is also worth noting that any creative that is prepared as a pushdown can easily be converted to a lightbox or fullscreen creative simply by changing the expand() and collapse() function calls to the corresponding lightbox and fullscreen functions.

Note Note

Working with a publisher that uses IFRAME tags to serve their ads via a third-party ad server? You will need to have them install an IFRAME breaker to support expandable creatives. Please click here for more information and installation instructions.

Mouse Functions

Tracking mouse events when the mouse cursor is within the banner area is simple and can be done using standard methods. However, if you wish to track the mouse outside of the banner area it complicated by the fact that the ad server actually loads HTML5 creatives into a friendly IFRAME tag. Fortunately we have an API method that allows you to listen for mouse activity outside of the banner area and it also conveniently returns the distance of the mouse pointer from the banner area.

FunctionDescription
AdvertEvents.detectMouseProximity(function(result){...}) Listens for mouse activity outside of the banner area and invokes the supplied callback function with an object containing the following properties:

{
  'distance': 123,
  'rect' : {
    'top' : 123,
    'left' : 123,
    'bottom' : 123,
    'right' : 123
  },
  'mouse' : {
    'x' : 123,
    'y' : 123
  }
}
Using this information you can easily determine the distance of the mouse pointer from the banner area as well as the coordinates of the mouse pointer and bounding box of the banner area itself relative to the parent document.

How might you actually use this functionality? Consider, for example, that you want a banner to start reacting to the user as they move their mouse pointer towards the banner. This might in turn trigger a subtle effect that causes the user to recognize the banner is reacting to them.

The following example gradually changes the background color from white to red as the mouse moves toward the banner:


<div id="container" style="width: 300px; height: 250px; border: 1px solid red; background-color: rgba(255, 255, 255, 1.0); box-sizing: border-box"></div>

<script type="text/javascript">
window.addEventListener('load', function() {
  AdvertEvents.detectMouseProximity(function (result) {
    var el = document.getElementById('container');
    if (result.distance < 200) {
      el.style.backgroundColor = 'rgba(255, 0, 0, ' + ((200 - result.distance) / 200) + ')';
    }
    else {
      el.style.backgroundColor = 'rgba(255, 255, 255, 1.0)';
    }
  });
});
</script>

As you can see the code is quite simple since the results provided to the callback function already contain the pre-calculated distance of the mouse pointer from the banner area. It's worth noting that you may also want to listen for the mouseenter and mouseleave events within your code as well. If a user is moving their mouse quickly the browser will stop sending events from the parent document once the mouse is within the IFRAME containing the banner, so you may not receive the last callback event indicating the distance is zero. By listening for the mouse to enter the banner area, however, you can get a more reliable notification of when that happens.

Pixel Functions

There may be times where an advertiser asks you to fire a pixel from a third-party ad server when certain events occur. The API provides methods for loading image, JavaScript and iframe pixels in such cases. This also enables feedback on when these pixels are loaded on the preview and test pages, which is useful for QA testing.

FunctionDescription
AdvertEvents.loadPixelImg(url) Loads an image pixel asynchronously.
AdvertEvents.loadPixelJS(url) Loads a JavaScript pixel synchronously.
AdvertEvents.loadPixelIframe(url) Loads an iframe pixel asynchronously.

How that code works is it first tries to auto play the video right away, but if the page or the creative are not visible it listens for the the visitor to scroll the parent window or for the page to become visible to try again. Why listen to the parent window? That is necessary since the ad server actually loads HTML5 creatives into a friendly IFRAME tag.

Visibility Functions

The API also provides convenient functions to detect if the browser tab is visible as well as if the creative is within the viewport. This can be useful in various situations. For example, you can avoid auto playing a video if the page or creative is not visible.

FunctionDescription
AdvertEvents.isPageVisible() Returns true if the browser tab is visible on the user screen. If the browser is minimized or the user switches to another tab this function will return false. However, it should be noted that about 12% of visitors have older browsers that lack visibility detection and the API always returns true for those users.
AdvertEvents.isCreativeVisible() Returns true if any portion of the creative is currently within the viewport of the browser tab or window. Otherwise returns false. However, this makes no guarantee that the browser tab or window is visible. You should combine this check with the isPageVisible() function if such a guarantee is required.
AdvertEvents.onVisibilityChange(callback) Allows you to supply a single callback function to receive notifications of viewability state changes. The viewability state is passed as an argument to the callback function. It can have three possible values: unknown, visible and hidden.
AdvertEvents.cancelVisibilityChange() Allows you to cancel execution of your visibility change callback function in the event you no longer need to receive notifications.

To give an example, consider that you do have a video that you want to avoid auto playing if the page and creative are not visible.


(function() {
  var autoplayFired = false;

  var autoplay = function() {
    if (!autoplayFired && AdvertEvents.isPageVisible() && AdvertEvents.isCreativeVisible()) {
      document.getElementById('MyVideo').play();
      autoplayFired = true;
      parent.window.removeEventListener('scroll', autoplay);
      parent.window.removeEventListener('visibilitychange', autoplay);
      return true;
    }
    else {
      return false;
    }
  };

  if (!autoplay()) {
    parent.window.addEventListener('scroll', autoplay);
    parent.window.addEventListener('visibilitychange', autoplay);
  }
})();

How that code works is it first tries to auto play the video right away, but if the page or the creative are not visible it listens for the the visitor to scroll the parent window or for the page to become visible to try again. Why listen to the parent window? That is necessary since the ad server actually loads HTML5 creatives into a friendly IFRAME tag.

Alternatively the same thing can be done by using a callback function that listens for visibility changes as shown in the following example.


(function() {
  var autoplayFired = false;

  var autoplay = function (state) {
    if (!autoplayFired && state == 'visible') {
      document.getElementById('MyVideo').play();
      autoplayFired = true;
      AdvertEvents.cancelVisibilityChange();
    }
  };

  AdvertEvents.onVisibilityChange(autoplay);
})();

That code works the same internally and is much simpler since you don't have to manage your own event listeners. Why provide both options then? That is a good question and the answer is backwards compatability because the onVisibilityChange() function was not included in earlier versions of this API.

VPAID Functions

The API also provides convenient access to our VPAID wrapper, which enables you to interact with the VPAID creative.

FunctionDescription
AdvertEvents.getVPAID().getAdWidth() Returns the width of the video player in pixels, which is also the width of the ad since it fills the entire video player space.
AdvertEvents.getVPAID().getAdHeight() Returns the height of the video player in pixels, which is also the height of the ad since it fills the entire video player space.
AdvertEvents.getVPAID().stopAd() Signals to the video player to stop playing the VPAID ad and resume playing the content video.
AdvertEvents.getVPAID().skipAd() Signals to the video player to skip playing the VPAID ad and resume playing the content video.

It is not necessary to call the startAd() function since our HTML5 wrapper calls it automatically when the HTML5 creative is loaded. Many other VPAID functions exist, but should not be used. This is due to the fact that our HTML5 wrapper pauses the video player, inserts the HTML5 creative over top of it and does not resume the video player until stopAd() is called. If you want your HTML5 creative to play a video it must invoke its own video player to do so, which may simply be an HTML5 video tag. It is also possible to use a third-party player such as JWPlayer or video.js if you need more advanced functionality.

VAST/VPAID Feeds

Advertisers who use a third-party ad server may wish to provide you with a VAST or VPAID XML feed to enable them to track video playback metrics in their third-party reporting. Our API provides support for this without requiring you to create your own wrapper. Currently we support VAST pre-rolls, VAST wrappers and VPAID (JS + Flash) although supporting Flash VPAID requires loading an additional script.

Here is a complete code that demonstrates how you can support all types of VAST and VPAID creatives.


<script type="text/javascript" src="//youraccount.advertserve.com/js/events1.js"></script>
<script type="text/javascript" src="//youraccount.advertserve.com/js/vpaid2flash.js"></script>

<div id="myVideo">
  <video id="myVideoPlayer" width="100%" height="100%"></video>
</div>

<script type="text/javascript">
window.addEventListener('load', function() {
  AdvertVastVpaid.loadVastXmlFeed(
    'mainVideoPlayer',
    'http://ad.dumbclick.net/ddm/pfadx/N99999.999999EXAMPLE/B99999999.99999999;sz=0x0;ord=[timestamp];dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;dcmt=text/xml',
    {
      "flashSWF" : '//youraccount.advertserve.com/swf/VPAIDFlash.swf',
      "controls": true,
      "handleClicks" : true,
      "onLoad" : function() { AdvertEvents.playVideoMutedIfNotPlaying('mainVideoPlayer'); },
      "onEnded" : function() { alert('video ended'); },
      "onError" : function() { alert('video error'); },
      "onUnload" : function() { alert('video unloaded'); }
    }
  );
});
</script>

The first thing you'll notice is that we load the HTML5 JavaScript API (events1.js) as well as our Flash VPAID client (vpaid2flash.js). However, the Flash VPAID client is not required if you do not need to support Flash VPAID. You can and should omit it if you do not need it to reduce the size of your HTML5 creative.

Next we have a simple placeholder (myVideoPlayer) that designates where the video will be loaded. Our player operates in HTML5 mode by default. However, it will switch to Flash mode automatically if required once the type of the creative is detected.

The last thing is to call the AdvertVastVpaid.loadVastXmlFeed() function which takes the following arguments:

ArgumentTypeRequired?Description
id String Yes This is the id attribute of the HTML5 <video> element that will play the VAST/VPAID creative.
url String Yes This is the URL of the VAST or VPAID XML feed.
options Object No
  • flashSWF - Must be provided if you require Flash VPAID support.
  • controls - When true the API adds a built-in play, pause and sound button to the HTML5 video element (may not work with custom VPAID players).
  • handleClicks - When true the API listens for clicks on pre-roll videos and VPAID creatives, but this can be disabled by omitting this option or setting it to false if you wish to implement custom click handling.
  • onLoad - A callback function that will be executed when the video loads
  • onEnded - A callback function that will be executed when the video ends
  • onError - A callback function that will be executed when an error occurs (i.e. if the VAST or VPAID feed fails to load)
  • onUnload - A callback function that will be executed when the video unloads
  • zIndex - Allows you to specify a custom z-index value for the VPAID player, which can be helpful when implementing overlays

Note Note

You might notice in the example above that we do not attempt to load the VAST/VPAID XML feed until the DOM load event has occurred. This is very important if Flash VPAID support is required. The reason for this is that the Flash VPAID client must be fully loaded in order to detect if Flash support is available or not. If you do not need Flash VPAID support though it is safe to execute your code sooner.