adsplayer.js

adsplayer.js is a javascript client/module that handles ad-insertion when playing streams with HTML5 based players, such as players using MSE/EME extensions.

adsplayer.js is compatible with MAST file format for describing the list of ad-insertion triggers, and with VAST format for ads playing description. When opening a new stream with hasplayer.js, the adsplayer.js plugin handles ad-insertion in the case a MAST file URL is provided.

adsplayer.js API enables using this module as a plugin/module for hasplayer.js.

The adsplayer.js plugin takes charge of:

• MAST and VAST files downloading
• detecting ad-insertion triggers
• pausing and then resuming the main player video when playing ad(s)
• opening and playing ad media files, by the help of <video> and <img> HTML components, created by the plugin and appended in the DOM container provided to the plugin

The web application that uses adsplayer.js in cunjunction with a HTML5 player has to take charge of:

• hiding/showing adsplayer.js components according to the events raised by the plugin
• opening the web page when a click on the playing ad has been detected by the plugin
• pausing/resuming the plugin (for example when application visibility changes)

Build / Run

# npm run build

The resulting built file adsplayer.js has to be included along with hasplayer.js.

Releases

The project releases are available at this address:

http://orange-opensource.github.io/adsplayer.js

Getting Started (when using with hasplayer.js)

When creating the hasplayer.js's MediaPlayer instance, create an AdsPlayer instance and add it to the MediaPlayer. The DOM element in which <video> and <img> HTML components will be appended for playing ad(s) has to be provided in the constuctor.

var mediaPlayer = new MediaPlayer();
var adsPlayer = new adsplayer.AdsPlayer(document.getElementById('adsplayer-container'));
mediaPlayer.addPlugin(adsPlayer);

When opening a stream with the MediaPlayer, the MAST file URL has to be provided in the 'adsUrl' stream parameter.

var stream = {
    url: "http://playready.directtaps.net/smoothstreaming/SSWSS720H264/SuperSpeedway_720.ism/Manifest",
    adsUrl: "<mast-file-url>"
};
mediaPlayer.load(stream);

In order to interact with AdsPlayer, the application has to register to some events raised by the AdsPlayer:

adsPlayer.addEventListener("start", function (e) {
    // Ad(s) playback is starting => the application shall show ad(s) player container and hide main video
});
adsPlayer.addEventListener("end", function (e) {
    // Ad(s) playback has ended => the application shall hide ad(s) player container and show main video
});
adsPlayer.addEventListener("addElement", function (e) {
    // A DOM element for playing an ad has been created and will be appended in the ads player container. The element can be either a <video> or an <img> element
});
adsPlayer.addEventListener("removeElement", function (e) {
    // the DOM element for playing an ad is being removed from the ads player container and deleted
});
adsPlayer.addEventListener("play", function (e) {
    // An ad's media playback is starting => the application should update play/pause button
});
adsPlayer.addEventListener("pause", function (e) {
    // An ad's media playback is paused => the application should update play/pause button
});
adsPlayer.addEventListener("click", function (e) {
    // A click has beed detected on the media component => the application shall open the corresponding web page, which URL is contained in parameter e.data.uri
});

AdsPlayer propose some more specific API methods in order to interact with the ad(s) playing:

adsPlayer.pause(); // Pause the playback of the current ad media
adsPlayer.play();  // Play/resume the playback of the current ad media

License

All code in this repository is covered by the BSD-3 license. See LICENSE file for copyright details.

Documentation

This API documentation describing AdsPlayer public methods and events can be generated using following gulp command:

# npm run doc