Table of Contents
- Google reference sites
- Setup Options
- Simple ad block
- URL based ad block
- URL based fixed ad units
- Bulk importing BLOX URLs as DFP ad units
- Creative Templates
- How to hide ads while avoiding false impressions
- Troubleshooting tools/tips
This document explains the integration between BLOX "Flex" (responsive design) templates and Google DFP (Doubleclick for Publishers).
To simplify the integration between BLOX and Google DFP, we've eliminated the need to export DFP ad code (generating tags) and paste that into your site. We take care of the code that is common to each DFP ad export, like header scripts, and only require you to enter variables in BLOX that are unique to your DFP account, like your network ID, ad unit names, etc..
WARNING: Due to a recent change in Google DFP software, we no longer support bulk uploading ad units via our CSV file. Instead, you must create the ad units manually (see BEST PRACTICE below).
Previously, for ad units that were part of an inventory hierarchy (where the full path of the ad unit is required) you could import a CSV file with hierarchical ad units.
Ex. of an ad unit with 2 hierarchies: domain.com/sports
Ex. of an ad unit with 3 hierarchies: domain.com/sports/local
Ex. of an ad unit with 4 hierarchies: domain.com/sports/local/high_school
All of the ad unit examples above were previously able to be bulk imported...
Now, after the Google DFP update, there are 2 significant changes when bulk uploading:
- There is a limit of 2 hierarchies per ad unit
- DFP automatically attempts to create hierarchies, instead of viewing the slashes (/'s) as just part of the ad unit name.
For example, if you bulk uploaded the following ad unit:
Before the DFP update, it would create 1 ad unit, and the slashes were just considered part of the name.
After the DFP update, it now looks at each slash as an indication of a hierarchy, and will create the sub-hierarchies automatically.
So with our example, now it would first create domain.com
then /sports inside of domain.com
So what's the problem?
When BLOX is expecting to match a DFP ad unit of domain.com/sports, it HAS to be the full path as a single ad unit, not the combination of multiple hierarchies to make up that ad unit.
BEST PRACTICE: You can still use the CSV file for a reference of what ad units to create within the DFP admin, but you will need to create each ad unit manually within DFP, and each ad unit needs to have the full BLOX URL path.
Note: As of June 2016, Google DFP Small Business has changed the columns required during a Bulk Ad Unit upload. "Target Platform" and "Mobile Platform" are no longer available as bulk upload criteria, as these criteria were already deprecated from inventory settings. Do not include these columns in your bulk upload files. You are still able to use the "DFP Small Business Ad Units" skin/export option, but please note that the columns mentioned above need to be removed from the .csv file prior to uploading to DFP. See DFP Release Notes. Our Templates have been updated to accommodate the change with DFP.
Best Practice - It is recommended that when positioning DFP Ads on your site that you position the smaller Ads at the top working towards larger ones at the bottom. The purpose is because if the larger ad is first, then the width of the ad space is reserved going down the page, thus creating white space on your site.
Google Reference Sites
- DFP Premium Help Center: https://support.google.com/dfp_premium
- DFP Small Business Help Center: https://support.google.com/dfp_sb
Simple Ad Block
The most simplistic approach for pulling in DFP ads into BLOX is to create the "Ads: Google DFP (Simple)" ad block, and place the ad block on the page where you want the ad to show. So for every ad unit in DFP, there would be an equivalent BLOX ad block.
This block allows you to enter the network code, ad unit and size(s) from DFP, and the ad block will pull in the DFP ad targeted to that ad unit.
Pro: very simple
Con: requires the creation of a BLOX ad block for every ad unit. If your DFP setup has a small amount of ad units, this may be a good solution. If it has many ad units, we recommend using the URL based approach below.
URL Based Ad Block
It's important to remember that the key to the DFP/BLOX integration is that we're simply attempting to match ad units. Whatever the ad unit is in DFP, BLOX needs to match.
With the URL based approach, we take advantage of block inheritance, and require that your DFP ad units are formatted like your BLOX site's URLs.
Example ad unit: domain.com/news
The URL based approach for pulling in DFP ads into BLOX is to create an ad block that matches your DFP account type; either a "Ads: Google DFP (SB)" (small business) or "Ads: Google DFP (Premium)" ad block.
Similar to the "Simple" ad block, these ad blocks are placed on the page where you want the ad to show up. Unlike the "Simple" ad block, these do NOT require an ad block for every ad unit.
So how does it NOT require an ad block for every ad unit? To answer that question, we first need to understand what these blocks do.
Within the "SB" and "Premium" ad blocks, the following fields are available, and are used to match the overall DFP ad unit information.
Let's look at how the block's fields' values, when put together, start to form the ad unit and size information that is required to match the DFP ad unit and size information when BLOX calls/queries DFP:
- Network Code: the ad unit call starts with the network code (your Network Code can be found in the top right corner of your DFP admin)
Example DFP code generated: <data-dfp-adunit="/1234">
- Include Domain: the ad unit name can include the domain, and is often a good idea, in the instance where your DFP account is used for more than one site, and the domain is the differentiation in ad units. The domain is set in the Blocks "Page customizations" settings panel, within the "Advertising" menu.
Example DFP code generated: <data-dfp-adunit="/1234/domain.com">
- Include The URLMap Path: the ad unit then includes the URL (and possible sub-URLs). These blocks identify the URL they're sitting on, and use that URL as part of the overall ad unit it expects to match from DFP. These blocks rely on the requirement that the DFP ad unit is formatted as a URL. ie. domain.com/news
This is also where block inheritance comes in. So for example, if this block is placed on the homepage and inherits through the rest of the site, when viewing the block on the homepage, the ad unit would be: /1234/domain.com/homepage
The same block (which inherits from the homepage) on news, the ad unit would be: /1234/domain.com/news
The same block (which inherits from the homepage) on sports, the ad unit would be: /1234/domain.com/sports
Example DFP code generated: <data-dfp-adunit="/1234/domain.com/news">
- Include a Index/Homepage Slug: (Rarely used) If you had the need to serve separate ads on an index page or homepage, you can use this to add the necessary slug to the end of your ad unit. So for example, if you have the need to serve an ad on /sports, but a completely separate ad on sports' sub-URLs (ie. /sports/baseball, /sports/basketball, etc.), then you could use this slug in a block to add "index" to the end of the ad unit, identifying the /sports URL
Example DFP code generated: <data-dfp-adunit="/1234/domain.com/news/index">
- Sizes: The size is required for DFP to know which DFP line items and creatives can serve, and is added after the ad unit code.
Example DFP code generated: <data-dfp-adunit="/1234/domain.com/news/" data-dfp-size="[729,90]">
- Include a Custom Targeting keyword (pos): While DFP supports custom "Key-values", the only targeting key that BLOX currently supports is "pos". Within DFP, make sure your targeting key is "pos". The values can be whatever you want, as long as they match the value you enter in the block. This allows you to target specific positions when the ad unit (URL) and the size are the same.
Example DFP code generated: <data-dfp-adunit="/1234/domain.com/news" data-dfp-size="[728,90]" data-dfp-custom-pos="leaderboard-top">
What about in-story ads? BLOX doesn't yet support the ability to place blocks inside an article (asset). (This feature is scheduled to be released in 2016).
To place ads inside a story, or to use our default ad regions/positions and not worry about creating ad blocks, you can use our fixed ad units.
URL Based Fixed Ad Units
For information on fixed ad positions options, view the Fixed ad positions within our Banner Ads workspace document. This includes different modes (how many fixed positions are available to use) as well as the names of the fixed positions that would need to be targeted by DFP's pos values.
Bulk Importing BLOX URL's as DFP Ad Units
When using DFP Small Business, you have the option to bulk import your ad units. When integrating with BLOX, we recommend using BLOX URLs as your ad units.
Google DFP Small Business Setup w/ BLOX (Flex only) walks you through the steps of how to create and export a .csv file from BLOX containing your ad units, and how to import them into DFP.
Note: As of June 2016, Google DFP Small Business has changed the columns required during a Bulk Ad Unit upload. "Target Platform" and "Mobile Platform" are no longer available as bulk upload criteria, as these criteria were already deprecated from inventory settings. Do not include these columns in your bulk upload files. You are still able to use the "DFP Small Business Ad Units" skin/export option, but please note that the columns mentioned above need to be removed from the .csv file prior to uploading to DFP. See DFP Release Notes. Our Templates have been updated to accomodate the change with DFP.
Creative templates are predefined creative types that you can use when adding a new creative. A few examples of creative templates would be an ad locked to the bottom of the page, a full page interstitial ad, or a pencil pushdown.
There are two types of creative templates:
- System-defined templates: templates provided for you by DoubleClick for Publishers and are not editable.
- User-defined templates: Create your own template that you can customize with unique variables.
Here are DFP templates that will work with Flex and are responsive, with “friendly iframe” technology (that works with async): http://help.bloxcms.com/app/dfp_flex_templates/
IMPORTANT: You want to download the creative templates as .txt files and IMPORT them. Here is more information about importing user-defined creative templates in DFP: https://support.google.com/dfp_premium/answer/1138308?hl=en
How To Hide Ads While Avoiding False Impressions
This means that the ad won’t get an impression for that page load, and the website will not be charged for that impression.
To hide the ads at the appropriate times, we use Bootstrap’s responsive utility classes to hide or show the ads at various times (when the site is in desktop mode, or smartphone mode, for example).
For more information on Bootstrap's classes, see: CSS Classes (Flex only)
Does the ad serve OUTSIDE of BLOX?
Prior to troubleshooting why an ad is not showing up in your BLOX site, first ensure that the ad serves correctly outside of BLOX... In other words, take BLOX out of the equation.
- Within DFP, generate tags for the ad unit in question
- Copy the ad tag scripts (header & body) and paste code in dreamweaver/notepad
Make sure the code is pasted inside the appropriate <head> and <body> tags
- Save as .html file and view
If the ad appears, you know it is serving correctly from DFP and the issue is the BLOX setup/integration
If the ad does NOT appear, then either the required waiting time
Google Publisher Toolbar
Within the Chrome web store, search for "Google Publisher Toolbar" and add to your Chrome browser, or go directly to:
The Chrome extension shows overlays on ads, to identify network ID and ad unit, line item and creative information.
Google Publisher Console
?googfc to your page's URL
Previewing DFP Ads in BLOX
There are two options to enable viewing of DFP ads while viewing the site in preview mode:
- Per URL
Add ?preview_ads=true to the end of your preview URL
- Site Setting
Add ads_run_in_preview site setting