71media AdLayer is a JavaScript library intended to make the integration of 71media commercials easier. The library now supports 92 types of ads: fullbanner, rectangle and 90 different video ads.

Though originally developed for the HBBTV platform only, AdLayer works on HBBTV, Samsung Apps, LG Apps/SmartAlliance and Xbox One and supports playback of video commercials in the HBBTV video object, LG Netcast video object, Samsung InfoLink video object, Samsung AV Play and the HTML5 video tag.

AdLayer offers complete management of displaying or playing back ads. However you can also use it to simply act as a mediator between the ad server and your app.

Sample applications

For your convenience we have prepared a few sample applications that you can have a look at before you begin with the integration of AdLayer into your own application. Please note, that these applications only exhibit the basic behaviour. To have a complete reference, you should still read this documentation before starting with the implementation.

Sample applications are available for HBBTV video object, HTML5 video tag, Samsung Orsay infolink player, Samsung Tizen using HTML5 videotag, Samsung Tizen using AVPlay, Virtual Player and Virtual Player for Samsung InfoLink

Page Parameters and DFP parameters

Ad delivery depends on DFP* parameters. DFP parameters are an ad server specific thing and are meaningless to the content providers. The content providers are able to describe the page from the content prospective. Such page description can then be mapped to the DFP* parameters, the language, which the ad server understands.

Parameters used by hbbtv.[prosieben|kabeleins|sat1|sixx].de are defined in https://confluence.sim-technik.de/pages/viewpage.action?pageId=26510559, Page Parameter section. All parameters are optional unless stated otherwise.

Setup options

There are 3 AdLayer components that require your attention:

the AdLayer javascript library, adlayer.min.js. To set up the library, include it into the DOM before any script that is using AdLayer like so:

<script type="text/javascript" src="http://ad.71i.de/global_js/AppConfig/Hbbtv/live/latest/adlayer-hbbtv.min.js"></script>

AdLayer mapping file Mapping file defines the ad strategy for your app and is created and managed by the ad manager. You will have to link to your mapping file as part of the AdLayer setup. There are several formats of the mapping file. Depending on the application you will receive one of the following:

JSONP mapping - suitable for application where cross domain AJAX requests are limited by the plattform. To setup this mapping, include the following script tag right after the adlayer.min.js script reference

 <script type="text/javascript" src="http://ad.71i.de/global_js/AppConfig/Hbbtv/live/sites/mapping_showroom.jsonp.js"></script>

JSON mapping - suitable for application where there are no cross domain AJAX limitations. Example platforms are: Xbox, Samsung Apps, LG Apps and basically every other platform where your application is able/must run locally on the device. The ad manager person will provide you with the path to such mapping file. You then pass this path to AdLayer in the setup call (see below)
JavaScript mapping - old mapping format which is deprecated and should not be used for new installations. For setting up JavaScript mapping include the following script tag after AdLayer reference:

    <script type="text/javascript" src="http://ad.71i.de/global_js/AppConfig/Hbbtv/live/sites/mapping_showroom.js"></script>

 In this case you should request your own copy of the mapping file from the responsible ad manager.

The page parameters At the beginning of each project the ad manager person will define a set of parameters that will affect the ad delivery to your application. This parameters will usually describe the page requesting the ad, for example, contentCategory, videoId, videoCategory, pageType etc. The set of page parameters is always individual and is discussed with every AdLayer consumer separately. A set of page parameters for existing consumers is defined later on in this document.

So to setup the AdLayer on a given html page you would:


<!-- include the AdLayer library (mandatory) -->
<script type="text/javascript" src="http://ad.71i.de/global_js/AppConfig/Hbbtv/live/latest/adlayer-hbbtv.min.js"></script>

<!-- include the AdLayer mapping script (for JSONP/Javascript mapping file types only) -->
<script type="text/javascript" src="http://ad.71i.de/global_js/AppConfig/Hbbtv/live/sites/mapping_showroom.jsonp.js"></script>

<!-- call the AdLayer.setup and AdLayer.setPageData methods -->
<script type="text/javascript">
    //<![CDATA[

    // general setup (see below the comlete setup function reference)
    AdLayer.setup({
        //mappingUrl : 'map.json', //for JSON mapping file only
        ads : {
            fullbanner2 : 'p7_banner', //id of the html element to hold fullbanner
            rectangle1  : 'p7_rect', // html element to hold rectangle
        },

        video : {
            videoElemId : '__video__'
        }

    });

    AdLayer.setPageData({
        ... pass page parameters here ...
    });

    //]]>
