Overview
This document explains the integration between BLOX Flex (responsive design) templates and Google Ad Manager (GAM).
To simplify the integration between BLOX and 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..
Setup Options
Simple Ad Block
The most simplistic approach for pulling in GAM ads into BLOX is to create the "Ads: Google Ad Manager (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.
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.
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.
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.
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.
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">
- 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.
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:
- 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.
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).
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.
- Within GAM, 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 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:
The Chrome extension shows overlays on ads, to identify network ID and ad unit, line item and creative information.
Google Publisher Console
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:
