GAM/DFP Express Module
This module is a simplified alternate installation mechanism for publishers that have 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 GAM/DFP slots to the Prebid AdUnits
- Currently supports display formats only (i.e not video)
- GAM - Google Ad Manager
- DFP - DoubleClick For Publishers is the old name of GAM.
- Slot - Sometimes called ‘AdUnit’ in the GAM/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
The prebid.js file needs to be loaded before the GPT library loads, unless you’re willing to manage the timing with additional queue functions. The examples here assume the easiest integration, which is synchronous.
The prebid.js file must also be constructed so that it contains:
- the Prebid.js adunits with the code keyed to the GAM slot name or the div element ID
- a call to pbjs.express()
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 Express module will copy the sizes from the GPT slots if they’re not specified in the PBJS 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 your 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.