</script>

AdLayer.setup() call configures the general behavior of the AdLayer. All parameters here are optional:

startBar [url, default /portal/startbar] parameter defines where the green button should lead on the ad target page. This parameter is only relevant for HBBTV applications that are part of the Prosiebensat1 HBBTV portal.
proxyService there is a special proxy service that provides additional functionality to the AdLayer. The ad manager person will provide advice if you need to enable this service.
ads [hashmap] parameter assigns an ad format to the container on the page.
- fullbanner2 [string] id of the container for hosting fullbanner
- rectangle [string] id of the container for hosting rectangle
video [hashmap] parameter directs the behaviour of video ads.
- videoElemId (string, default __video__) id of the video/* object where video ads will be played.
- virtualPlayer [hashmap] object implementing Virtual Player.
mappingUrl [url, default empty] - a path to the JSON mapping file
uuidReceiverLocation - relative path to the host.html file. (See the UUID section for details)
uuidTrackLocation - absolute path to the track.html file. (See the UUID section for details),
nuggsid [string, optional, default empty] - a nuggad instance id. If you have not received the value for nuggsid from the ad manager you can ignore this parameter.
midrollResumeRewind - [number, default 0] a number of milliseconds to rewind the content video back after the midroll block has been completed. This is intentionally a global parameter and will apply to every midroll block if set.

Methods AdLayer.setup() and AdLayer.setPageData() may, be called repeatedly in any order, whenever the application needs to reconfigure AdLayer parameters. As mentioned above for AdLayer.setPageData() the parameters are defined individually for each application.

Displaying ads

To begin displaying ads, call AdLayer.display(adName);

adName (string) is the name of the ad in question (@see the ads parameter from AdLayer.setup()). If this parameter is omitted AdLayer will attempt to display all ads specified in AdLayer.setup().

Sometimes the ad server delivers a special commercial called powercorner. This commercial requires the fullbanner and rectangle to be stack together. In this case the AdLayer adds the class .powercorner on elements holding the both tiles. You have to define the necessary CSS rules for .powercorner yourself.

Calls to AdLayer.display(), without a prior call to AdLayer.setup() and AdLayer.setPageData(), will raise an exception. The AdLayer.display() method is asynchronous and does not return any values.

Playing video ads

AdLayer tries not to restrict the client application in the matters of video playback and is designed to work with any custom player. Players can subscribe to AdLayer's events to get notified about commercial playback. One playback session, that is a preroll block, content video with several midroll blocks and the postroll block can be initiated with the AdLayer.play method.

Example:

video.data = 'http://example.com/my-content-video.mp4';
AdLayer.play({

    pageData: {
        // ... page parameters
    },

    ads: {
        preroll: true
        midroll1: 15,
        midroll2: false
    },

    onPlayStateChange: MyOnPlayStateChangeHandler
});

AdLayer.play() quickstart/Upgrading to AdLayer 2.x

AdLayer v2 has introduced a small but important change in the interaction with your player object and with the video object.

In AdLayer v1, the integration looked like this:

AdLayer.setup(...);
AdLayer.setPageData(...);
AdLayer.play({
    onStart : function() {
        // Application prepares here for ad playback.
    },
    onStop : function() {
        // Ad has stopped playing, application prepares here for content playback
        // and eventually calls videoObject.play()
    }
})

AdLayer v2 has added support for ad blocks and midrolls which could no longer be accommodated in the logic above. Therefore the interface has changed into the following:

AdLayer.setup(...)
AdLayer.setPageData(...)

AdLayer.on(AdLayer.events.block.start, function (blockName) {
    // Application prepares here for ad playback
});

AdLayer.on(AdLayer.events.block.end, function (blockName) {
    // Application prepares here for content playback
    // but **does not** call videoObject.play
});

AdLayer.play();

The apparent change is that the application code has been moved from the onStart/onEnd event to the specific events block.start/block.end. The small important bit is to not call play() on the video object before starting the content video. The reason for this change is the midroll support - AdLayer now needs to be active also during the content playback.

The efforts for upgrading from AdLayer 1 to AdLayer 2 will depend on your ad plan, i.e. which ads you want to support.

Supporting a single preroll

If your app should still continue playing just a single preroll and nothing more (that is exactly how it has been with AdLayer 1), the integration remains essentially the same except for the single line of code containing the videoObject.play() instruction. To summarize your efforts you would:

Move the code from onStart and onEnd callbacks to the events as above.

Remove the line with videoObject.play() from the former onEnd callback.

Depending on the the particular implementation and platform it may be safe to even keep the videoObject.play(), since it would normally be ignored (not true for Infolink player)

Supporting a preroll block

AdLayer 2 supports playing back several commercial videos collectively called a preroll block. The user basically sees several ads followed by content. Integration in this case is exactly the same as above, except for the fact, that your application needs to be aware of multiple ads coming in. Summarizing your efforts to support a preroll block:

Move the code from onStart to onEnd callbacks to the events as above

Remove the line with videoObject.play() from the former onEnd callback.

Make sure, that your player remains idle during the whole block playback (ignore native videoHasCompleted events). Instead wait for AdLayer.events.block.end event and only lauch playback then.

That last third step is rather a precaution than an active requirement. If you had relied on the onEnd callback in the past, then you will not have to make any adjustments.

Supporting a preroll, one or more midroll and a postroll block

For integration of all the blocks your app would make use of all the events emitted by AdLayer. For a single content video the event sequence looks as follows (omitting AdLayer.events. prefix for bravity):

adlayer.init

block.start //preroll
--> for every video from the block
    * ad.start
    * ad.complete
block.end //preroll

content.play //content playback actually started
content.pause //contend will now be paused to play a midroll block

//for every midroll block
block.start //midroll
--> for every video from the block
    * ad.start
    * ad.complete
block.end // midroll

content.play //content resumes playing after midroll

...

block.start //postroll
--> for every video from the block
    * ad.start
    * ad.complete
block.end //postroll

adlayer.end //a full playback stretch is complete

As you can see this is a fairly repeating affair. For every ad block regardless its placement a block.start and block.end is called every time notifying your application to take action. This is again very similar to the former onStart and onEnd with the exception that the native play() method is called by the AdLayer itself immediately after the listeners for the block.end are executed. Every such event carries additional information about the block, ad type etc.

So summarizing your efforts for integration of all blocks you would:

In every block.start event prepare for the ad playback (as you did in the former onStart)

In every block.end event prepare for the content playback (as you did in the former onEnd)

Make sure that you do not call videoObject.play() on the native video object or interfere with the video object during ad playback (the second was also a requirement in AdLayer v1)

Be prepared for a midroll interruption, i.e. take additional preparations in a block.start/block.end for the midrolls, since the content video will be resumed after the block at the appropriate position.

During the time the content video is being played back you are in complete control over your video object. You can access all of the properties and call all of the methods including pausing, seeking or aborting the playback. On the non-<video> based players you should withdraw from changing the listeners on the video object during the playback session is in progress, since this will remove the AdLayer listeners and thus corrupt the playback.

Supporting several ad providers

If you have to support several ad providers or have versions of your application with and without ads it may be possible to keep using AdLayer in both versions and thus keep the codebase the same saving you great amounts of maintenance efforts.

To force an ad free version (to make the AdLayer 100% silent)

In your AdLayer.setPageData() call include the parameter adfree : true. Then talk to your ad manager to configure the mapping file accordingly. In this way you can keep all the AdLayer calls in your application while being 100% sure that no AdLayer-specific ads will be ever played back. Hence you can integrate other ad SDKs into the same player with confidence.

**To control the amount of blocks and ads in each ad block **

You can discuss this with the ad manager who will configure your mapping file to have the amount of ads that you require.

AdLayer and your video object

AdLayer interacts directly with the video object of your platform and emits events about different playback states of the ads and the content video. In case you do not want AdLayer to communicate directly with video object, you can use Virtual Player option.

Because AdLayer has to inject midroll commercials into your content video it must have a certain degree of control over the videoobject of your platform and the playback start should be done through AdLayer. In short: For playing back a single content clip with ads instead of calling videoObject.play() call AdLayer.play(). AdLayer will prepare the ads and initiate the playback according to your ad program. This requirement does not pose any limitation on your current video player implementation. You are still able to interact with the video object exactly as before and there is generally no need to change anything else in your current player.

When you call AdLayer.play() it starts looking for the configuration of a preroll block. If the preroll block is not explicitly forbidden in the configuration AdLayer contacts the ad server to collect preroll information and starts playing the block. After that your content video URL is restored to the player and the .play() method is called on the video object. During the playback of the content video AdLayer stands by and watches the position of the video. If the position matches the time configured for a midroll block, AdLayer collects the block information from the ad server and then plays back a midroll block. Then content video URL is restored to the player and a .seek() method is called on the video object to revert to the position where the video has been interrupted. Then video is resumed at the interrupted position. The same happens for every midroll block. After the content video is completed the postroll block is fetched from the ad server and played back. After that a stop() method (or equivalent for your platform) is called and that completes the video playback session.

Every step of the way AdLayer emits events that your app can listen to and act as necessary. Check out events section as well as the event flow example here.

`AdLayer.play` configuration options.

srcUrl (string, optional) The URL of the content clip that should be played back. If you don't set this parameter AdLayer will attempt to use the one currently set on the video object. It is generally advised to set this parameter explicitly. Important if you don't set srcUrl and your videoobject will not contain a valid URL, then you may experience weird behaviour such as commercial clips playing instead of the content video.
ads (object, optional) values contain names of ads or ad blocks that should be configured. Keys are either true, false or a positive number. So preroll : true means allow playback of preroll block, midroll2 : false means disallow playback of the second midroll block, midroll3 : 75 means that the content video will be interrupted at approximately 75th second for the third midroll block. The ads parameter is optional so you can leave it completely out in which case your ad inventory will be managed completely by the ad server. It is recommended that you leave this parameter out.
pageData (object, optional), since version 2 AdLayer allows for passing the pageData in the call, so that you do not need a separate AdLayer.setPageData() call. This parameter is optional, however if missing the app is expected to call the AdLayer.setPageData() prior to the AdLayer.play() call.
onStart (function deprecated) a callback which should be invoked before ad playback starts. This parameter is deprecated, use the event system instead
onEnd (function deprecated) a callback, which should be invoked after the playback has ended (for any reason). The callback function will receive adType as its parameter This parameter is deprecated, use the event system instead.
onPlayStateChange function - a client playStateChange handler. Not relevant for players based on HTML5 video tag. AdLayer will overwrite current playStateChange listener on the video object, so make sure to pass your listener in this way
displayArea object (for InfoLink and Tizen AVPlay based players only) - object that holds video dimensions. If displayArea is not defined AdLayer will try to get video dimensions from video object. Object must have 4 properties:
- top - display area distance from top of the screen;
- left - display area distance from left of the screen;
- width - display area width;
- height - display area height.

Calls to AdLayer.play() method will throw an exception if called prior to AdLayer.setup(). If pageData is not set AdLayer.play() will also fail if called prior AdLayer.setPageData(). If you have specified your display ads in AdLayer.display AdLayer will implicitly call AdLayer.display()

There is a number of video object types available in the SmartTV world. Adlayer supports the following interfaces: HBBTV video/mp4, video/mpeg object, LG netcast video object and HTML5 video tag. As long as your particular video object implements all interfaces of one of the mentioned object, there is a good chance, that it will be supported as well.

HBBTV onPlayStateChange handler

Unfortunately HBBTV does not support the addEventListener method on the HBBTV video object and some devices do not provide read access to the current onPlayStateChange handler. Therefore the last parameter in the AdLayer.play method is of importance for non-trivial applications, because AdLayer will redefine the onPlayStateChange handler right before the commercial playback and restore the handler after the commercial end. During the commercial playback AdLayer notifies the client application about the events on the video object by calling this handler. The application does not need to take any additional action to receive information about the events.

InfoLink event handlers

Unfortunately, addEventListener method cannot be used with InfoLink player to capture player-specific events. If you need to listen to any of such event - you should assign listener before launching AdLayer.play method. During advertisement playback listeners must not be changed, as they are managed by AdLayer. Listeners, defined before AdLayer.play will still be triggered with associated events.

Note, that in older versions of Samsung TVs (2011) listeners must be defined as strings - names of the functions in global scope.

function listener() { ... }
video.OnCurrentPlayTime = 'listener';

var Listeners = { myListener: function() { ... } };
video.OnCurrnetPlayTime = 'Listeners.myListener';

Showrooms

The ad server uses a number of criteria to determine which ad to display or whether to display an ad at all. During the development this can be quite confusing, since it is not immediately obvious if and which component is buggy. You can force the ad server to skip all the limiting and rotating logic and to deliver the same ad for the same ad position by specifying a showroom. Showroom can be specified in any of the following ways:

by specifying a showroom : "showroom_name" in your AdLayer.setup call.
by adding a &showroom=showroom_name&subsite=hbbtv parameters to the URL of the app (if available).
by specifying the showroom in the mapping file (ad managers only).

You will get a list of showroom names appropriate for your app ad inventory. The now available showrooms are:

vast2_all causes a (possibly random) ad to be delivered every time.
vast2fb_all - causes a scenario where no ad is delivered for any ad position.

A special mapping file is prepared with showroom parameter set to vast2_all. Use it during development:

<script src="http://ad.71i.de/global_js/AppConfig/Hbbtv/live/sites/mapping_showroom.jsonp.js"></script>

Ad blocks, delivery and tracking

AdLayer supports the following commercial blocks: preroll, midroll1, ..., midroll5, postroll. Every block can contain up to 15 commercial videos. The exact amount of the ads in a block depends on various conditions and is controlled by 71media. For development purposes you may disable delivery of the specific ad by specifying it in the ads configuration object passed to AdLayer.play, for example: ads : {"sponsor1b" : false} (for complete example refer to "Playing ads" section). The commercials in block are played back one after another without pauses or interruptions. User should not be able to skip or pause any of the commercial videos. AdLayer does not enforce this however, so it is left up to the application.

The complete list of rolls grouped by blocks supported by AdLayer is as follows:

//preroll
"preroll1",   "preroll1b",   "preroll1c",   "preroll1d",   "preroll1e",
"sponsor1",   "sponsor1b",   "sponsor1c",   "sponsor1d",   "sponsor1e",

//midroll1
"presplit1",  "presplit1b",  "presplit1c",  "presplit1d",  "presplit1e",
"midroll1",   "midroll1b",   "midroll1c",   "midroll1d",   "midroll1e",
"postsplit1", "postsplit1b", "postsplit1c", "postsplit1d", "postsplit1e",

//midroll2
"presplit2",  "presplit2b",  "presplit2c",  "presplit2d",  "presplit2e",
"midroll2",   "midroll2b",   "midroll2c",   "midroll2d",   "midroll2e",
"postsplit2", "postsplit2b", "postsplit2c", "postsplit2d", "postsplit2e",

//midroll3
"presplit3",  "presplit3b",  "presplit3c",  "presplit3d",  "presplit3e",
"midroll3",   "midroll3b",   "midroll3c",   "midroll3d",   "midroll3e",
"postsplit3", "postsplit3b", "postsplit3c", "postsplit3d", "postsplit3e",

//midroll4
"presplit4",  "presplit4b",  "presplit4c",  "presplit4d",  "presplit4e",
"midroll4",   "midroll4b",   "midroll4c",   "midroll4d",   "midroll4e",
"postsplit4", "postsplit4b", "postsplit4c", "postsplit4d", "postsplit4e",

//midroll5
"presplit5",  "presplit5b",  "presplit5c",  "presplit5d",  "presplit5e",
"midroll5",   "midroll5b",   "midroll5c",   "midroll5d",   "midroll5e",
"postsplit5", "postsplit5b", "postsplit5c", "postsplit5d", "postsplit5e",

//postroll
"sponsor2",   "sponsor2b",   "sponsor2c",   "sponsor2d",   "sponsor2e",
"postroll1",  "postroll1b",  "postroll1c",  "postroll1d",  "postroll1e"

Before the block playback AdLayer is requesting data for every member of the block allowed by the configuration, so you may see many parallel requests if all the ads are enabled. During ad playback AdLayer various additional URLs are called to report the usage. You may be bound legally to inform the user about this and to present the user with the opt out interface to switch off the tracking. AdLayer in cooperation with AdProxy - a server software offers means for switching off the tracking.

Multiple ad requests on the same page

The order of requesting ads is important to the AdServer, therefore AdLayer enforces the following ad sequence: fullbanner2, rectangle1, preroll1, postroll1. You may skip some of the ads, if your application does not require them. AdLayer will however prevent you from requesting the ads in any other order. Calling AdLayer.setPageData with relevant parameters allows you to restart the sequence (NOTE: passing the pageData object in AdLayer.play has the same effect as calling AdLayer.setPageData). Consider the following examples:

Wrong:

AdLayer.setPageData(); --- ok
AdLayer.display(); --- ok
AdLayer.display(); --- Exception: Ad sequence is not allowed

Right:

AdLayer.setPageData() --- ok
AdLayer.display(); ---- ok
AdLayer.setPageData([some new parameters]) --- ok
AdLayer.display() --- ok

Wrong:

AdLayer.setPageData() --- ok
AdLayer.play() --- ok
AdLayer.display() or AdLayer.play() --- Exception: Ad sequence not allowed

Right:

AdLayer.setPageData() --- ok
AdLayer.play() --- ok
AdLayer.setPageData([some new parameters]) --- ok
AdLayer.play() --- ok
AdLayer.setPageData([some new parameters]) --- ok
AdLayer.display() or AdLayer.play() --- ok

Advanced usage

If for some reason you are unable to use the AdLayer.play() or AdLayer.display() functions, that is your app has specific requirements, that conflict with that of the AdLayer, you still can save your self a solid amount of work by using the AdLayer as a proxy between the ad server and your app. Instead of AdLayer.play() or AdLayer.display() just call AdLayer.getAdTag(adName, callback). This function will construct the URL, which you can then use to retrieve ad information yourself. Please note however, that in this case your app is responsible for all related ad tracking, which especially in the case of video ads is quite a complicated matter.

We recommend not using AdLayer.getAdTag() unless the situation with AdLayer.play() and AdLayer.display() is really absolutely hopeless.

Virtual Player

In case your video player implementation does not allow AdLayer to communicate directly with video object, you can implement virtual player adapter. Adapter is a plain object with a few mandatory methods, that you must implement. Adapter must be passed to AdLayer during setup as follows:

AdLayer.setup({
        /**
         * ... Your usual parameters
         */
        video: {
            /**
             * Instead of "videoElemId",
             * "virtualPlayer" adapter is passed
             */
            virtualPlayer: {
                /**
                 * Start playing given URL
                 * As a precaution, make sure
                 * to check URL is provided
                 * and is different from
                 * current one before assigning it.
                 * @param url {String|Null}
                 * @param time {Number} - Start playback
                 *  from given time, ms
                 */
                play: function(url, time) { /* ... */ },
                /**
                 * Stop playback
                 */
                stop: function() { /* ... */ },
                /**
                 * Get current video playback position
                 * This method will be called
                 * sequentially during playback and
                 * it's expected to return updated and
                 * accurate results
                 * @return {Number} ms
                 */
                getPosition: function() { /* ... */ },
                /**
                 * @return {Number} video duration in ms
                 *     or 0 if not yet available
                 */
                getDuration: function() { /* ... */ },
                /**
                 * Callback, provided through this function,
                 * must be saved and called
                 * after video actually started playing
                 * e.g. on readyState == 4 for html5 video
                 * It is expected, that video metadata
                 * is available after this callback is called
                 * @param clbk {Function}
                 */
                setStartCallback: function(clbk) { /* ... */ },
                /**
                 * Callback, provided through this function,
                 * must be saved and called
                 * every time video playback is completed.
                 * Stop/pause actions must not trigger
                 * the callback.
                 * @param clbk {Function}
                 */
                setEndCallback: function(clbk) { /* ... */ },
                /**
                 * Callback, provided through this function,
                 * must be saved and called
                 * every time video error has occur.
                 * @param clbk {Function}
                 */
                setErrorCallback: function(clbk) { /* ... */ }
            }
        }
    });

Troubleshooting Virtual Player adapter

When AdLayer has direct access to video object (not using Virtual Player), it manages a wide range of video object peculiarities. If Virtual Player is used, it's up to adapter to handle them. The rule of thumbs is to keep all data accurate and updated, even if video object fails to do so.

For example, Samsung InfoLink Player provides current position via event "OnCurrentPlayTime", but event is fired irregularly. So, it is important to update local variable, that is used to store current position, after "play", "stop" or "seek" are called. See Samsung InfoLink Virtual Player demo for an example.

Here are few common cases:

Simptom	Likely cause	Resolution
Content is not playing, only ads	"getPosition" method returns staled or inaccurate results	Make sure "getPosition" always return correct result, specially after "play", "stop" or "seek" is called
First video playback is fine. Second video starts not from beginning	"stop" method is not implemented properly	"stop" method means full stop, not pause. Current position should be set to 0 and video SRC is cleared
AdLayer end event is called right after playback of ad or content video began	Some players tend to throw false-positive video errors	It's up to adapter to detect such errors and not to pass them to error callback

Ad server selection

AdLayer currently supports sending ad requests to "doubleclick" and "adition" ad servers. By default "doubleclick" is used. If you need to use "adition" server, you can define it in page data as follows:

    AdLayer.setPageData({
        ... usual page data params ...
        adServer: 'adition'
    });

