Table of Contents

Overview

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:

  1. There is a limit of 2 hierarchies per ad unit 
  2. 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:  
domain.com/sports

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.

Note: DFP Ads cannot be used with Email Reach (Newsletters) setup due to javascript.


Google Reference Sites

Setup Options

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. 

+6 
DFP simple 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.

+6 
DFP simple ad block

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. 

+6 
DFP blocks

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. 

+6 
DFP SB Premium

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">
+6 
DFP settings network code domain
  • 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

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:

  1. System-defined templates: templates provided for you by DoubleClick for Publishers and are not editable.
  2. 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

Usually, hiding a Google DFP ad with CSS is a problem because Google will still load the JavaScript and download the ad - though it won’t show up. Technically, this is against Google DFP’s terms of use. In addition, if the site is paying for Google DFP Premium, they would have to pay for those ad impressions that are never seen.

With our new BLOX Flex integration with Google DFP, we’ve solved this problem. We use a feature of JavaScript that is able to look at a “DIV” element and see if it is empty in the page DOM (because it has been set to “display: none” by CSS). If it is, we do not run the JavaScript to load the Google DFP ad, and so it is not triggered as an impression.

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)

Troubleshooting Tools/Tips

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. 

  1. Within DFP, generate tags for the ad unit in question
  2. 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
  3. 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:

https://chrome.google.com/webstore/detail/google-publisher-toolbar/omioeahgfecgfpfldejlnideemfidnkc?utm_source=chrome-ntp-icon

The Chrome extension shows overlays on ads, to identify network ID and ad unit, line item and creative information.

+6 
Google Publisher Toolbar

 

Google Publisher Console

https://support.google.com/dfp_sb/answer/181070?hl=en

If your network uses Google Publisher Tags (GPT), you can use an on-screen debugging tool called the Google Publisher Console to troubleshoot delivery problems. The console checks your page for many common JavaScript tagging errors, identifies all of the ad units and creatives on the page, and helps you visualize the ad request behavior of a web page.

append ?google_force_console or ?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:

  1. Per URL 
    Add ?preview_ads=true to the end of your preview URL

    Ex. https://admin-newyork1.bloxcms.com/domain.com/tncms/admin/action/main/preview/site/?preview_ads=true

  2. Site Setting
    Add ads_run_in_preview site setting
+6 
ads_run_in_preview