jQuery DFP - A jQuery implementation for Google DFP ======================================================
npm install jquery.dfpjQuery DFP - A jQuery implementation for Google DFP
======================================================
This script is a drop in solution for getting Double Click for Publishers (DFP) by Google working on your page. By including this script on your page and then initialising it in the ways described below you should find it very easy to get DFP working.
Do not include any of the generated DFP script tags from the DFP admin on your page, this script replaces them.
This script also works with Zepto.js
Demo / Ad unit tester
---------------------
You can use this page to test your DFP ads using the jquery.dfp.js script. There is some debug code included to help debug the ad delivery.
You can also use the Google Console to debug your ad units. This is done by by adding a "google_console=1" or "google_debug=1" to the url, and toggling the console by pressing CTRL + F10. Subsequent pagerequests will not require the parameters, and the console can be toggled. Adding the querystring "googfc" to an url, will also load the console, but also show it, without having to press CTRL + F10.
Setup
-----
You can add ad units to your page in any location that you would like to display an ad.
By default this script will look for ad units with a class of adunit but you can of course use jQuery selectors as well.
The minimum information required for an ad unit to function is having the ad unit specified. To do this you can use the id parameter of the element, for example:
``html`
In the example above the ID of the div element will be used to look up a corresponding ad unit in DFP and the dimensions of the adunit will be set to the same dimensions of the div which could be defined in your CSS.
You can optionally specify the adunit name and dimensions in the following way:
`html`
This method can be useful for including multiple copies of an ad unit with the same name which when part of a DFP placement will then pull in as many different creatives as possible.
You can also specify multiple dimensions sets:
`html`
Also you can optionally specify custom targeting on a per ad unit basis in the following way:
`html`
Also you can optionally specify custom exclusion category on a per ad unit basis in the following way:
`html`
To create an out of page ad unit set the data-outofpage property on the ad unit. Dimensions are not required for out of page ad units.
`html`
In order to identify an ad unit on the page that is a video companion ad, set the data-companion attribute on that unit.
`html`
Usage
-----
Calling the script:
`html
`
Using a bootstrap file (take a look at example-bootstrap.js):
`html
`
You can init the script in the following ways:
`javascript`
$.dfp('xxxxxxxxx');javascript`
$.dfp({
dfpID:'xxxxxxxxx'
});javascript`
$('selector').dfp({
dfpID:'xxxxxxxxx'
});javascript`
$('selector').dfp({
dfpID:'xxxxxxxxx',
setCategoryExclusion: 'firstcategory, secondcategory'
});javascript`
$('selector').dfp({
dfpID:'xxxxxxxxx',
setLocation: { latitude: 34, longitude: -45.12, precision: 1000 }
});
`javascript`
$('selector').dfp({
dfpID:'xxxxxxxxx',
sizeMapping: {
'my-default': [
{browser: [1024, 768], ad_sizes: [980, 185]},
{browser: [ 980, 600], ad_sizes: [[728, 90], [640, 480]]},
{browser: [ 0, 0], ad_sizes: [88, 31]}
],
}
});
Available Options
-----------------
| Option | Description |
|---|---|
| dfpID | This string is your unique DFP account ID. |
| setTargeting | This object is where you set custom targeting key value pairs. Also see the Default Targeting options that are set further down the page. |
| url | This string is the url used by the URL Targeting feature. The default value of this option is the value found by calling window.location. |
| setUrlTargeting | This boolean specifies whether the targeting should include information found in the url of the current page. The default value of this option is true. |
| setCategoryExclusion | This comma separated list sets category exclusions globally (page level). |
| setLocation | This object sets geolocalization. String values are not valid. |
| enableSingleRequest | This boolean sets whether the page ads are fetched with a single request or not, you will need to set this to false it you want to call $.dfp() more than once, typically you would do this if you are loading ad units into the page after the initial load. |
| collapseEmptyDivs | This can be set to true, false or 'original'. If its set to true the divs will be set to display:none if no line item is found. False means that the ad unit div will stay visible no matter what. Setting this to 'original' (the default option) means that the ad unit div will be hidden if no line items are found UNLESS there is some existing content inside the ad unit div tags. This allows you to have fall back content in the ad unit in the event that no ads are found. |
| refreshExisting | This boolean controls what happens when dfp is called multiple times on ad units. By default it is set to true which means that if an already initialised ad is initialised again it will instead be refreshed. |
| sizeMapping | Defines named size maps that can be used with in combination with the data-size-mapping attribute to enable responsive ad sizing (https://support.google.com/dfp_premium/answer/3423562?hl=en). |
| companionAds | If adding companion ads to accompany videos using the IMA SDK to serve video ads, then pass this parameter as true to identify the units being used for that purpose. (https://support.google.com/dfp_premium/answer/1191131) |
| disableInitialLoad | This allows for serving companion ad units when the video on the page auto plays. You'll need to include this setting with companionAds as true to avoid possible double impressions. (https://support.google.com/dfp_premium/answer/1191131) |
| setCentering | Enables/disables centering of ads. |
| afterEachAdLoaded | This is a call back function, see below for more information. |
| afterAllAdsLoaded | This is a call back function, see below for more information. |
| beforeEachAdLoaded | This is a call back function, see below for more information. |
Callbacks
---------
This script provides two callbacks which you can use to make working with DFP a little easier.
| Callback | Parameters | Description |
|---|---|---|
| afterEachAdLoaded(adUnit) |
| This is called after each ad unit has finished rendering. |
| afterAllAdsLoaded(adUnits) |
| This is called after all ad units have finished rendering. |
| alterAdUnitName(adUnitName, adUnit) |
| Return the modified or overrided ad unit name. This function is called once per ad unit. |
| beforeEachAdLoaded(adUnit) |
| This is called before each ad unit has started rendering. |
| afterAdBlocked(adUnit) |
| This is called after each AdUnit has been blocked. |
Please see the example-bootstrap.js file for an example of how to use these.
Default URL Targeting
---------------------
The following targeting options are built into this script and should be setup in your DFP account (within Inventory/Custom Targeting) to make full use of them. These targeting-parameters can be turned on/off with the setUrlTargeting option.
Beware: The Targeting string has a 40 character limit!
| Key | Description |
|---|---|
| UrlHost | This allows you to target different host names, for example you could test your ads on your staging environment before pushing them live by specifying a host of staging.yourdomain.com within DFP, this script will take care of the rest. |
| UrlPath | This allows you to target the path of the users browser, for example if you set UrlPath to '/page1' on the targeting options of the DFP line item it would match http://www.yourdomain.com/page1 only and not http://www.yourdomain.com/page1/segment2. |
| UrlQuery | This allows you to target the query parameters of a page. For example if the URL was http://www.yourdomain.com/page1?param1=value1 you could target it with a DFP ad by specifying a UrlQuery targeting string of param1:value1 |
DFP now supports both a "begins with" and a "contains" operator when specifying the custom criteria value. Furthermore the value when using free-form-key-value custom criterias, is no longer subject to a 40 character limit. Read more about custom criteria in the DFP help.
IMPORTANT: Regarding user-identifiable information in url targeting
If your url contains user-identifiable information you have to anonymize the url when using URL targeting.
From the DFP docs:
> You may not pass any user-identifiable data (including names, addresses, or user IDs) in the targeting. Please mask this information using the encoding of your choice, and ensure your ad trafficker knows how to decode the values when setting up a line item.
From the DFP Terms & Conditions:
> 2.3 Prohibited Actions. You will not, and will not allow any third party to: ... (h) utilize any feature or functionality of the Program, or include anything in Program Data or Program Ads, that could be so utilized, to personally identify and/or personally track individual end users or any other persons
Ignoring this rule can result in Google shutting down your network!
You can anonymize the url by providing an anonymized version in the 'url' option. This example shows how to replace email occurances in the url with an empty string:
`javascript`
$('selector').dfp({
dfpID: 'xxxxxxxxx',
url: window.location.toString().replace(/\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,4}\b/gi, '')
});
Contributing
------------
Any and all contributions will be greatly appreciated.
If you wish to you can use Grunt to enable a smooth contributing and build process.
Install Node.js by running sudo apt-get install nodejs
Install Grunt using: npm install -g grunt-cli
Once installed run npm install from inside the cloned repo directory.
You should now be able to make your changes to jquery.dfp.js and once you are finished simply run grunt` if there are no errors then you can commit your changes and make a pull request and your feature/bug fix will be merged as soon as possible.
Please feel free to write tests which will test your new code, Travis CI is used to test the code automatically once a pull request is generated.
Thanks a lot to these contributors.