Emitted events

AdLayer fires a number of events during the video playback and provides an interface for event subscriptions.

Events available for subscriptions

You can subscribe to an event defined on AdLayer.events. Following events are available:

block.start - ad block is ready to start, parameters: blockName that is one of preroll, midroll1, ..., midroll5, postroll
block.end - ad block is over, parameters: blockName same as above
ad.play- ad is ready to play. Parameters adId and adName. For the names overview see above.
ad.complete - ad playback is complete. Parameters adName.
ad.start - ad is being played back (that is the commercial video is really playing). No parameters.
ad.firstQuartile - ad playback has reached 25%. No parameters.
ad.midpoint - ad playback has reached 50%. No parameters
ad.thirdQuartile- ad playback has reached 75%. no parameters
content.pause - content video has been paused. No parameters
content.play - content video playback is started. Parameters playbackPosition (integer). Note that this event fires multiple times, for example after restarting the video after a midroll block.
content.end - content video playback is finished. No paramenters.
adlayer.init - AdLayer is ready to start playback. Parameters videoObjectIsAbleToSeek (boolean). If the AdLayer detects that the video object is unable to seek in the video this value will be true and the playback of all midrolls will be disabled.
adlayer.end - AdLayer has completed the playback cycle. No parameters
adlayer.dataMapped - page parameters have been mapped. Parameters mappedData (object).
adlayer.abort - The AdLayer.abort method has been called and AdLayer has been reset to initial state.
adlayer.unseekable - AdLayer has detected that the device is not able to seek at all or does this incorrectly. AdLayer will flag the device as not fit for playing midrolls. The flag will expire eventually and the midroll playback will be reattempted in the future to account for changed circumstances.

