Skip to content

Commit

Permalink
moved api docs to docs/ dir, add ref to read me.md
Browse files Browse the repository at this point in the history
  • Loading branch information
Tim Sturtewagen committed Jun 17, 2013
1 parent ba47146 commit d75d64c
Show file tree
Hide file tree
Showing 16 changed files with 4,311 additions and 57 deletions.
162 changes: 150 additions & 12 deletions vast/adhese-vast.js
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,41 @@
// vast linear ads for html/js by adhese.com
// http://www.iab.net/media/file/VASTv3.0.pdf

/**
* @class
* The Adhese Vast JS library is meant to ease the integration of VAST (2.0 & 3.0) ads in video players.
* It contains cross-domain safe methods for requesting ads from your adhese account as well as convenience methods for playing and tracking the ads.
* It is however not a player on its own and it does not insert anything in the DOM.
* This implementation is based on the requirements as defined in {@link http://www.iab.net/media/file/VASTv3.0.pdf}.
* AdheseVastWrapper is the main object through which you will request ads and access the response.
* @example
* var wrapper = new AdheseVastWrapper();
* @param {boolean} debug true for debug mode
*/
function AdheseVastWrapper(inDebug) {
this.debug = inDebug!=undefined?inDebug:false;
}

/**
* Needs to be called after constructing or whenever you want to start your use of the wrapper all over again.
* Resets listeners, trackers and scheduled ads.
* @example
* wrapper.init();
* @return {void}
*/
AdheseVastWrapper.prototype.init = function() {
this.eventListeners = new Array(); // stores registered event listeners
this.trackedImpressions = new Array(); // stores fired impressions, to prevent multiple impression tracking (some players might simply listen to "playing" events)
this.schedule = {};
this.helper = new AdheseVastHelper();
};

