How to Get Started with Key-Value Targeting?

Updated on: December 28, 2023
"Key-value targeting" lets you show your ad to users based on values associated with the website or app visits.

Wouldn’t it be awesome if you could serve the right ads to the visitors with the help of your ad server, driving benefits for both sides? For advertisers, it provides better exposure to the right audience and, for you – enhanced yield. Moreover, if the ad is relevant to the users, they’ll find it less annoying than the out-of-nowhere ads that don’t match the page’s context. 

Google Ad Manager offers an advanced feature, i.e., key-value targeting, that allows you to place ads where you want more granularly. For instance, suppose you have an advertiser with a local restaurant who wants to show ads on article pages related to the food category.

With the help of key-values, you can serve ads from the advertiser on the pages with food content. Not just placing a targeted ad on a particular page, publishers can also serve ads on a specific ad slot via key-value targeting in Google Ad Manager. This guide will explain how key-value targeting works and how to set up the ad server’s line items.

What Are Key-values of Google Ad Manager?

Simply put, key-values are the custom parameters (attributes and associated values) that Google Ad Manager uses to identify a page, a portion of a page, or an ad inventory. Usually, publishers determine the key-values by analyzing the information gathered about the visitors, such as their location, age, interests, and more.

Via Google Ad Manager, a publisher can take advantage of two types of key-values:

  1. Predefined key-values, and
  2. Dynamic key-values (formerly known as “Free Form”).

Predefined key-values are used when the range of values is limited and already known to the publisher. For example, you can use Predefined key-values when you want to target an audience aged 18-35. Here, the key is “age,” while the value is “18-35”.

On the contrary, when the values for the attribute are not well-known or can’t be standardized, you need to use Dynamic key-values. Although the publisher needs to define the attribute (key) in advance, the values can be passed dynamically while collecting user information via ad requests into the ad tags. 

Tip: A Predefined key can be transformed into a “custom dimension” and then included in the Google Ad Manager reports to view the ad performance based on demographics, ad positions, and other custom parameters.

These days, publishers prefer Dynamic key values, enabling them to create key-value pairs unique to the site and target thousands of users without restrictions. Besides, there is one more advantage of using Dynamic key values, i.e., the availability of match types in Google Ad Manager. Publishers can match values to the key as broad or as granular as they want using the following types:

“Begins with” match – For this match type, you must add “*” at the end of the value, e.g., volleyball*.

“Include” match – Use “~” at the beginning of the value, for example, ~volleyball.

“Begins with” and “Include” match – For this type, you must add “~” at the beginning and “*” at the end of the value. For example, ~volleyball*. This will match values like volleyball matches, volleyball players, volleyball penalties, etc.

Exact match – There is no need to add any modifier for this type, and the value should exactly match. If the value is “volleyball”, then targeting will not be done for the “volleyballs” value.

“Values with spaces” match – Spaces are treated as characters in this type. If you enter a value “volleyball penalty*”, it will match with “volleyball penalties” but not with “volleyballs penalty”.

Image Source:

Since we are done with the terminologies related to key-value targeting, let’s understand their types with the help of a few examples:

  1. Ad slot-level targeting, and
  2. Page-level targeting. 

For the first case, ad slot-level targeting, let’s assume you have premium CPM rates for above-the-fold ads and you want to place targeted ads to the specific ad slots; then you need to create a key, e.g., “position” with the values, “right-box”, “top”, and “bottom”. Adding the key-value combination to the ad requests will make Google Ad Manager exclusively serve ads on the placements.

In the second type, i.e., page-level targeting, you want to target a group of specific pages based on the page’s ID; then you need to create a key, e.g., “pageID” with the values, e.g., “987654”, “123456,” and pass the values via ad requests to display ads on those selected pages. 

Now that you have understood what are key-values and the variations are let’s get to the technical aspect of this guide and see how to set up the key and value combinations in Google Ad Manager.

How to Setup Key-values and Target Specific Pages in Google Ad Manager?

When an ad tag with key-values is processed via the ad request, Google Ad Manager serves the ad from the eligible line items targeting those key-values on the website. Follow the three steps to target a specific page or an ad slot on your website.

Step #1: Add Key-values in Google Ad Manager

