Google Ad Manager
Author: Anete Jodzevica 18 minute read
All Categories >Google Ad Manager > Key-Value Targeting in Google Ad Manager – a Guide for Publishers

Key-Value Targeting in Google Ad Manager – a Guide for Publishers

Key-value targeting is a feature offered in Google Ad Manager (GAM), which is used for inventory management, reporting, and specific targeting of ads to users, webpages, and ad slots. 

Key-value targeting can help publishers to increase the value of their ad inventory and improve the relevance of the ads displayed on their website, which can lead to higher engagement rates and increased revenue.

In this article, we will explain what key-values are, what are their types, and how to use them to optimize your ad campaigns! 

What is Key-Value Targeting?

Key-value targeting is a feature in Google Ad Manager (GAM) that enables publishers to define custom targeting criteria, organize inventory, improve reporting, and target ads to a specific audience, page, and ad slots. 

It helps advertisers to reach their desired audience and increase publisher’s inventory value. 

There are 3 main purposes of key-value targeting:

  • Identifying pages on a website.
  • Specifying page sections.
  • Helping to target other ad inventory. 

Key-values based on the information you’ve gathered about website visitors. Publishers typically select the key-values by analyzing visitor data (e.g., location, age, interests).

When an ad request comes in from your website or an app with key-values in its ad tags, line items targeting those key-values are eligible to serve for that ad request. 

Other targeting methods

Here are 5 common targeting methods: 

  1. Contextual targeting–ensures that ads are displayed alongside relevant content on a website or app. 
  1. Audience targeting–enables publishers to provide advertisers with access to their audience data, which can help them create more precise and effective ad campaigns. 
  1. Location targeting–allows to target users in specific geographic regions.
  1. Device targeting–targets users on specific types of devices, such as mobile or desktop. 
  1. Frequency capping–limits the number of times an ad will be exposed to a user. The main goal is to avoid showing the same ad to the same user too many times. 

What are Key-values in GAM?

Key-values are the extra parameters that help to define custom targeting in ad requests. They’re used in the targeting picker and are included in ad tags. 

When you think about which key-values you’d like to set up, you should evaluate them. 

Determine which keys would be valuable to your objectives. Think about the data that your advertisers want to know and whether it’s compatible with the information you already have on your users and content. 

For example, if an advertiser wants to reach news readers within the 25-35 age range, you can create two keys–“page” and “age”, and add the appropriate values. 

Why use key-values?

Here are 4 reasons to use key-values:

  • They help to reach desired audience.
  • They add value to your offerings when negotiating campaigns. 
  • They help to better understand the value of your inventory. 
  • They help to develop new advertising partnerships.

When you have key-value data collected, you’ll be able to run reports and forecast on key-value data to tell buyers how much traffic you expect to see in the coming months based on their targeting criteria. 

This is beneficial to engage your visitors in becoming a loyal audience, and optimize the ads you serve based on key value targeting.

Key-value pair types

Key-value pairs can be used to target ad inventory and identify context, but they serve publishers best when they’re based on demographic data and used in combination with reporting to develop effective ad targeting strategies.

Google Ad Manager offers two types of key-values:

  • Dynamic.
  • Predefined.

Each of them will be further described below.

Predefined key-values

Predefined key-values are static. They’re suitable when you know the possible range of potential values. 

For example, a predefined key value is age. You can create a key-value and enter the age range (e.g., 18-25, 25-35, etc.)

Afterward, when creating a line item, you can select the age key-value and the range you want to target. 

Predefined key-values are hard-coded in the ad tag.

Dynamic (Freeform) key-values

Dynamic key-values, previously known as free-form key-values, are used when you need to pass values to the ad tag dynamically. 

They’re suitable when your key-values are changing, unknown, or can’t be defined efficiently. 

For example, dynamic key-values are appropriate when targeting search terms visitors use when browsing your website. 

Therefore, you can target thousands of targeting values without predefining them.

The publisher needs to define the key-value in advance. Then these values can be dynamically passed while collecting user information through ad requests into the ad tags. 

Key-value Formatting Rules

Publishers need to follow GAM’s limits. To see the limits for your network you need to: 

  • Go to “Admin”, then “Global settings”, and click on “Limits”.

 In the table below you can see the general limits for each GAM network:

Active keysUp to 200
Active key-value pairs2.5 million
Active values per key100,000
Reportable key-values30,000
Custom dimensions10
Custom dimension key-values5,000 for GAM (free)
20,000 for GAM 360 (premium)

Key-value Match Types

Exact match

