Table of Contents

Overview

This document explains the integration between BLOX "Flex" (responsive design) templates and Google GAM (Doubleclick for Publishers).

To simplify the integration between BLOX and Google GAM, we've eliminated the need to export GAM ad code (generating tags) and paste that into your site. We take care of the code that is common to each GAM ad export, like header scripts, and only require you to enter variables in BLOX that are unique to your GAM account, like your network ID, ad unit names, etc.. 


WARNING: Due to a recent change in Google GAM 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 GAM update, there are 2 significant changes when bulk uploading:

  1. There is a limit of 2 hierarchies per ad unit 
  2. GAM 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 GAM update, it would create 1 ad unit, and the slashes were just considered part of the name. 

After the GAM 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 GAM 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 GAM admin, but you will need to create each ad unit manually within GAM , and each ad unit needs to have the full BLOX URL path.


Note:  As of June 2016, Google GAM 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 "GAM 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 GAM. See GAM Release Notes. Our Templates have been updated to accommodate the change with GAM .



Best Practice - It is recommended that when positioning GAM 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: GAM 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 GAM ads into BLOX is to create the "Ads: Google GAM (Simple)" ad block, and place the ad block on the page where you want the ad to show. So for every ad unit in GAM, 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 GAM, and the ad block will pull in the GAM 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 GAM 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 GAM/BLOX integration is that we're simply attempting to match ad units. Whatever the ad unit is in GAM, BLOX needs to match. 

With the URL based approach, we take advantage of block inheritance, and require that your GAM ad units are formatted like your BLOX site's URLs. 

Example ad unit: domain.com/news

The URL based approach for pulling in GAM ads into BLOX is to create an ad block that matches your GAM account type; either a "Ads: Google GAM (SB)" (small business) or "Ads: Google GAM (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 GAM 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 GAM ad unit and size information when BLOX calls/queries GAM:

  • Network Code: the ad unit call starts with the network code (your Network Code can be found in the top right corner of your GAM admin)
    Example GAM code generated: <data-GAM-adunit="/1234">

  • Include Domain: the ad unit name can include the domain, and is often a good idea, in the instance where your GAM 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 GAM code generated: <data-GAM-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 GAM. These blocks rely on the requirement that the GAM 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 GAM code generated: <data-GAM-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 GAM code generated: <data-GAM-adunit="/1234/domain.com/news/index">

  • Sizes: The size is required for GAM to know which GAM line items and creatives can serve, and is added after the ad unit code.
    Example GAM code generated: <data-GAM-adunit="/1234/domain.com/news/" data-GAM-size="[729,90]">

  • Include a Custom Targeting keyword (pos): While GAM supports custom "Key-values", the only targeting key that BLOX currently supports is "pos". Within GAM, 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 GAM code generated: <data-GAM-adunit="/1234/domain.com/news" data-GAM-size="[728,90]" data-GAM-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 GAM's pos values. 

Bulk Importing BLOX URL's as GAM Ad Units

When using GAM 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 GAM 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 GAM. 


Note:  As of June 2016, Google GAM 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 "GAM 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 GAM.  See GAM Release Notes. Our Templates have been updated to accomodate the change with GAM.


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 GAM templates that will work with Flex and are responsive, with “friendly iframe” technology (that works with async): http://help.bloxcms.com/app/gam_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 GAM: https://support.google.com/gam_premium/answer/1138308?hl=en

How To Hide Ads While Avoiding False Impressions

Usually, hiding a Google GAM 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 GAM’s terms of use. In addition, if the site is paying for Google GAM Premium, they would have to pay for those ad impressions that are never seen.

With our new BLOX Flex integration with Google GAM, 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 GAM 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 GAM, 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 GAM 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/gam_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 GAM Ads in BLOX

There are two options to enable viewing of GAM 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