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 GAM 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 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:
- There is a limit of 2 hierarchies per ad unit
- 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:
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.
Google Reference Sites
- GAM Premium Help Center: https://support.google.com/gam_premium
- GAM Small Business Help Center: https://support.google.com/gam_sb
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.
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.
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.
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.
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 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 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
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 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
?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:
- Per URL
Add ?preview_ads=true to the end of your preview URL
- Site Setting
Add ads_run_in_preview site setting