Adding/Removing an event listener

Listeners can be registered by method AdLayer.on(name, func, runOnce, priority) and unregistered with AdLayer.off(name, func, runOnce).

name string, one of the events from AdLayer.events
func callback to be executed when the event occurs.
runOnce boolean default false - if true, listener will be unregistered after the first execution.
priority integer, optional - order in which the listeners will be called. (lower first)

Both .on and .off return the AdLayer object allowing you to chain multiple listeners.

Example using the event system


    function trackPlay() {
        console.log('play was fired');
    }

    //register event play
    AdLayer.on(AdLayer.events.play, trackPlay, 0, 10);

    //unregister event play
    AdLayer.off(AdLayer.events.play, trackPlay, 0);

Thrown errors

In some situations AdLayer cannot continue nor recover and is forced to throw an error. Error is always an object containing the error code in the code field. Following errors can be thrown:

Code 1 : No mapped data for adName Code 2 : "No url for adName Code 3 : "Unknown ad adName Cause: Either the submitted adName is wrong, or the mapping file is wrong. Doublecheck the adName then contact support.
Code 4 : "No container on page for adName Cause: Container with id specified in the setup call is missing on the page at the time the AdLayer.display call has been attempted.
Code 5 : Map method not overridden and no mapping data available Cause: Either you did not setup the mapping file properly, or the mapping file is corrupt. Verify the setup then contact support.
Code 6 : Server response in unknown format Cause: Ad server returned unexpected response. Contact support.
Code 8 : Setup required Cause: Application called to an AdLayer method prior to calling AdLayer.setup()
Code 9 : Ad sequence not allowed: adName1 -> adName2. Call setPageData to reset this. Cause: Application requested another commercial within the same "adserver session". Refer to the section "Multiple ad requests on the same page" for resolution
Code 11 : Failed to fetch mapping data Code 13 : Failed to parse mapping data Code 14 : No mapping rules defined Cause: The mapping file is unreachable, corrupt or in the wrong format. Verify path, then contact support.
Code 15 : Parameter value not allowed parameterName Cause: Value of the parameterName you have passed in setPageData is not allowed in the mapping file. Adjust the value.
Code 16 : Play already called Cause Play function was called while player is already playing.
Code 17 : Page data was not set while mapping ad adName Cause AdLayer was trying to apply mapping for ad adName, but page data was not defined by that moment.

