How to use Key-value Targeting in Google Ad Manager

Google Ad Manager (GAM) is one of the most widespread and well-known Ad Servers in ad tech. While it does a good job of targeting its audience in general, publishers can utilize it even better by using key-value targeting. This functionality is used for inventory management, enriched reporting, and specific targeting of ads to users, webpages, and ad slots. Personalized targeting ensures brands are exposed to the right audience, and advertisers are willing to pay a premium for this. Furthermore, key-value targeting provides users with less intrusive ads that are relevant to both the web page they are visiting and their personal preferences.

What are Key-values in Google Ad Manager?

Publishers can specify custom targeting criteria for their ad slots in Google Ad Manager (GAM) via a feature called Key-value targeting. This helps advertisers reach their intended audience and increases the value of your inventory. Key-values can be used to identify pages on a website, specify parts of a page, and help target other ad inventory. One way to go about this is for publishers to analyze their audience characteristics, such as age, location, and so on, and base key values on this information. When a line item is set to target a key value, ads selected to be served on your website will always match it. 

Predefined & Dynamic Key-values

Depending on your targeting intention, you can choose between two types of key-values within Google Ad Manager: predefined key-values and dynamic key-values.

Predefined key-values are static, they don’t change according to the information of a particular user. They are appropriate when you know the possible range of values. A typical example of a predefined key would be “age”, and the values can be set in ranges such as 18-35, 36-65, etc. When creating a new line item, you can now select “age” as the key, and then choose a range you would like to target. The key-value is hard-coded in the ad tag. 

Dynamic key-values (previously called free-form key-values), on the other hand, allow publishers to pass targeting values dynamically into an ad tag based on information gathered about your audience. They are appropriate to use when the values for your ‘key’ are changing, unknown, or simply too many to define efficiently. The typical example here would be search terms your website visitors use when browsing your website. This feature allows you to target thousands of targeting values without having to predefine them. Publishers can choose to target variations of key values that can be defined as broad or as narrow as you prefer, allowing you to create advanced custom ad units. Below are the available match types in GAM:

  • Exact match: If you don’t add any special modifiers to a targeted value, the user search must match it exactly. Let’s take [phone] for example. With exact match, values such as [telephone] or [phones] won’t match. 
  • “Begins with” match: Use an asterisk (*) at the end of a value to match items that begin with the value but have additional characters at the end. For example, [phone*] would match values such as [phones] and [phone you are using], but not [telephone].  
  • “Include” match: Use a tilde (~) at the beginning of a value to include values that have the entire word in them, in any location. For example, [~phone] would match values like [samsung phone] and [phone number], but not [phones you are using].
  • “Begins with” and “Include” match: You can use both a tilde and an asterisk on a value. The “begins with” part of the value can now appear anywhere in the value, not just at the beginning. For example, [~phone*] would match values like [phones], [old phone] and [your favorite phones to use].  
  • Values with spaces: When you’re using match types, spaces are treated as characters within the value. For example, [phone number*] would match [phone numbers] but not [phoned numbers].

Key-value Formatting Rules

Valid key values need to be entered according to Google’s formatting restrictions. Here are the rules you need to follow:

  • Both keys and values cannot be case-sensitive.
  • Key names must not start with a number. Values can start with a number, be only numbers, or a combination of numbers and letters.
  • Key names must not contain any spaces. Values can.
  • Values are treated as strings even if they are numbers, meaning that numbers cannot be evaluated or calculated. For example, age>=18 AND age<=35 is not valid and must be entered as age=18-35.
  • The following characters must not be used in neither keys, nor values: “ (double quotes), ‘ (single quotes or apostrophe), = (equal sign), ! (exclamation point), + (plus sign), # (pound or hash symbol), * (asterisk), ~ (tilde), ; (semicolon), ^ (caret), () (parentheses), < > (angle brackets), [ ] (square brackets), , (comma), & (ampersand).

How to set up Key-values and target specific pages and ad slots in GAM?

Publishers can target ads to specific pages or ad slots within a site via key values. Let’s see what you should do:

Add your key-values in GAM.

  1. Go to Inventory > Key values > New key value
  2. Enter a key and check the ad tag to make sure it matches the key there.
  3. Enter a display name, which is used by the trafficker in GAM when targeting specific line items.
  4. Choose the key-value type: predefined or dynamic.
  5. Go to Report on values and choose Yes if you want the keys to appear in your GAM reports.
  6. Enter the values for the key. Separate them by line breaks. When you are ready, click Save.

Add key-values to the ad requests.

At this step, publishers can define if they want to target at the page level or at the ad slot level. You can pass one or more keys, each with one or more associated values, for each ad request. These key values will be compared to targeting choices set up in Ad Manager at the line item level. 

Page-level targeting allows you to set the same key values across all ad slots on your page. For example, you may want to target specific sections on your site, such as your news section. You can assign value “news” to pages that fit within that category and when targeting it in the line item, it will target all ad units on those pages. Use the function googletag.pubads().setTargeting () to utilize page-level targeting. 

Slot level targeting allows you to configure key values for individual ad slots on your page. For example, some advertisers may want to target only your premium inventory, such as those with the highest viewability. Use the function Slot.set.targeting() in such cases.

Below is an example by Google, which uses both types of targeting for a single ad slot. In such instances, the key-values are combined and only ads that satisfy all criteria are eligible to be served on such ad slots. 


  <script async src=””></script>


    window.googletag = window.googletag || {cmd: []};

    // GPT slots

    var adSlots = [];

    googletag.cmd.push(function() {

      // Configure slot-level targeting.

      adSlots[0] = googletag

          .defineSlot(‘/6355419/Travel/Asia’, [728, 90], ‘banner-ad-1’)


          .setTargeting(‘color’, ‘red’)

          .setTargeting(‘position’, ‘atf’);

      adSlots[1] = googletag

          .defineSlot(‘/6355419/Travel/Asia’, [728, 90], ‘banner-ad-2’)


          .setTargeting(‘position’, ‘btf’);

      // Configure page-level targeting.

      googletag.pubads().setTargeting(‘interests’, ‘basketball’);

      // Enable SRA and services.






Target key-values via line items.

  1. In GAM go to Delivery > Order. Select the line item that you want to target.
  2. Scroll down to Add Targeting and select Custom Targeting. 
  3. Select Key in the drop-down menu and enter the values for your key.

Key-values and system limits

Publishers need to adhere to GAM’s limits, which for your network can be viewed when you go to Admin > Global settings > Limits. Check them when planning on new key-values implementation so that you can make the best use of key-values targeting. 

Here are the general limits for each GAM network:

Active keys (predefined and dynamic): up to 200

Active key-value pairs: up to 2.5 million

Active values per key (predefined and dynamic): 100,000

Key-value reporting has some additional limits:

Reportable key-values: 30,000

Custom dimensions: 10

Custom dimension key-values: 5,000 for GAM (20,000 for GAM 360). These are calculated by multiplying the number of values in each custom dimension key. Google’s example is with Key A of 10 values, Key B of 15 values, and Key C of 20 values. When multiplied (10x15x20) they reach 3000, which is more restrictive than it seems at first glance of the system limits.

Reporting on Key-values

You can use the Key-values dimension to report on key-values, select which keys to include in reports, transform your most important keys into custom dimensions, and see when key-value reporting settings were changed.

Create “custom dimensions” from frequently used predefined keys, which you can then select when creating reports. Data for custom dimensions is displayed in reports only if the custom dimension key’s predefined value was explicitly included in the request. Only impressions captured after the addition of a custom dimension are included in reports that make use of the custom dimension.

How to transform “predefined” keys into custom dimensions:

  1. In GAM, go to Inventory > Key-values.
  2. Click on the name of the key to be used in reports.
  3. Under “Report on values” click “Include values in reporting & add key as custom dimension”
  4. Add the targeting values that you want to see in Ad Manager reports and click Save.

How to report on custom dimensions:

  1. In GAM, go to Reporting > Reports > New report.
  2. Click Custom Dimensions in the “Dimensions” section.
  3. Click the name of one or more keys that you’ve added as a custom dimension.
  4. Add the remaining report settings.

Wrap up

Although key values can be used in a variety of ways, the concept itself is simple. By carefully planning your use of Keys and Values, you can make Google Ad Manager more powerful and generate more insightful reports.