Table of Contents


Before starting this process, make sure you have completed the following: 

  1. Your BLOX site setup is complete, where your URLs will not change (or should only slightly change)
  2. You have a Google GAM Small Business account created (preferably with no ad units yet created)

Note: This process is for Google GAM Small Business accounts only. If you are using GAM Premium, the ad units are automatically generated and you do not need to bulk import them. 

Create "Ad Units" in Google GAM From URLs in BLOX

To simplify the relationship between BLOX and Google GAM Small Business, TownNews recommends using GAM's “Ad units” as the equivalent to BLOX URLs. Each URL on the BLOX site would be added to Google GAM as an ad unit. This set up gives sites extremely flexible targeting options, while allowing for ease-of-use at the same time.

To make the process of creating Ad Units in GAM easier, we created a special skin in BLOX that will generate a list of URLs, to be imported into GAM as ad units.

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.

Create a New BLOX URL Which Will Use The GAM Skin

  1. Create a new URL: GAM_ad_units
  2. Set the URL's skin to the following:
    • Application Skin: Guide: GAM SB Ad Units
  3. Save Changes
DFP skin

Update BLOX URL Page Customizations

  1. Access the new URL's page customizations (either by going to the URL in the URL map, or via Design > Blocks and open page customizations for that URL).
  2. Sizes: Enter a list of all your ad sizes that will exist on the entire site, one per line. It is important that all sizes are listed BEFORE the next step.
  3. Go to Design / Blocks, and open the GAM_AD_UNITS URL.  In Advertising under Page Customizations, enter your GAM account information.
  4. Include Domain: If your GAM setup will support multiple sites, it's best to check "Include domain", as this will allow you to sort and target ads on a per domain basis. If your GAM setup will only support one site, it's not required but we still recommend it as a best practice. 
  5. Include a Index/Homepage Slug: leave blank
DFP page customizations

After saving the settings above, you may notice that the main layout screen's message changes to include "Ok looks like we're setup for exporting. Press [Next]". Disregard this message, as the "Next" button is broken (a reported bug) and will be fixed or removed in a future release. 

Create "Ad Units" Spreadsheet

  1. Launch a preview of the site and add /GAM_ad_units to the end of the URL
  2. If everything is configured correctly, you should see a page showing instructions on how to create the CSV file. Follow the instructions to create the CSV file.

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:
Ex. of an ad unit with 3 hierarchies:
Ex. of an ad unit with 4 hierarchies:
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:

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
then /sports inside of

So what's the problem? 
When BLOX is expecting to match a GAM ad unit of, 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 .

DFP help text

Importing "Ad Units" Spreadsheet into Google GAM

  1. Within Google GAM's admin, go to Inventory / Ad Units
  2. Click Bulk Upload New Ad Units 
  3. Click Choose File, browse to find your new .csv file, and click Upload and Validate

Google will evaluate the file and may give warnings or errors. You'll need to fix those errors (duplicates need to be removed, blank line items need to be removed, etc.)

bulk upload ad units

Create "Placements" in Google GAM

Now that the ad units are uploaded, you'll want to create "placements", or groups of ad units, to make maintenance and targeting easier.  A placement may contain any ad units desired. For example, a "Sports" placement may contain ad units for /sports and all sub-URLs of Sports. 

If you are selling the index page (ex. main sports section page) and asset pages separately, you may want one placement to target the Sports section page, and another placement to target the Sports asset pages. 

Create a New Placement

  1. Go to Inventory / Placements
  2. Click New Placement
  3. Name: (what you're targeting), ex. "Sports"
  4. Search for the ad units you want to include and click Include to add each ad unit (BLOX URL) for the placement
  5. Uncheck Google AdWords (recommended if not using placement targeting Google's AdWords Advertisers)
  6. Click Save
DFP placements

Create "Custom Targeting" in Google GAM

In this setup, we are using custom targeting in order to target specific ad locations on a page. BLOX is utilizing a targeting value of "pos" (stands for "position"), as a custom targeting variable.

Create a New Custom Targeting Value Key

  1. Go to Inventory / Custom Targeting
  2. Click New Key
  3. Name: enter pos
  4. Values type: select Users Will Select From Predefined Targeting Values
    (This option is useful so that users don't have to remember or type in the various position codes)
DFP custom targeting
  1. Click Add Values
  2. If using BLOX Fixed Ad units, enter values that match fixed ad region names that you plan to use
  3. Click here for more information on Fixed ad region names
  4. If using BLOX Ad Blocks, enter values that match block ad region names (ex. block-leaderboard-top, block-leaderboard-top-mobile), OR values that make sense to your organization (ex. "right1_atf_300x250", "leaderboard-top_728x90", etc.)
  5. Click Apply
DFP custom targeting

Custom Targeting By Page

When you create an ad order you can now target the ad based on the custom criteria set up in GAM. Templates will now automatically generate a GAM custom targeting key with values depending on the page you are on:

  • / - homepage
  • section front - index
  • asset page - asset
  • editorial page - app-editorial
  • calendar page - app-calendar
  • 404 page - 404

These key-value pairs can be targeted in GAM by setting up custom targeting in Inventory / Custom Targeting.  Add the key of page.  Then add the values above.

Duplicate "Line Items" in Google GAM

Google GAM's Line item is similar to a single element of an order. An "Order" in GAM is a collection of line items.  

Ex. The advertiser for an order might be Apple Inc. The order itself might be an iPad campaign. Each line item might be for a different iPad product (iPad 2, iPad Mini, iPad Air, etc.)

In order for ads to move to the new system with minimal downtime, we recommend duplicating your line items, and within the duplicates, removing old ad unit, placement and custom criteria information, and adding new ones. 

NOTE: This step is only required for sites already using GAM. If you have a new installation of GAM, skip this step. Adding a "pos" custom target to an existing order (when a custom target is not used in the current system) will cause the existing ads to go offline. 

Duplicate Line Item

  1. Go to Orders / Line items
  2. Check the boxes next to the line items you need to duplicate (NOTE: you can duplicate multiple line items at once as long as the Advertiser is the same)
  3. Above the list of line items, click More Actions, and select Copy to...
  4. Select a copy option: Copy Line Item and Creatives
  5. The line items will be copied to: The Same Order
  6. Click Ok

Update The Duplicate (Copy) Line Item

  1. Click on the duplicate line item
  2. In the Add Targeting section at the bottom of the page, remove Ad units, Placements and custom criteria (if applicable)
  3. Include new Ad units, Placements and/or custom criteria

How Do I create "ROS" (Run of Site) Ads? 

When creating a new line item in GAM, the Ad units will default to "Run of network". Because the ad units imported from BLOX URLs consist of the full domain name as part of the ad unit, a placement (group of ad units) which targets all URLs of the site is recommended.  

DFP ad targeting ROS

Troubleshooting Tips 

Google 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 

For example, if your page is located at, you'd modify the URL to

Google Console

Troubleshooting Fixed Ad Positions

By clicking on the (?) icon in the top right corner of any fixed ad position in the Blocks admin, you will be presented with the information that the particular ad is looking for in terms of the ad unit and the "pos" custom targeting value(s). 

The code created by GAM will need to match in order to show the ad. 

As you change page customization settings under "Advertising", the help text will update to reflect what the ad position is expecting. 

DFP fixed help