jQuery 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.
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:
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:
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:
Also you can optionally specify custom targeting on a per ad unit basis in the following way:
Also you can optionally specify custom exclusion category on a per ad unit basis in the following way:
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.
In order to identify an ad unit on the page that is a video companion ad, set the data-companion attribute on that unit.
Calling the script:
Using a bootstrap file (take a look at example-bootstrap.js):
You can init the script in the following ways:
|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.|
This script provides two callbacks which you can use to make working with DFP a little easier.
||This is called after each ad unit has finished rendering.|
||This is called after all ad units have finished rendering.|
||Return the modified or overrided ad unit name. This function is called once per ad unit.|
||This is called before each ad unit has started rendering.|
||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!
|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:
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.