Exact match means that without adding special modifiers to a targeted value, the user’s search must match it exactly.


  • Target value (only match): blog
  • Doesn’t match: blogger and blogging 

Suppose your target value is “blog”. In this case it’s the only possible match.

Such variations like “blogger” and “blogging” won’t be included.

“Begins with” match

Adding an asterisk (*) at the end of a value matches items that begin with the value but have additional characters at the end.


  • Target value: blog*
  • Match: blog, blogger, blog creation
  • Doesn’t match: new blog, a blog

“Include” match:

Adding a tilde (~) at the beginning of a value to include values with the entire word in them placed in any location.


  • Target value: ~blog
  • Match: blog creation, sports blog
  • Doesn’t match: blogger, blogging tips

“Begins with” and “Include” match:

When you use a tilde (~) and an asterisk (*), the “begins with” part of the value can now appear anywhere.


  • Target value: ~blog*
  • Match: blogger, new blog, blogging tips

Values with spaces: 

When you include the “space bar”, it’s treated as a character within the value.


  • Target value: new blog*
  • Match: new blogs, new blogger
  • Doesn’t match: newest blog

How to Set Up Key-Value Targeting in Google Ad Manager?

How to add keys to your network?

Here are 7 steps that show how to add keys to your network:

  1. On the GAM home page, navigate to “Inventory”, then “Key-values”, and click on “New Key-value.”
  1. Choose a name for the key and a display name (optional). The display name is visible to the traffickers when they target the key-values. For example, if your key name is “b” and the display name is “blog”, the trafficker will see “blog” as the key name.

The “Name” is the text that’s used in ad tags. The name you enter may appear in an ad request URL, which can be seen by people visiting your website or app if they inspect the ad request. 

The “Display name” is what traffickers see in the targeting picker when adding custom targeting line items, proposal line items, or other items in GAM.

  1. Select a “Value type” (dynamic or predefined). 
  1. Go to the “Report on values” and choose your requirements. 
  1. Go to “Targeting values” and click “New values.”
  1. Enter the values for the key separated by whitespace. You can enter 200 values per line item with a free GAM account. If you want to add more, you need to upgrade to a Google Ad Manager 360 account.
  1. Save the key-values. 

How to add values to your network?

You can save a key without adding values. However, a key will only be serviceable once you define values. 

First, you need to enter the value name, and then its display name. 

  1. Navigate to “Inventory,” then “Key-values.”
  1. Find the key to which you want to add values and go to its details page.
  1. Click “New values.”
  1. Enter one or multiple values.

Adding Key-values to GPT

With keys defined you need to then pass some value data into GAM to use those key-values. This can be done through the Google Publisher Tag on page, using the “setTargeting” function.

When passing values into GAM you can either have that value associated with just the requests made by a particular ad slot, or to all the requests on the current page.

Publishers can define if they want to target at the page level or at the ad slot level. For each ad request, you can pass one or more keys (each with one or more associated values).

These key values will be compared to targeting choices set up in GAM at the line item level.

Page-level value examplesSlot-level value examples
page-type = news
source = facebook
user = loggedin
position = topright
fold = atf
Placement-type = in-content

Slot-level Targeting

To target ad slots, you can create a key-value (e.g., “position”) and assign values based on how you plan to organize your ad inventory (e.g., sidebar).

Slot-level targeting allows you to configure key-values for individual ad slots on your page. 

Once you add the key value in the ad tags, you can start targeting line items to ad slots. This can be beneficial when you want to bundle your above-the-fold inventory and sell it at a premium price. 

For example, if you have premium CPM rates for above-the-fold ads and want to place targeted ads to the specific ad slots. 

You need to create a key–”position”–with the values–”right-box”, “top”, and “bottom”. 

Adding this key-value combination to the ad requests will make GAM serve ads on these placements.

In simple words, slot-level targeting is set when the ad slot itself is defined. It’s most useful when passing values that relate to requests served into that, such as it’s position on a page or a viewability prediction.

Page-level Targeting

Page-level targeting enables to set the same key values across all ad slots on a page. To target pages, you should create a unique dynamic key-value (e.g., “pageID=123”). 

Key-value is a secondary dimension that you can use to create a structure for your ad inventory without creating hundreds of independent ad units to achieve the same result.

For example, you may want to target specific sections on your site, such as the news section. 

You can assign the 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. 

Page level targeting is set in the header portion of the GPT code and is automatically then passed into all ad requests made on that page. 

This is a good choice when you want to pass details of the user or the page itself, such as the gender of a registered user of the website category they are viewing.

Target key-values through line items

