Adsolutions - Tagman - Adsolutions

Adsolutions – Tagman

General

The TAGMAN (tagmanager) library implements the ad-tags on a publishers website, and provides an easy interface to control and interact with the ad-slots on the webpage. It’s also capable to operate in a fully asynchronous way, so the ad-calls won’t block the content flow of the publisher.

Additionally, it prevents the global scope being polluted, by only requiring a single global variable, which you can set with an optional second global variable. Advertisements are rendered into an iframe, so they will also have their own scope.

The Queue

The queue object is used, to predefine commands while the JavaScript library is loaded. The queue is flushed once the library is loaded, and when the DOM is ready, and once more when the document is loaded. The queue is a regular JavaScript object, any property within is a separated queue, and must be of an array type. This allows for multiple alternative TAGMAN configurations. There are 3 properties reserved, which are TAG, CONFIG and EVENTDISPATCHER. The TAG property is a proxy for all defined queues so that it’s possible to update the configuration or perform interactions with all defined TAGMAN instances. The CONFIG property defines global configurations. By default, the global variable name of the queue object is ASTAGQ, however it’s possible to use a different variable name. To do so, the variable name chosen must be set in the variable $__ASTAGQNAME. For example, if you choose to name your queue variable MyASTAGQ, you must set $__ASTAGQNAME = ‘MyASTAGQ’. If you choose to use the default variable name this is not required.

To define the queue variable, use the following code:

var ASTAGQ = ASTAGQ || { main: [] };

This either creates a new queue object, with one queue named main, or uses the already created one.

A queue command is a JavaScript function which receives 3 arguments, which are all optional. The arguments are in order, scope (which defines all classes which are exported from the library), queueObject (which holds a reference to the global queue object instance), currentQueue (which holds a reference to the current queue being processed).
Typically you would add a queued command with the following code:

ASTAGQ.main.push(function(scope,qObj, q){
    //code to execute, once the library is loaded
};

A basic TAGMAN implementation could look like:

ASTAGQ.main.push(function(scope,qObj, q){
    q.TAG.setAdserver('ADTECH',{nw:'72.34'})
    .addPlacement([{id:'4432106'}],'placement_001')
};

Which specifies to use the ADTECH ad server with network id 72.34. And adds a single placement with id 4432106, which must be rendered in a html element with id placement_001.

It’s important to have the network id setup correctly. The network id can be found on the right upper-corner of the I-Center.

Public interface TAGMAN

.setAdserver(Implementation, Configuration)

Description: Initialises the ad server configuration
Arguments:

Implementation; String, the name of the implementation
Configuration: Object, the configuration object, example: {nw:’74.43′}

The configuration object can have following properties;

nw: (string, required) the network id to use
autoAlias: (Boolean, optional) when true, it automatically set’s an alias to a placement, if no placement alias is specifically defined on the placement. By default its value is false.

Returns: TAGMAN instance

.addModule(module)

Description: Adds a module to the current TAGMAN instance (currently there is no support for global modules)
Arguments:

Module: Module instance, any javascript object which implements the public interface of a TAGMAN module.

Returns: TAGMAN instance

.setSite(siteName)

Description: Defines the site name, which for example can be used with the autoAlias feature.
Arguments:

siteName: (string), the site name

Returns: TAGMAN instance

.setPage(pageName)

Description: Defines the pagename, which for example can be used with the autoAlias feature.
Arguments:

pageName: (string), the page name

Returns: TAGMAN instance

.setTag(key, value)

Description: Sets a key/value(s) pair, on which can be targeted in the ad server, if the key is already set, it’s content’s will be overwritten
Arguments:

key: String, the name of the key. example: ‘bouwjaar’
value: Primitive (string, number) or Array of primitives. example: 2009

Returns: TAGMAN instance

.addTag(key, value,[keep])

Description: Sets a key/value(s) pair, on which can be targeted in the ad server, if the key is already set, the value’s will be added, if the keep argument is not supplied, or is set to true.
Arguments:

key: String, the name of the key. example: ‘bouwjaar’
value: Primitive (string, number) or Array of primitives. example: 2009
keep: Boolean, whether to keep the original values of the key

Returns: TAGMAN instance

.removeTag (key, [values])

Description: Removes a targeting key, or some values of a targeting key.
Arguments:

key: String, the name of the key. example: ‘bouwjaar’
values: (optional ) Primitive (string, number) or Array of primitives. example: 2009

Returns: TAGMAN instance

.setKeywords(keywords)

Description: Sets keywords overwriting the original, on which can be targeted in the ad server
Arguments:

Keywords: String or Array: either a single keyword string, or an array of keywords. They array can be either an array of string, or an array of keyword objects; a keyword object has 2 properties, word and con, for example {word:’cola’, con:’|’}. the con property can be either | or &, and allows to specify if the keyword should be connected with the previous keyword in an OR or AND fashion. By default the connection is OR.

Returns: TAGMAN instance

.addKeywords(keywords,[keep])

Description: Adds keywords without overwriting the original (unless keep = false), on which can be targeted in the ad server
Arguments:

keywords: String or Array: either a single keyword string, or an array of keywords. The array can be either an array of string, or an array of keyword objects; a keyword object has 2 properties, word and con, for example {word:’cola’, con:’|’}. the con property can be either | or &, and allows to specify if the keyword should be connected with the previous keyword in an OR or AND fashion. by default the connection is OR.
keep: Boolean, whether to keep the original keywords

Returns: TAGMAN instance

.removeKeywords(keywords)

Description: Removes keywords
Arguments:

Keywords: String or Array: either a single keyword string, or an array of keywords. They array can be either an array of string, or an array of keyword objects; a keyword object has 2 properties, word and con, for example {word:’cola’, con:’|’}. the con property can be either | or &, and allows to specify if the keyword should be connected with the previous keyword in an OR or AND fashion. by default the connection is OR.

Returns: TAGMAN instance

.disableBundleCall ()

Description: Disables bundled calling, meaning every ad-slot will perform its own ad-call. This is the default behavior
Arguments:
Returns: TAGMAN instance

.enableBundleCall ()

Description: Enables bundled calling, meaning all ad-slots will be requested in a single request. #NOTE: this is mutually exclusive with enableDirectCall
Arguments:
Returns: TAGMAN instance

.enableDirectCall ([totalPlacementCount])

Description: Disables waiting for all the ad-slot’s become available, meaning as soon as a call to addPlacement is performed, a watcher is started to see if the html element is or becomes available, once available the ad will directly start rendering.
Arguments:

totalPlacementCount: (optional) Number, which specifies how much placements in total will appear on the page, this is important for accurate load detection, however it’s not required, but it might cause for a too early fully loaded event, due to timing issues.

Returns: TAGMAN instance

.disableDirectCall ()

Description: The opposite of enableDirectCall, this is the default.
Arguments:
Returns: TAGMAN instance

.setMinimalVisibility (percent)

Description: Sets the minimal visibility, an ad-slot must have before it starts rendering. By default, ads are always rendered, regardless their visibility.
Arguments:

percent: Number, if it’s a positive number the ad requires to be that percentage of visibility within the viewport, when negative, visibility checking is disabled.
Returns: TAGMAN instance

.setRefreshPolicy (policy)

Description: Sets the interval times after which the ad-slots should be refreshed. The time starts counting after at least 1 ad-slot is loaded. By default there is no refresh policy
Arguments:

Policy: Number or Array of Numbers, the number are time in milliseconds to wait before a refresh is initiated. If a number is supplied, the ad-slot will refresh infinitely on that interval. If it’s an array, each element represents a time, and will be executed in order. If the element is positive this is the time to wait, if it’s negative the last time is used x times and then refresh stops, for example if the element is -3 the last time will be used for 3 more times. If the element is 0 the last time will be used to infinitely refresh.

Returns: TAGMAN instance

.setRenderDelay (delay)

Description: Sets a delay before rendering starts, this can be use-full if you only want to display ads to visitors which are at least x amount of time on the webpage.
Arguments:

Delay: Number, of milliseconds to wait before rendering.

Returns: TAGMAN instance

.disableRenderDelay ()

Description: Disables the render delay. This is the default.
Arguments:
Returns: TAGMAN instance

.requiresFocus ()

Description: Requires the tab or browser window to have focus, before rendering the ads.
Arguments:
Returns: TAGMAN instance

.ignoreFocus ()

Description: Render the ads regardless if the browser tab/window has focus. This is the default.
Arguments:
Returns: TAGMAN instance

.setRenderOn (on)

Description: Specifies when the ads should be rendered, the default is when the DOM is ready
Arguments:

on: String, which either can be;
- domready: render the ads when the is dom ready
- loaded: render the ads when all content is loaded (when window onload is triggered)
scroll: render the ads when the user for the first time scroll’s (for example use full for if ads are below the fold on content articles)
none: don’t render the ads automatically

Returns: TAGMAN instance

.setCookieMode (mode)

Description: Sets the cookie mode, the default is full
Arguments:

mode: String, which can either be;
full: use all cookie capabilities (eg. also cookie targeting)
normal: use normal cookie behavior
anonymous: disable the use of cookie’s

Returns: TAGMAN instance

.enableFlashDetection ([majorKey], [minorKey])

Description: Detects the flash version and passes it as key/value to the adserver, so it can be targeted for campaigns that require flash.
Arguments:

majorKey: (optional) String, specifies the key to use in the ad-call (default: flash), when null the value will not be send.
minorKey: (optional String, specifies the key to send the minor flash version (default: null, so by default only the major flash version is send)

Returns: TAGMAN instance

.disableFlashDetection ()

Description: The opposite of enableFlashDetection, this is the default
Arguments:
Returns: TAGMAN instance

.enableScreenDetection ([widthKey], [heightKey])

Description: Detects the screen resolution, and passes the result as key/value to the ad server, so campaigns can be targeted on the screen resolution of the user. This can be use full for large rich media ads, which don’t come to their full potential on small screen resolutions, for example when they don’t fit on it.
#NOTE: The detection, uses the standard javascript screen object, which means that it passes the resolutions of the primary screen of the user, and the actual document or window dimensions are not taken into account.
Arguments:

widthKey: (optional) String, the key name to use in the ad-call (default: screenwidth)
heightKey: (optional) String, the key name to use in the ad-call (default: screenheight)

Returns: TAGMAN instance

.disableScreenDetection ()

Description: the opposite of enableScreenDetection, this is the default
Arguments:
Returns: TAGMAN instance

.doPassLoadCount ([loadKey])

Description: Passes the times the TAGMAN has loaded ad’s as key/value to the adserver. this can be use full for example in conjunction with the refresh policy, so you can target premium campaigns on the first-call and remnant campaigns on refreshes.
Arguments:

loadKey: (optional) String, the key name to use in the ad-call (default: loadcount)

Returns: TAGMAN instance

.dontPassLoadCount ()

Description: The opposite of doPassLoadCount, this is the default
Arguments:
Returns: TAGMAN instance

.doPassPlacementCount ([placementCountKey])

Description: Passes the total amount of placements as key/value to the adserver.
Arguments:

placementCountKey: (optional) String, the key name to use in the ad-call (default: plccount)

Returns: TAGMAN instance

.dontPassPlacementCount ()

Description: The opposite of doPassPlacementCount, this is the default
Arguments:
Returns: TAGMAN instance

.enableDefaultDetection ()

Description: enables globally default detection for all placements, this is the default.
Arguments:
Returns: TAGMAN instance

.disableDefaultDetection ()

Description: disables globally default detection for all placements (opposite of enabableDefaultDection)
Arguments:
Returns: TAGMAN instance

.addEventListener (listenerObj)

Description: adds a listener object to the tagmanager instance, currently there are 2 events available;

onDefault; when a placement receives a default adserver response, the handler will receive 2 arguments, the first being tagmanager instance, the second the placement object which received the default adserver response.
onPlacementLoaded; when a placement is loaded, the handler will receive 2 arguments, the first being the tagmanager instance, the second the placement which is loaded.

Arguments:

listenerObj: an object defining the handlers, example:

{
onDefault:function(tagman, placement){
//do something

}
}

Returns: TAGMAN instance

.resetTags ()

Description: Clears all key/values defined
Arguments:
Returns: TAGMAN instance

.resetKeywords ()

Description: Clears all keywords defined
Arguments:
Returns: TAGMAN instance

.resetTargeting ()

Description: Clears all possible targeting parameters defined
Arguments:
Returns: TAGMAN instance

.addPlacement(sizes, htmlId, [configuration])

Arguments:

sizes: Array or Object, Array of size objects, otherwise an single size object. example: {id:123456,name: ‘468×60’,includeSizes:[‘1×1′,’468×60’]}
a size object can contain following properties;
- id: (number, string) the placement id (or fallback placement id)
- name: (string) the name of the placement, this will be used in conjunction with the autoAlias feature and represents the postfix of the alias string
- alias: (string) the alias of the placement, this overrides the autoAlias feature for this single placement
- includeSizes: (string, array or object) a size definition of sizes which are allowed to display on this placement
- excludeSizes: (string, array or object) a size definition of sizes which are not allowed to display on this placement
- tags: (object) defines additional key/values which only apply to this placement (this currently is not available when bundled mode is enabled). Example: {position:’pos1′,prijs:1500,extra:[‘val1′,’val2’]}
- keywords: (array, string) defines additional keywords which only apply to this placement (this currently is not available when bundled mode is enabled). The value is the same is the setKeywords argument. Example: [‘kw1′,’kw2’]
- htmlId: string or DOMNode, when it’s a string, the string must supply a valid html id, which at some point must appear in the DOM, in this node the advertisement will be rendered
- configuration: Object, an optional configuration object. The configuration object can have following properties;
- initialWidth: (number) the initial width (in px) the iframe should occupy (default: 0)
- initialHeight: (number) the initial height (in px) the iframe should occupy (default: 0)
- virtualWidth: (number) the virtual width (in px) the placement has, this value is used with visibility detection, when there is no initial width, or actual width known (default: 0)
- virtualHeight: (number) the virtual height (in px) the placement has, this value is used with visibility detection, when there is no initial height, or actual height known (default: 0)
- maxWidth: (number) the maximum width (in px) the iframe can occupy, which would mean if a larger creative is served, it will be partly hidden, but the site layout is protected (default: disabled)
- maxHeight: (number) the maximum height (in px) the iframe can occupy, which would mean if a larger creative is served, it will be partly hidden, but the site layout is protected (default: disabled)
- minWidth: (number) the minimum width (in px) the iframe will occupy, which would mean if a smaller creative is served, the placement will occupy a larger space, but the site layout is protected (default: disabled)
- minHeight: (number) the minimum height (in px) the iframe will occupy, which would mean if a smaller creative is served, the placement will occupy a larger space, but the site layout is protected (default: disabled)
- visibility: (number) overrides the global visibility detection value, use -1 to disable visibility detection.
- initialSizeMode: (string) read the initial dimensions from the defined placement placeholder element or by using the includeSize definition. By default it’s disabled (value: none), to enable set it to: auto, to read it from the placement placeholder element, and set it to: size to read it from the size definition
- reloadSizeMode: (string) how the placement should be sizes when a reload occurs, by default the placement dimensions will be reset to 0x0, to prevent this set it to value: leave, which will keep the placement to its current dimensions, till the new ad is loaded, and the new dimensions are known.
- dontManageContainer: (Boolean) whether or not the placement placeholder should be modified with the dimensions of the ad. By default: true, which means the placement placeholder will not be updated with the dimensions of the loaded ad, set the true, if you don’t want that the width and height are updated on the placement placeholder.
- allowForceSize: (Boolean) allow ads to force the dimensions of the iframe (by passing the autodetection), this only applies when they use the public interface, properties are not monitored ($ASTAG_PlacementObject.forceSize(width,height);). Default this is allowed
- restrainForcedSize: (Boolean) whether or not the min/max dimensions should be validated when a banner forces a size, default: true.
- defaultDetection: (Boolean) whether or not the placement should analyze the response if the adserver responded with a default ad. By default it’s enabled, disabling it might have a small performance improvement.

Returns: TAGMAN instance

.render ()

Description: Initiates the rendering process. Generally this doesn’t needs to be called, as it’s called automatically based on the renderOn policy (see setRenderOn). It’s possible to use this if you want the ads to load sooner than one of the renderOn event occurs. It’s advised to setRenderOn(‘none’) if you plan to call render manually. Also note, never call render in conjunction with enableDirectCall feature is enabled.
Arguments:
Returns: void

.reload ()

Description: Reloads all the ad-slots
Arguments:
Returns: Boolean, true when reload is directly initiated, false when it’s already loading, and it’s queued till load completes or when the reload is ignored, as there are no changes while a load was already in progress.

Debugger

To show the debug panel, place ASTAG_DEBUG somewhere in the url, if you want to show the debugger, if the page is already loaded, add the ASTAG_DEBUG string as has tag, thus #ASTAG_DEBUG
Example1: http://cdn.adsolutions.nl/tagman/test1.html?ASTAG_DEBUG
Example2: http://cdn.adsolutions.nl/tagman/test1.html#ASTAG_DEBUG

Examples

The basic, using a multiad call, to display all ad’s, and load polite;
http://cdn.adsolutions.nl/tagman/test1.html

Using a multiad call, to display all ad’s, and load polite, but only run the ad-code, if the ad-slot is visible(for more than 50%) (scroll down to see);
http://cdn.adsolutions.nl/tagman/test2.html

Using a multiad call, to display all ad’s, and load polite, and refresh the ad’s according a schedule, first 3sec, then 5, then 9, and repeat it 3 times more ;
http://cdn.adsolutions.nl/tagman/test3.html

Using a multiad call, to display all ad’s, and load polite, and refresh the ad’s according a schedule, first 3sec, then 5, then 9, and repeat it 3 times more, but only run the ad-code when the adslot is visible (for more than 50%) ;
http://cdn.adsolutions.nl/tagman/test4.html

Using regular addyn (javascript tags), and load polite;
http://cdn.adsolutions.nl/tagman/test5.html

Using regular addyn (javascript tags), and load polite, but only perform the ad-call when the ad-slot is visible (for more than 50%);
http://cdn.adsolutions.nl/tagman/test6.html

Using regular addyn (javascript tags), and load polite, but only perform the ad-call when the ad-slot is visible (for more than 50%), but again with a refresh schema;
http://cdn.adsolutions.nl/tagman/test7.html

Using regular addyn (javascript tags), but not load polite (thus as soon as the ad-slot becomes available (and is visible) the call is done), but only perform the ad-call when the ad-slot is visible (for more than 50%), but again with a refresh schema;
http://cdn.adsolutions.nl/tagman/test8.html

Same as 8, only adding an extra placement, which uses the multiad ad-call to display a table;
http://cdn.adsolutions.nl/tagman/test9.html

Same as 8, only adding an placement alias;
http://cdn.adsolutions.nl/tagman/test10.html

Adds Revenue Science module, enables; flash and screen detection, and send the loaded times and placement counts to the adserver, and uses anonymous ad-call’s. And only loads the ads when the browser tab has focus
http://cdn.adsolutions.nl/tagman/test11.html

Same as 11, but directly starts rendering, meaning, as soon as all html elements defined are available the ad-call is performed.
http://cdn.adsolutions.nl/tagman/test12.html

Shows a sample implementation of the autoAlias feature;
http://cdn.adsolutions.nl/tagman/test13.html

Adsolutions – Tagman