/**
* Gets ads from Adhese account at given host for location and given array of formats. Fires ADS_LOADED event when finished. See {@link AdheseVastWrapper#addEventListener}
* @example
* wrapper.requestAds("http://ads.demo.adhese.com", "_test_", ["preroll","postroll"]);
* @param {string} host The protocol and host of your Adhese account
* @param {string} location The location indentification for the Ad position you are requesting.
* @param {Array.<String>} formats An array of strings containing the identification of the formats you want to request. These strings will be used as id for accessing scheduled Ad's properties.
* @return {void}
*/
AdheseVastWrapper.prototype.requestAds = function(inHost, inLocation, inFormats) {
var uri = inHost + "/jsonp/a.parseVastJson";
for (var f in inFormats) {
Expand Down Expand Up @@ -105,13 +129,32 @@ AdheseVastWrapper.prototype.parseXML = function(inXml) {
}
};

//player can register as listener for ADS_LOADED
/**
* Add a listener for the "ADS_LOADED" event.
* Every time you perform a call to requestAds, the event will be fired and you will be able to handle the Ads through your callback function.
* @example
* wrapper.addEventListener("ADS_LOADED", yourPlayerInstance.yourCallBackFunction);
* @param {string} event The name of the event. "ADS_LOADED" is currently the only option.
* @param {function} callBackFunction The name of the function to be executed when the event is fired.
* @return {void}
*/
AdheseVastWrapper.prototype.addEventListener = function(event, listener) {
this.eventListeners.push(
new AdheseVastEventListener(event, listener)
);
};

/**
* ADS_LOADED event. Fired whenever a request has been completed and the schedule array is ready.
* Upon firing this event, all requested ads and their properties are available to the implementing player.
* @event AdheseVastWrapper#ADS_LOADED
* @type {object}
*/

/**
* Fires the ADS_LOADED event.
* @fires AdheseVastWrapper#ADS_LOADED
*/
AdheseVastWrapper.prototype.fireAdsLoaded = function() {
for (var i=0; i<this.eventListeners.length; i++) {
if (this.eventListeners[i].getEvent()=="ADS_LOADED") {
Expand All @@ -121,7 +164,17 @@ AdheseVastWrapper.prototype.fireAdsLoaded = function() {
}
};

// ad schedule is available before display, it contains the id's of the active ads, as requested, only active ads are returned, if no ads, an empty array is returned
/**
* Gets the format names of the scheduled ads. This function will only return a value of a request has been amde and the ADS_LOADED event has been fired. If there is no ad available for a requested format, no entry will be included in the schedule array.
* @example
* // request two formats: "preroll" and "postroll"
* wrapper.requestAds("http://ads.demo.adhese.com", "_test_", ["preroll","postroll"]);
* // from your callback het the schedule
* var schedule = wrapper.getSchedule();
* // if only one of the two ads is actually scheduled, the array contains only one item
* // fi.: ["preroll"]
* @return {Array.<String>} Returns array of strings containing the scheduled format codes.
*/
AdheseVastWrapper.prototype.getSchedule = function() {
var arr = new Array();
for (var name in this.schedule) {
Expand All @@ -130,14 +183,34 @@ AdheseVastWrapper.prototype.getSchedule = function() {
return arr;
};

/**
* Checks if an Ad has been scheduled for a given format code.
* @example
* if (a.hasAd("preroll")) {
* //do something
* }
* @param {string} formatCode The format code for the requested ad.
* @return {boolean} Returns true if an Ad has been scheduled.
*/
AdheseVastWrapper.prototype.hasAd = function(adId) {
return this.schedule[adId]!=undefined;
};

/**
* Gets the "Impression" URI for a scheduled Ad. The Impression URI is used for racking the initial start of the Ad.
* You will normally not call this directly.
* @param {string} formatCode The format to identify the Ad.
* @return {string} Returns a string containing the URI for tracking a "VAST Impression Event".
*/
AdheseVastWrapper.prototype.getImpression = function(adId) {
return this.schedule[adId].getImpression();
};

/**
* Gets the "Click" target URI for handling a click on the player. This URI will also perform "VAST ClickThrough Tracking".
* @param {string} formatCode The format to identify the Ad.
* @return {string} Returns a string containing the URI for tracking a "VAST ClickThrough".
*/
AdheseVastWrapper.prototype.getClick = function(adId) {
return this.schedule[adId].getClick();
};
Expand All @@ -146,6 +219,17 @@ AdheseVastWrapper.prototype.getTrackers = function(adId) {
return this.schedule[adId].getTrackers();
};

/**
* Returns the URI for the ad's media actual media file. The media type parameter contains the actual mime type of the needed media file (eg: video/mp4, video/ogg).
* @example
* // create source element for video
* var adSrc = document.createElement("source");
* adSrc.src = wrapper.getMediafile("preroll","video/mp4");
* adSrc.type = "video/mp4";
* @param {string} formatCode The format to identify the Ad.
* @param {string} type The mime type of the requested file.
* @return {string} Returns the URI for the requested media type or undefined if no media type is available.
*/
AdheseVastWrapper.prototype.getMediafile = function(adId, type) {
var mf = this.schedule[adId].getMediafile();
for (var y=0; y<mf.length; y++) {
Expand All @@ -155,15 +239,29 @@ AdheseVastWrapper.prototype.getMediafile = function(adId, type) {
return undefined;
};

/**
* Get the duration of a scheduled Ad.
* @example
* // display duration
* infoContainer.innerHTML = "ad takes " + wrapper.getDuration("preroll") + " time, stay tuned";
* @param {string} formatCode The format to identify the Ad.
* @return {string} Returns a string of format hh:mm:ss.
*/
AdheseVastWrapper.prototype.getDuration = function(adId) {
return this.schedule[adId].getDuration();
};

/**
* Get the duration of a scheduled ad in seconds.
* @example
* wrapper.getDurationInSeconds("preroll")
* @param {string} formatCode The format to identify the Ad.
* @return {number} A positive integer number.
*/
AdheseVastWrapper.prototype.getDurationInSeconds = function(adId) {
return this.schedule[adId].getDurationInSeconds();
};

// whenever a player shows an ad, it should call it's Impressions uri
AdheseVastWrapper.prototype.track = function(uri) {
for (var x=0; x<uri.length; x++) {
// add uri to tracked, if already exists, do not track again
Expand All @@ -175,6 +273,15 @@ AdheseVastWrapper.prototype.track = function(uri) {
}
};

/**
* Callback function for player media event "timeupdate". This function will handle all tracking of impressions, progress, ... .
* @example
* // attach to timeupdate event for passing the currentTime, this allows adhese to track the actual viewing of the ad
* adPlayer.addEventListener("timeupdate", function() { wrapper.timeupdate("preroll", adPlayer.currentTime); }, true);
* @param {string} formatCode The format to identify the Ad.
* @param {number} currentTime The current time of the player, in seconds.
* @return {void}
*/
AdheseVastWrapper.prototype.timeupdate = function(adId, currentTime) {
if (this.debug) console.log(adId + " timeupdate @" + currentTime + " sec.");
// at start, log an impressions
Expand Down Expand Up @@ -204,21 +311,38 @@ AdheseVastWrapper.prototype.timeupdate = function(adId, currentTime) {
}
};

/**
* Callback function for "click" on player (or any container defined as clickable by you). This function will track the click and open a new window containing the click-through url of the ad.
* @example
* // clicks on video player should be sent to adhese for handling and reporting
* adPlayer.addEventListener("click", function() { wrapper.clicked("preroll", adPlayer.currentTime); }, true);
* @param {string} formatCode The format to identify the Ad.
* @param {number} currentTime The current time of the player, in seconds.
* @return {void}
*/
AdheseVastWrapper.prototype.clicked = function(adId, currentTime) {
if (this.debug) console.log("tracker clicked for " + adId + " @" + currentTime);
if (this.debug) console.log("open new window with VideoClicks>ClickThrough");
this.helper.openNewWindow(this.getClick(adId));
this.track(this.getTrackers(adId).click);
};

/**
* Callback function for player media event "ended". This function will track completion of the ad.
* @example
* // when playing has ended, tell and adhese and than continue to showing content
* adPlayer.addEventListener("ended", function() { wrapper.ended("preroll", adPlayer.currentTime);
* @param {string} formatCode The format to identify the Ad.
* @param {number} currentTime The current time of the player, in seconds.
* @return {void}
*/
AdheseVastWrapper.prototype.ended = function(adId, currentTime) {
if (this.debug) console.log(adId + " ended @" + currentTime);
if (this.debug) console.log("tracker complete for " + adId);
this.track(this.getTrackers(adId).complete);
};


// AdheseVastAd
function AdheseVastAd(inId, inMediaFile, inDuration, inImpression, inDurationInSeconds, inTrackers, inClick) {
this.id = inId;
this.mediafile = inMediaFile;
Expand Down Expand Up @@ -289,13 +413,19 @@ AdheseVastEventListener.prototype.getListener = function() {
};



// AdheseVastHelper
/**
* @class
* Helper class for utility functions.
*/
function AdheseVastHelper() {

}

// duration should be of format hh:mm:ss, fallbacks for mm:ss and ss
/**
* Method to get the value in seconds of a string representing time in one of these formats: "hh:mm:ss", "mm:ss" or "ss".
* @param {string} timeAsString The time to convert as a string of format "hh:mm:ss", "mm:ss" or "ss".
* @return {number} The value of the time in seconds or 0 if not a valid string.
*/
AdheseVastHelper.prototype.getDurationInSeconds = function(inDuration) {
if (inDuration) {
var d = inDuration.split(":");
Expand All @@ -313,9 +443,17 @@ AdheseVastHelper.prototype.getDurationInSeconds = function(inDuration) {
return 0;
};

/**
* Method to open a new window ("_blank") from the DOM window object and give it focus.
* If now window object is available, nothing happens.
* @param {string} uri The URI to be used as the location of the new window.
* @return {void}
*/
AdheseVastHelper.prototype.openNewWindow = function(uri) {
var win = window.open(uri, '_blank');
win.focus();
if (window) {
var win = window.open(uri, '_blank');
win.focus();
}
};


Expand Down
Loading

0 comments on commit d75d64c

Please sign in to comment.