Build Google Publisher Tags

Set targeting and sizes with GPT

Specify ad units with GPT

For each ad slot, you can specify an ad unit so that line items targeted to that ad unit, or to placements containing that ad unit, will be eligible to serve to that tag.

You can learn more about the Ad Manager inventory structure, ad unit hierarchy, and how ad units inherit targeting in the inventory overview.

Specify ad sizes with GPT

You must specify in your tags which creative sizes can serve to each ad slot.

For single-size ad slots, you also have the option of defining the size of the <div> element where the creative will render; this prevents other elements on your page from shifting if the creative renders asynchronously, after elements following the <div> element have loaded. To allow multiple sizes to serve to the ad slot, use a comma-separated list.

There is no limit to the number of sizes you can include, though the request URL has a character limit, depending on the tag type.

Read the Developer Documentation

Use key-value targeting with GPT

You can use key-values to target ads more granularly than ad units..

Please use key-value targeting with care.

Under the terms of your contract, you must not pass any information that Ad Manager could use or recognize as personally identifiable.

For each ad call, you can pass one or more keys, each with one or more values.You can either use slot-level or page-level customized targeting parameters based on your network’s needs, as below:

  • Slot-level customized targeting: You can set key-value attributes for individual ad slots on your page.

    We recommend using slot-level implementation for customized targeting, as it covers all targeting scenarios (both when the key-values is the same throughout the page, and when it varies by individual slots).

  • Page-level customized targeting: You can use this to set custom attributes across all ad slots on your page.

    Page-level targeting allows clients to use less code in their tags and ensures that all ad slots have the same set of key-value attributes. For example, clients could set the key-value pair gender = male on all ad slots using page-level customized targeting.

Passing key-values into a tag allows line items targeted to that key and value pair to serve to that tag. For example, if you pass the custom key-value of gender = male into a tag, line items targeted to gender = male will be eligible to serve, assuming all other criteria matches.

Read the Developer Documentation

Rules and limitations around key-values in GPT ad tags

Keep the following guidelines in mind when inserting key-values into GPT ad tags:

  • The key must not begin with a number.

  • The keys of key-values cannot contain spaces or any of the following special characters: " ' , = ! + # * ~ ; ^ ( ) < > [ ]

  • The values of key-values cannot contain any of the following special characters: " ' , = ! + # * ~ ; ^ ( ) < > [ ] 

  • Spaces are allowed in key-values. For example: .setTargeting('region', ['middle east', 'southeast asia']);

  • There is no limit to the number of key-values you can include, though the request URL has a character limit, depending on the tag type. Learn more

Characters can be unsafe for a number of reasons, some of which are mentioned below:

  • The characters ? : @ have a special purpose in HTTP URLs and will break the ad request if you include them in key-values.

  • The characters ; / & are reserved for special meanings within Ad Manager ad tags and can be used only for those purposes.

  • A quotation mark (") is used to delimit URLs.

  • The character # is used to delimit a URL from a fragment/anchor identifier that might follow it.

  • The character % is used for encodings of other characters.

  • Other characters such as { } | ^ ~ [ ] \ are unsafe because when they are sent in URLs via the web, gateways and other transport agents sometimes modify such characters.

  • The value of a key-value cannot be empty (for example, cat= or cat=" " or cat=' '). However, where there are instances where the value is intentionally blank, populate the value with null or some other value indicating a blank (for example, cat=null).

  • Key-values are not case sensitive. There is no distinction between words entered in lowercase and uppercase.

Slot definition and sequentiality of ad selection

Sequentiality is important to consider when tagging pages with multiple ad slots.*

For pages using GPT with multiple size ad slots, the slot definitions in the header should be declared according to the order they should be filled as this may be used to inform Ad Manager ad selection.

Define ad slots for sequential ad selection

Imagine the creative delivery for line item above is set to All and targeted to a page using GPT with the ad slots declared in the following order:

    '/1234567/travel', [[300, 600], [300, 250]], 'div-gpt-ad-1');

googletag.defineSlot('/1234567/travel', [300, 250], 'div-gpt-ad-2');
googletag.defineSlot('/1234567/travel', [728, 90], 'div-gpt-ad-3');

Using this definition, the slots are set up as follows:

Slot 1: [[300, 600], [300, 250]]

Slot 2: [300, 250]

Slot 3: [728, 90]

When Ad Manager receives the ad request, it tries to fit the creatives into the ad slots in the order they are found in the tag.

Ad Manager assigns the 300x250 creative to Slot 1, because it's the first matching creative listed in the line item. Ad Manager then looks for a creative for Slot 2, but none is available because the 300x250 pixel creative has already been used. Because of the sequential ad selection logic, Ad Manager determines that it cannot deliver all of the creatives in the line item, so it doesn't deliver any of them.

To ensure correct delivery to the page, the ad slots must be declared as follows:

googletag.defineSlot('/1234567/travel', [300, 250], 'div-gpt-ad-2');
    '/1234567/travel', [[300, 600], [300, 250]], 'div-gpt-ad-1');

googletag.defineSlot('/1234567/travel", [728, 90], 'div-gpt-ad-3');

*Sequentiality applies to all GPT usage and is not affected by line item type or priority.

Define <div> size to prevent elements from shifting when a creative renders

To define sizes, you should use the style attribute in the <div> elements that will hold the ads.

We recommend that this only be used for single-size ad requests. If you’re creating a multi-size ad request, you should set the height to the tallest creative and width to the widest creative in order to avoid creatives being inadvertently cropped.

Define an out-of-page slot

To specify an out-of-page ad slot, follow the Generate ad tags instructions. Check the "Out-of-page" checkbox in the Generate tags tab.

Was this helpful?
How can we improve it?