Follow the below steps to add new key-value pair to the server:

  • Go to the Google Ad Manager home page and click Inventory > Key-values > New Key-value.
  • Enter a name for the key and display name that will be used by the trafficker in Ad Manager when targeting the line items. This is an optional step, and the name provided here is visible to the traffickers when they target the key-values. For example, if you enter the key name “a” and enter the display name as “age”, the trafficker will see “age” as the key name.
  • Now, select a Value type – Dynamic or Predefined. Then, go to the Report on values and select as per your requirements. Selecting Yes will make the keys Reportable and appear in the Ad Manager reports.
  • Now, go to the Targeting values and click New values.
  • Then, enter the values for the key separated by whitespace. You can enter 200 values per line item with a free Ad Manager account. If you want to add more values, you’ve to upgrade to an Ad Manager 360 account.
  • Save the key-values. This is how saved key-values look in the Google Ad Manager dashboard: Save the key-values. This is how saved key-values look in the Google Ad Manager dashboard:

Once you’re done adding key-values, the next step is to add the key-values to the ad request. 

Step #2: Add Key-values to the Ad Requests

Here comes the role of GPT. Since there are two types of targeting, i.e., page-level and slot-level, as discussed before, you need to use the setTargeting () function to pass multiple keys and values. Let’s understand how to do that in detail:

Ad slot-level targeting:

Paste the below code to the header part of your GPT just after specifying the network code and targeted ad slots:

Ad Slot Level Targeting

Once you pass the key values, the line items targeted to them will be eligible to serve that ad slot. In this example, the code will trigger the line items targeted to gender = females to serve on the ad slots, provided that they match all other targeting criteria. Also, if you want to attach multiple values to a key, you can do it in the tag itself, e.g., .setTargeting(“age”, [‘18-35’, ‘45-85’]);.

Page-level targeting:

To add custom parameters for page-level targeting, paste the below code to the head of the GPT after adding the network code and targeted ad slots:

Google tag

This code will enable all the ad slots on the page to inherit the targeting. Also, if you add ad slot-level and page-level targeting, write the code after the previous code for slot-level targeting.

Here’s the script of a GPT head tag with ad slot-level and page-level targeting:

Key Value Targeting

Note: Now the question is, what if you have a universal GPT for all the pages on the site but want to target only specific pages with the help of key-values?

There’s an answer. You can write a logic that checks the URL to determine whether the page should run the custom GPT tag (with key-values) or the usual GPT tag. If you already use different GPT for a different set of pages (for instance, GPT for the homepage. GPT for sports article pages, etc.), you can append the GPT tag of the pages you would like to target or exclude. 

Step #3: Target Key-values via Line Items

The final step to start targeting a page’s specific pages or ad slots in Google Ad Manager is to trigger and serve the line items that match the targeting criteria specified by the publisher. Follow the below steps to do that:

  • Go to the Google Ad Manager home page and click Delivery > Order. Then, select the Line item that you want to target.
  • Then, scroll down to the Add targeting section. Go to Custom targeting. Select Key from the drop-down menu and enter the values for the key. You can even create different sets of key-values with the help of the And and Or feature. Selecting And will make it necessary for the line item to match with all the values, while Or is broad and make the line item eligible to serve if one of the values matches.

If you don’t want the ads to appear on a specific area of a web page, then you can select “is not” from the drop-down menu. And then, Save the setting.

How to Know If a Specific Page is Targeted Or Not Via Key-Values?

If you want to determine whether the key-value combinations are added to your page, you can do it without signing into the Ad Manager account. This is how it can be done:

  1. Navigate to the page where you want to check and right-click anywhere on the page. 
  2. Select View page source and find the word targeting by pressing the Ctrl+F or Command+F keys.

You can see in the above code snippet how keys and values are displayed in the source code. Here, Key is “grapeshot_segments”, and Values = gs_tech, an_bankofamerica, an_ms_safe, etc. When the values match with the targeting criteria of line items, the eligible line items serve the ad on the respective inventories. 

What’s Next?

Although there are multiple usages of key-values, from targeting a specific ad slot to analyzing the performance of attributes via Ad Manager reports, once the concept is clear to you, passing the key-values to the ad requests will become quite simple. 


What Is Key-Value Targeting in Google Ad Manager?

Key-value targeting is a feature in Google Ad Manager that allows advertisers to target specific ad inventory based on custom key-value pairs set by publishers.

How to Optimize Key-Value Targeting for Better Results?

Publishers can gain insights into their audience demographics and preferences and collaborate on developing a more effective targeting strategy. It’s also important to regularly communicate and share data with your advertising partners to ensure your targeting strategy aligns with their business goals.

News and Tips for Publishers

Get the inside scoop on publishing and programmatic with our 5-minute newsletter.