Set targeting and sizes with GPT

Watch related Publisher University training (Part 1)

Watch related Publisher University training (Part 2)

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.

Specify creative sizes in the googletag.defineSlot() function. To allow multiple sizes to serve to the ad slot, you can use a comma-separated list. You can see examples of this here. 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. Learn more

Use key-value targeting with GPT

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

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 use the setTargeting() function to pass one or more keys, each with one or more values. For each ad call, 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. Use .setTargeting to utilize slot-level targeting, as in the Google Publisher Tag samples.

    Typically, 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. Use googletag.pubads().setTargeting to utilize page-level targeting, as in the Google Publisher Tag samples.

    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=m 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 (written as .setTargeting('gender', 'male');) into a tag, line items targeted to gender = male will be eligible to serve, assuming all other criteria matches.

Target multiple attributes or values with one key

You can target multiple attributes or associate multiple targeting values with one key, using the guidance below or viewing the full Google Publisher Tag samples.

For slot-level or page-level key-value targeting

To define more than one key-value attribute, you can call setTargeting multiple times:

     .setTargeting('gender', 'male')

     .setTargeting('age", '20-30');

To associate multiple values with one key, use the following format:

     ('key', ['value1', 'value2', 'value3'])

Note that when key-values is configured using page-level key-values, all ad slots will inherit the key-values.

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.

See an example of a GPT tag passing key-values
  <script async src="">
    window.googletag = window.googletag || {cmd: []};
    googletag.cmd.push(function() {
      var adSlot1 = googletag.defineSlot(
          '/6355419/Travel/Europe/France/Paris', [300, 250], 'banner1');
      adSlot1.setTargeting('position', ['atf']);
      var adSlot2 = googletag.defineSlot(
          '/6355419/Travel/Europe/France/Paris', [300, 250], 'banner2');
      adSlot2.setTargeting('position', ['btf']);
          'articletopic', 'basketball');  // Applies to all slots on the page

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 by 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're found in the GPT. 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. You can see examples of this here.

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, check the Out of page checkbox in the 'Generate tags' window.

Was this helpful?
How can we improve it?