Key-value targeting

Key-values can be used to target ads more granularly than ad units. Learn more about key-values.

For each ad request, you may pass one or more keys, each with one or more associated values. These key-values will be evaluated against targeting options configured at the line item-level in Ad Manager. For example, if you pass a custom key-value of age=18-34, line items targeted to the age range 18-34 will be eligible to serve, assuming all other criteria matches.

Set targeting

You may specify key-values to configure targeting at both the slot- and page-level based on your network’s needs.

Slot-level

Allows you to set key-values for individual ad slots on your page.

Slot-level targeting allows you to configure targeting on a per-slot basis. This is useful in cases where individual slots on the same page require different targeting, but can be inefficient in situations where the same key-values are applied to all slots. Use Slot.setTargeting() to utilize slot-level targeting, as in the example below.

Page-level

Allows you to set key-values across all ad slots on your page.

Page-level targeting ensures that all ad slots have the same set of key-values. In some cases this may reduce the total amount of code needed to configure targeting. Use googletag.pubads().setTargeting() to utilize page-level targeting, as in the example below.

<head>
  <script async src="https://securepubads.g.doubleclick.net/tag/js/gpt.js">
  </script>
  <script>
    window.googletag = window.googletag || {cmd: []};

    googletag.cmd.push(function() {
      // Slot-level targeting.
      var adSlot1 = googletag
          .defineSlot('/6355419/Travel/Europe/France/Paris', [300, 250], 'banner1')
          .addService(googletag.pubads())
          .setTargeting('position', 'atf');
      var adSlot2 = googletag
          .defineSlot('/6355419/Travel/Europe/France/Paris', [300, 250], 'banner2')
          .addService(googletag.pubads())
          .setTargeting('position', 'btf');

      // Page-level targeting.
      googletag.pubads().setTargeting('interests', 'basketball');

      googletag.enableServices();
    });
  </script>
</head>

In this example, two ad slots are defined which specify ad unit /6355419/Travel/Europe/France/Paris and ad size 300x250. Then key-value targeting is applied to further restrict and differentiate the ads which may serve in each slot.

Note that when both slot- and page-level targeting are used, the key-values are combined and only ads satisfying all criteria will be eligible to serve to a given slot. In this example, the effective tageting for each slot is:

Ad slot Effective targeting
1 position=atf AND interests=basketball
2 position=btf AND interests=basketball

Target multiple keys or values

In the above example, a combination of slot- and page-level targeting was used to define multiple targeting keys for a single ad slot. This could have also been accomplished by calling setTargeting() multiple times for each slot:

// Slot-level targeting with multiple keys.
var adSlot1 = googletag
    .defineSlot('/6355419/Travel/Europe/France/Paris', [300, 250], 'banner1')
    .addService(googletag.pubads())
    .setTargeting('position', 'atf')
    .setTargeting('interests', 'basketball');
var adSlot2 = googletag
    .defineSlot('/6355419/Travel/Europe/France/Paris', [300, 250], 'banner2')
    .addService(googletag.pubads())
    .setTargeting('position', 'btf')
    .setTargeting('interests', 'basketball');

It's also possible to target multiple values for a single key by providing an array of values when calling setTargeting():

// Page-level targeting with multiple values for a single key.
googletag.pubads().setTargeting('interests', ['baseball', 'basketball']);

Clear targeting

Once targeting has been set, the congfigured key-values will be sent with every ad request for the life of the ad slot. In some circumstances, however, it may be desirable for targeting to change over time. While setTargeting() can be used to add and overwrite key-values, it's not possible to remove them this way. To accomplish that, Slot.clearTargeting() or googletag.pubads().clearTargeting() must be used instead:

// Step 1, define slot- and page-level targeting.
var adSlot1 = googletag
    .defineSlot('/6355419/Travel/Europe/France/Paris', [300, 250], 'banner1')
    .addService(googletag.pubads())
    .setTargeting('color', 'red')
    .setTargeting('position', 'atf');

googletag.pubads().setTargeting('interests', 'basketball');

// Step 2, clear slot-level color targeting.
adSlot1.clearTargeting('color');

// Step 3, clear all page-level targeting.
googletag.pubads().clearTargeting();

When clearTargeting() is called with a specific key (either at the slot- or page- level), only that key is removed. When no key is specified, all targeting at that level is removed.

In the above example, the effective targeting for ad slot 1 after each step is:

Step Effective targeting
1 color=red AND position=atf AND interests=basketball
2 position=atf AND interests=basketball
3 position=atf