About key-values

Get started with 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 webpages or an app 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
  • Specify parts of a page
  • Help target other ad inventory 

They can also be based on information you've gathered about people who visit your website or app to target ads based on 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.

Key-value restrictions

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).

PII includes, but is not limited to, information such as IP addresses, email addresses, personal mobile numbers, and social security numbers.

We strongly recommend that you seek legal advice if you are unsure if information constitutes PII. All legally acceptable but recognizable data must be obfuscated or codified.

For ad requests where ads personalization should be turned off, either because of user preferences and/or because of regulatory requirements, you may not :

  • Target using key-values that represent user identifiers' ID or user data
  • Record information against user identifiers for the purposes of personalized ads measurement or targeting

To get started with key-values:

Example of set up

Suppose you run the news app and website World News Online. Suppose also that your advertiser wants to specifically reach people who visit the sports page on your website but are also interested in fashion.

When people create a user account for World News Online, their personal information is stored in a database for World News Online. To help your advertisers show ads to relevant users, you can set up key-values.

First, you define a key such as "page" with values that represent all the pages of your content, such as "local-news", "travel", and "sports". These values identify parts of your app and website:

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

Then you also set up key-values that represent users’ interests, for instance :

  • Key: interests
  • Values: fashion, chess, languages

To make sure key-values work, you need to tag your app and website. You generate ad tags for ad units, which represent ad space on different parts of your app or website. These tags should include key-values for the page they represent. So, your sports section should include an ad tag with the key-value page=sports. 

Next, if a user is signed into World News Online, your developer team can extract the relevant information from the World News Online database for that user and pass it programmatically into each tag for the web or app. 

From Ad Manager, you can then target line items for your advertiser that include the required key values:

  • Key: page
  • Values: sports


  • Key: interests
  • Values: fashion

When users, who are signed in, browse your app or website, an ad request is sent to Ad Manager with all keys and values. If the user satisfies the particular targeting of the line item, then an ad creative is served. If not, another more generic line item and creative is selected.

In this case, when a user visits the sports section of your website or app, and this user's account indicates an interest in fashion, the line item would be eligible to show an ad.

Learn more about best practices ;in setting up names and display names.

Learn more about key-values:

Was this helpful?
How can we improve it?

Need more help?

Sign in for additional support options to quickly solve your issue

Clear search
Close search
Google apps
Main menu
Search Help Center