About key-values

Define custom targeting

Key-values let you define custom targeting. They are used in the targeting picker and included in ad tags. When an ad request comes in from one of your pages that has key-values in its ad tags, line items that target those key-values are eligible to serve for that ad request.  

Key-values can be used for a variety of purposes. They can identify pages on a website, specific parts of a page, or other ad inventory. They can also be based on information you've gathered about people who visit your website or app in order to target ads based in that information.

Key-values, like other targeting, help your advertisers and buyers reach their intended audience or demographic. They add value to your offerings when negotiating campaigns.

Use key-value targeting with care

Under the terms of your contract, you must not pass any information to Google that Google could use or recognize as personally identifiable information (PII).

IP addresses cannot be used as a key-value input.

Get started with key-values

The basic process to get started with key-values is to:

Example of set up

Your advertiser might want to reach people who visit your sports page on your website. The advertiser may additionally be interested in targeting males from the age of 18 to 32.

You can define a key like "page" and values such as "sports", "news", and "travel" to identify parts of your website:

  • Key: page
  • Values: sports, news, travel

Additionally, you may be able to understand who's engaging with your website. This information could be gathered, for instance, based on users who singed into your website with a user account. These user account could contain information from their user profile, like age, and you could then capture these users via key value such as:

  • Key: age
  • Values: 18-32, 33-42, 43-55, 56-plus

After tagging your webpages, you can then target line items to reach this audience. Learn more about good practice in setting up names and display names.

Predefined and dynamic key-values

Predefine a key and its values or create a dynamic key-value. Dynamic key-values use a defined key but take dynamic values based on user attributes or behavior. If your requirements exceed 200 possible values per key and you don't want to define them in advance, use dynamic targeting.

Predefined key-values

Use predefined key-values when you know the possible range of values.

For example, create the predefined key "age", and enter ranges as values—such as, "18-32", "33-42", and so forth. When you add the line item, select "age" as the key and "18-32" as the value. The key-value remains hard-coded in the ad tag.

Most publishers believe it's good practice to use less identifiable key-values strings in ad tags. Learn more in Names versus display names.

Dynamic key-values

Dynamic key-values let you pass targeting values dynamically into an ad tag based on information you collect.

For example, you can use dynamic key-values to target ads based on a user's search terms on your site. With dynamic targeting, you can have thousands of possible targeting values without defining each one ahead of time.

Example of dynamic key-values

Target line items to specific content and ad slots. If you want to target specific pages on your site, create a dynamic key named "pageID". Add pageID=123456 to the page's ad tags and then target your line item to that key-value.

You might also use key-values to target ads to specific ad slot positions. If you sell your ad slots above the fold at a premium, create a pre-defined key called "position" with multiple values, such as "top", "right-box", and "bottom". Add the key and value combination to your ad tags (position=top) and target certain line items to that key-value so they don't appear below the fold.

Was this helpful?
How can we improve it?