A JavaScipt library for interacting with Google DFP.
AdManager is a JavaScript library for interacting with Google Publisher Tags (GPT) and Google DFP. It handles the loading of the GPT library as well as the definition and request of ad inventory. Below you’ll find documentation on its configuration and usage.
- Installation
- Basic Usage
- Configuration
- Inventory
- Events
- Dynamic Insertion
- Contributing
- Dependencies
- References
Use the Bower package manager to install AdManager into your project. To do so you can either use the CLI:
$ bower install admanager --saveOr define it in your bower.json manifest:
"dependencies": {
"admanager": "latest"
}Similarly, AdManager can be installed using npm. To do so you can either use the CLI:
$ npm install admanager --saveOr define it in your package.json manifest:
"dependencies": {
"admanager": "latest"
}If package managers are not your thing, the library can be downloaded directly from GitHub using the Download ZIP button.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>AdManager Usage</title>
<script src="jquery.js"></script>
<script src="AdManager.min.js"></script>
</head>
<body>
<!--
This is the ad unit container. AdManager looks for all of the
[data-ad-unit] in the DOM and grabs the slot name to make a
request from DFP to fill those units.
-->
<div data-ad-unit="Unit_Name_in_DFP"></div>
<script type="text/javascript">
( function () {
var config = {
account: 1234567,
inventory: [
{
slot: 'Unit_Name_in_DFP',
sizes: [
[ 728, 90 ],
[ 970, 250 ],
[ 1000, 220 ]
]
}
]
};
AdManager( config );
} () );
</script>
</body>
</html>A configuration object is required to initialize the AdManager.
| key | type |
|---|---|
account |
Integer |
autoload |
Boolean |
clientType |
String |
inventory |
Array |
context |
String |
enabled |
Boolean |
targeting |
Array |
insertionEnabled |
Array |
insertion |
Object |
Example Configuration:
{
account: 1234567,
clientType: 'desktop',
inventory: [
{
slot: 'Unit_Name_in_DFP',
sizes: [
[ 728, 90 ],
[ 970, 250 ],
[ 1000, 220 ]
]
}
]
}Type: Integer
Default: null, must be specified
Description: Your network code, found in the “Admin” tab of DFP.
Type: Boolean
Default: true
Description: Whether to start the qualification process automatically.
Type: String
Default: 'default', optional
Description: This declares the client type (such as desktop, tablet, or mobile). The value can be set by an external client-detection script and will be used to compare against each inventory item to see whether the item should be displayed or not for that client.
For example, if a desktop device is detected, this value should be set to clientType: 'desktop' and items in the inventory array that match (type: 'desktop') will be displayed. This allows you to include both desktop and mobile inventory items, but only show the appropriate ones according to what clientType is set to at load time.
Type: Array
Default: [], must be specified
Description: An array of one or more objects that define different ad types. See the Inventory section below. More information can be found in the inventory section below.
Example:
var config = {
// ...
inventory: [
{
slot: 'Unit_Name_1',
sizes: [
[ 728, 90 ],
[ 970, 250 ],
[ 1000, 220 ]
]
},
{
slot: 'Unit_Name_2',
sizes: [
[ 728, 90 ],
[ 970, 250 ],
[ 1000, 220 ]
]
},
// ...
]
};Type: String
Default: 'body', optional
Description: This is used as a jQuery selector that specifies the DOM context where ads are to be inserted. In standard cases this will be static since there will only be one page. In infinite scroll applications, there may exist multiple pages in a single window and this provides a way to distinguish one page/context from another.
Type: Boolean
Default: true, optional
Description: This provides a way to disable the AdManager.
Type: Boolean
Default: false, optional
Description: Whether to enable dynamic insertion.
Type: Object
Example Insertion:
{
pxBetweenUnits: 800,
adHeightLimit: 1000,
insertExclusion: [
'img',
'iframe',
'video',
'audio',
'.video',
'.audio',
'[data-ad-unit]'
]
}Type: Array
Default:
[
'img',
'iframe',
'video',
'audio',
'.video',
'.audio',
'[data-ad-unit]'
]Description: When using the dynamic insertion feature, this allows customization of what elements to exclude when looking for valid insertion points.
Type: Integer
Default: 800, optional
Description: The minimum distance between dynamically inserted units.
Type: Integer
Default: 1000, optional
Description: The max height for dynamically inserted units.
The inventory array is a collection of objects that represent different ad positions.
| property name | type | |
|---|---|---|
slot |
String | |
sizes |
Array | |
type |
String | |
dynamic |
Boolean | |
localContext |
String | optional (required if dynamic: true) |
Example Usage:
var config = {
// ...
inventory: [
{
slot: 'Article_Leaderboard',
sizes: [
[ 728, 90 ],
[ 970, 250 ],
[ 1000, 220 ]
],
type: 'desktop',
dynamic: false
},
{
slot: 'Article_Dynamic',
sizes: [
[ 300, 250 ],
[ 300, 600 ]
],
type: 'desktop',
dynamic: true,
localContext: '.entry-content'
}
// ...
]
};Type: String
Description: The slot name defined in DFP.
Type: Array
Description: An array of accepted sizes for this unit. Must match up to the sizes defined in DFP.
Type: String
Description: This can be used to categorize inventory. For example, it can be used to denote whether an unit is for desktop or mobile devices. This value is checked against clientType.
Type: Boolean
Default: false
Description: This enables/disables dynamic insertion. If set to false, AdManager will expect a container on the page with the data-ad-unit attribute value that corresponds to the slot name defined in the Inventory object.
Type: String
Description: This is needed only for dynamic insertion. The string is a jQuery selector that specifies an insertion point for the new ad.
Example:
var config = {
// ...
inventory: [
// ...
{
slot: 'Article_Dynamic',
sizes: [
[ 300, 250 ],
[ 300, 600 ]
],
type: 'desktop',
dynamic: true,
localContext: '.entry-content'
}
// ...
]
};Custom jQuery events prefixed with AdManager.
| event | trigger source |
|---|---|
AdManager:libraryLoaded |
internal |
AdManager:adUnitRendered |
internal |
AdManager:slotsDefined |
internal |
AdManager:refresh |
external |
AdManager:runSequence |
both |
AdManager:emptySlots |
external |
AdManager:emptySlotsInContext |
external |
AdManager:importConfig |
both |
Description: This is triggered once when the GPT library is loaded.
Description: This is triggered each time an ad is rendered. Bind to this event to receive notification of a particular ad that has rendered.
Parameter: unit {Object}
| name | type | description |
|---|---|---|
name |
String | The slot name defined in DFP. |
id |
String | HTML id for the current ad wrapper. |
size |
Array | Indicates the pixel size of the rendered creative. |
isEmpty |
Boolean | true if no ad was returned for the slot, false otherwise. |
creativeId |
String | Creative ID of the rendered ad. |
lineItemId |
String | Line item ID of the rendered ad. |
serviceName |
String | Name of the service that rendered the slot. |
Description: This is triggered when slots are successfully defined, but before ads are rendered.
Description: Pass an array of slot names to be refreshed. Slots should already be in the DOM.
Example Usage:
$.event.trigger( 'AdManager:refresh', [ 'Unit_Name_1', 'Unit_Name_2' ] );Description: Trigger to run the full qualification sequence: the identification of positions in the DOM, define of DFP slots, targeting, request for creative, and display.
Example Usage:
$.event.trigger( 'AdManager:runSequence' );Description: Pass an array of slot names to be emptied.
Example Usage:
$.event.trigger( 'AdManager:emptySlots', [ 'Unit_Name_1', 'Unit_Name_2' ] );Description: Pass an array of slot names to be emptied within a selection.
Example Usage:
$.event.trigger( 'AdManager:emptySlotsInContext', {
$context: $( '.entry-content' ), // Defaults to the context set in the config.
removeContainer: true // Defaults to true
} );Description: Pass an object to import new configuration values. The new config will override values in the current config.
Example Usage:
$.event.trigger( 'AdManager:importConfig', {
targeting: {
category: [
'athletics',
'technology',
'graphic design'
]
}
} );Note: This feature is optional.
This feature allows AdManager to dynamically insert a variable number of new ad positions on the fly, without predetermined ad containers. The Insertion.js module contains logic that analyzes the DOM nodes in a specified text area to determine the optimal places where to insert ads.
- Add new inventory items that reflect the maximum possible number of dynamically inserted ads.
- Set the additional options
dynamicandlocalContextin the inventory config.
var config = {
// ...
inventory: [
// ...
{
slot: 'Dynamic_Unit_1',
sizes: [
[ 300, 250 ],
[ 300, 425 ],
[ 300, 600 ]
],
type: 'desktop',
dynamic: true,
localContext: '.entry-content'
},
{
slot: 'Dynamic_Unit_2',
sizes: [
[ 300, 250 ],
[ 300, 425 ],
[ 300, 600 ]
],
type: 'desktop',
dynamic: true,
localContext: '.entry-content'
},
{
slot: 'Dynamic_Unit_3',
sizes: [
[ 300, 250 ],
[ 300, 425 ],
[ 300, 600 ]
],
type: 'desktop',
dynamic: true,
localContext: '.entry-content'
}
]
};
AdManager( config );- If a more specific outer/main context is needed (the default context is
body), the propertycontextcan be added to the config. This is needed when keeping multiple contexts or articles separate, such as in infinite scroll applications. In the example below, it is.hentry.
<body>
<div class="hentry">
<div class="entry-content">
<p>Paragraph 1</p>
<p>Paragraph 2</p>
<p>Paragraph 3</p>
</div>
</div>
<script type="text/javascript">
( function () {
var config = {
// ...
context: '.hentry',
inventory: [
{
// ...
dynamic: true,
localContext: '.entry-content'
}
]
}
};
AdManager( config );
} () );
</script>
</body>AdManager follows the WordPress JavaScript Coding Standards. There is a .jscsrc included in the project for automatic linting using JSCS.
The modules are written in the UMD pattern to support AMD, CommonJS, and global usage.
The project contains a gulpfile.js for concatenation and minification. To use first install gulp and the dependencies (npm install). The default gulp task (gulp) will start the watch task.
AdManager requires jQuery.