Unique id module

This AdLayer module creates and maintains a persistent id for a user. The id is persistent across all domains on which this component is used. Enabling uuid will enable the adserver to use a more efficient strategy when delivering ads. The current implementation uses an Iframe to store the id, on some platforms this may not be possible/allowed. If it is a case with your platform consult the options with a responsible ad manager.

Integration

There are 2 versions of the uuid module. Choose one based on your requirements. Please note, that if the uuid is not yet present inside the users browser additional files will be downloaded to support the generation process. After the uuid has been generated, no additional files will be downloaded.

First of the 2 supporting files a track.html is hosted on the AdServer. The ad manager person will provide you with the path to that file. The second of the supported files you will have to host yourself on the same domain where you intend to host your application.

uuid bundled with AdLayer.

The ad manager person will provide you with the location of the track.html file. If you have decided to also integrate AdLayer or have it already integrated do the following:

Follow the general setup process as described in the beginning of this document.
Host the html file from release/host.html on your server in a convenient location.

Pass location to host.html and track.html into AdLayer.setup

    AdLayer.setup({
        ....
        uuidReceiverLocation : "path/to/host.html/on/your/server",
        uuidTrackLocation : "path/to/track.html/on/ad/server"
        ....
    });

On some devices/browsers the uuid module is able to function without host.html. However hosting this file greatly expands the range of supported devices.