Once you’ve set-up your key-values, you can use them as custom targeting options in your GAM account. 

  1. Go to GAM home page. 
  1. Click on “Delivery”, then “Order”.
  1. Select the line item that you want to target.
  1. Navigate to the “Add Targeting” section and select “Custom Targeting”.
  1. Select “Key” in the drop-down menu, and enter the corresponding values

How to Set Up Custom Reporting with Key-values?

You can use the key-value dimensions to report on key-values, choose which keys to include in reports, turn your most essential keys into custom dimensions, and track changes to the key-value reporting settings.

To include key-values in GAM reports, you need to mark them as “reportable.” 

To do this, you need to take these 5 steps:

  1. Sign in to GAM.
  1. Click on “Inventory,” then “Key-values.”
  1. Click the name of a key you want to use in GAM reports.
  1. Under “Report on values,” choose “Include values in reporting.”
  1. Click “Save.”

You can report on values using the key values dimension. Select the keys you want to include in reports, transform your most important keys into custom dimensions, and see when reporting settings for keys were changed. 

Key values are associated to an ad slot request.

To run a report you need to take these 6 steps: 

  1. Go to “Reports”, then “New report”.
  1. Select “Historical” as the report type. 
  1. Select your general settings, name your report, and choose the time zone and the date range.

For the date range you can set a relative or dynamic date range, a fixed start and end date range or a custom date range. You can also add in filters, which narrow report results. 

It’s beneficial to select dimensions and metrics before adding filters to restrict the results.

  1. In the “Dimensions” section, you can click on “Inventory” and select “Key-values”.
  1. Select the “Ad server targeted impressions” and “Ad server impressions” to differentiate between targeted and un-targeted impressions. 

You can also select additional settings, such as add editors or schedule the report to run at a future date. You can select scheduling criteria to generate a report on a recurrent basis. 

  1. Click “Run”. 

You’ll see your key-value report, and it will list the key-values that you have active and show the ad server impressions and ad server targeted impressions per value. 

This report enables you to understand which key values perform best, and add in more granular values if necessary.

Key-Value Targeting and Programmatic Advertising

Key-value targeting is crucial to programmatic advertising because it enables publishers to provide advertisers with more granular targeting options. 

Programmatic advertising relies on automated systems to buy and sell ad inventory in real-time. Key-value targeting can help publishers make their ad inventory more attractive to advertisers by providing them with more precise targeting options. 

In programmatic advertising, advertisers use demand-side platforms (DSPs) to bid on ad inventory that matches their targeting criteria. By providing DSPs with key-value targeting options, publishers can increase the chance that their ad inventory will match the right advertisers, which can help them earn higher ad revenue.

Key-value targeting also allows publishers to give advertisers more transparency and control over their ad campaigns. 

By offering specific key-values, publishers can give advertisers more insight into the context of their ad placements and help them better understand where their ads appear.


Google Ad Manager is one of the most popular ad servers in the digital space. It does a great job of targeting its audience, but key-value targeting improves it even more.

By carefully planning your use of keys and values, you can make GAM more effective and generate insightful reports. Once you get around the basics, passing key-values to ad requests becomes a simple and effective way to target specific users and increase your ad revenue.

If you need help or have any questions, message us at [email protected]!


What is key-value targeting, and how does it work?

Key-value targeting is a feature in Google Ad Manager (GAM) that enables publishers to define custom targeting criteria, organize inventory, improve reporting, and target ads to a specific audience, page, and ad slots. 

How can I create custom key values in Google Ad Manager?

First, you need to go to the GAM home page, then click on “Inventory”, navigate to “Key Values”, and click on “New Key-value”. Enter the key and ensure that it matches the key in the ad tags. Fill out the additional details.

Can I use key-value targeting with other targeting options in Google Ad Manager?

You can use custom targeting in GAM. Custom targeting includes key-values, audience segments, or content metadata. 

What are the benefits of using key-value targeting in programmatic advertising?

The main benefits of key-value targeting include efficient inventory management and improved reporting capability. 

It also enables to target ads to specific users, webpages, and ad slots, which can increase the ad inventory value and improve the relevance of the ads displayed on the website.

How can I optimize key-value targeting for better performance?

Make sure to include important key-values in reports and check them regularly. You can improve performance by employing key-value targeting and regular reporting, and ensure that your content matches the right users.

About Anete Jodzevica
Anete is a content marketing specialist at Setupad. In addition to writing articles, she works at gathering information, verifying data, and explaining complex concepts to others. Anete believes that simplicity is the key to brilliance.

message icon message icon big