DFP Express Module
This module is a simplified alternate installation mechanism for publishers that have DoubleClick Google Publisher Tag (GPT) ad calls in their pages. Here’s how it works:
- You build a Prebid.js package that contains the extra module code and optionally the page’s AdUnits.
- The module intercepts ad behavior by overriding certain GPT APIs, coordinating the appropriate header bidding behavior, and then calling DoubleClick.
- Bidder parameters for the auction are determined by linking the DFP slots to the Prebid AdUnits
- Currently supports display formats only (i.e not video)
- DFP - DoubleClick For Publishers
- DFP Slot - Sometimes called ‘AdUnit’ in the DFP world, the slot is often a combination of size and page location. e.g. ‘top_leader’
- Prebid AdUnit - links the ad server slot to the header bidders and their parameters
- Div ID - the element ID of the HTML DIV where the ad will be displayed
Adding the module to a page could be as simple as just one line:
This one-line approach assumes that the AdUnits are appended to the end of the prebid.js package. An alternate approach to loading AdUnits is to bring them in from separate files:
The two-line method may allow for easier future update of the Prebid codebase, and allows Prebid code to be obtained from the Download page.
Prepare the AdUnit Configuration
Create an AdUnits file and source control it in a separate local repository. E.g. my-prebid-config/pub123adUnits.js:
- The pbjs and pbjs.que variables need to be defined if not already defined on the page.
- The DFP Express module will copy the sizes from the ad slots if they’re not specified in the AdUnits.
Build the package
Step 1: Bundle the module code
Follow the basic build instructions on the Gihub repo’s main README. To include the module, an additional option must be added to the the gulp build command:
This command will build the following files:
- build/dist/prebid-core.js - the base Prebid code
- build/dist/express.js - additional code for DFP express
- build/dist/prebid.js - a combined file with the base Prebid code and the DFP express code
Step 2: Append the AdUnits
If you’ve chosen to append the AdUnits right to the end of the package, use the command line to concatenate the files. e.g.
Step 3: Publish the package(s) to the CDN
Note that there are more dynamic ways of combining these components for publishers or integrators ready to build a more advanced infrastructure.
The DFP Express module adds one new function to Prebid:
This function initiates the scanning of the in-page DFP slots, mapping them to Prebid AdUnits, kicking off the Prebid auction, and forwarding the results to DFP.
The AdUnits argument is optional – if not provided it will look for AdUnits previously registered with pbjs.addAdUnits(). If no AdUnits can be found, it will return an error.
- DoubleClick must be the primary ad server and the pages must use enableAsyncRendering
- The first call to googletag.display() will run auctions for AdUnits that have codes matching one of these two conditions:
- AdUnit.code matches gptSlot.getAdUnitPath()
- AdUnit.code matches gptSlot.getSlotElementId()
- Additional calls to display() (e.g. an infinite scroll scenario) will run auctions only for new GPT slots that have been defined since the last call to display().
- If googletag.disableInitialLoad() is called, then Prebid Express will not run auctions when display() is called. Instead it waits for a call to refresh().
- When refresh(gptSlots) is called, Express will run auctions for the array of slots provided, or if none is provided, then for all slots that have been defined on the page.
- Integration works whether enableSingleRequest is on or off, but we recommend single request
- If enableSingleRequest is off, there are multiple calls to requestBids - one per slot
The practice of intercepting GPT ad calls has precedence in the industry, but may not work in all scenarios. The publisher assumes all risks:
- The approach used by the module may not work in complex page implementations. We recommend thorough testing.
- Obtaining Google support may be more difficult with this module in the page.
- Google may change GPT such that this module stops operating correctly.