Standalone uuid module.

The ad manager person will provide you with the location of the adlayer-uuid.min.js and track.html file.

Link the script adlayer-uuid.min.js to yout html file.
Host the html file from host.html on your server in a convenient location.
Include the following lines right after the script from step 1. AdLayer.uuid.setReceiverIframeLocation('web/path/to/host.html'); AdLayer.uuid.setTrackIframeLocation('path/to/track.html/on/ad/server'); Note the the first call expects a relative path whereas the second expects absolute path.
To request the uid use AdLayer.uuid.getUuid(yourCallbackFunction);. The uuid will be thus passed to yourCallbackFunction as the only argument. The return value from the call above should be ignored. You may execute the getUuid call as many times as you wish. The uuid will be available shortly after the first request.

Please note, that the standalone uuid module requires the DOM to be ready, so do not attempt to call the AdLayer.uuid.getUuid() before the load event.

Hosting the file host.html is optional, however doing so greatly expands the range of supported devices.

UUID module in Tizen applications.

AdLayer stores the UUID at the ad.71i.de domain. In Tizen app you will have to allow this domain explicitly in your config.xml like so:

<tizen:allow-navigation>ad.71i.de</tizen:allow-navigation>

Otherwise you may experience weird behaviour such as browser launching on itself.

AdTech Integration Guides

Integrating the AdLayer

Sample applications

Page Parameters and DFP parameters

Setup options

Displaying ads

Playing video ads

AdLayer.play() quickstart/Upgrading to AdLayer 2.x

Supporting a single preroll

Supporting a preroll block

Supporting a preroll, one or more midroll and a postroll block

Supporting several ad providers

AdLayer and your video object

`AdLayer.play` configuration options.

HBBTV onPlayStateChange handler

InfoLink event handlers

Showrooms

Ad blocks, delivery and tracking

Multiple ad requests on the same page

Advanced usage

Virtual Player

Troubleshooting Virtual Player adapter

Ad server selection

Emitted events

Events available for subscriptions

Adding/Removing an event listener

Example using the event system

Thrown errors

Unique id module

Integration

uuid bundled with AdLayer.

Standalone uuid module.

UUID module in Tizen applications.

Sample applications

Page Parameters and DFP parameters

Setup options

Displaying ads

Playing video ads

AdLayer.play() quickstart/Upgrading to AdLayer 2.x

Supporting a single preroll

Supporting a preroll block

Supporting a preroll, one or more midroll and a postroll block

Supporting several ad providers

AdLayer and your video object

AdLayer.play configuration options.

HBBTV onPlayStateChange handler

InfoLink event handlers

Showrooms

Ad blocks, delivery and tracking

Multiple ad requests on the same page

Advanced usage

Virtual Player

Troubleshooting Virtual Player adapter

Ad server selection

Emitted events

Events available for subscriptions

Adding/Removing an event listener

Example using the event system

Thrown errors

Unique id module

Integration

uuid bundled with AdLayer.

Standalone uuid module.

UUID module in Tizen applications.

`AdLayer.play` configuration options.