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.

When adding custom targeting to an audience segment, key names can only include
  • letters
  • numbers
  • colon :
  • semi-colon ;
  • less than sign <
  • equals sign =
  • greater than sign >
  • question mark ?
  • at symbol @
  • square bracket (left only) 
  • back slash \
  • underscore _
A custom value name cannot include an apostrophe '

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). IP addresses cannot be used as a key-value input.

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 reach people who visit the sports page on your website. The advertiser is also interested in targeting males between the ages of 18 - 32.

When people create a user account for World News Online, they may include information such as age and gender. This 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 like "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

You can then set up key-values for age and gender. For age:

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

For gender:

  • Key: gender
  • Values: male, female, other, not-stated

To make sure key-values work, you need to tag your app and website. You generate ad tags for ad units, and these ad units 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

When a user is signed into World News Online, you can use the information stored for that user in the World News Online database. You can know, for instance, the user's age and gender based on their user account.

You can now target line items for your advertiser that include all of these key values:

  • Key: page
  • Values: sports

You can then set up key-values for age and gender. For age:

  • Key: age
  • Values: 18-32

For gender:

  • Key: gender
  • Values: male

When users who are signed in browse your app or website, an ad request is sent to Ad Manager. If the user satisfies the targeting of the line item, then an ad creative is served. In this case, when a user visits the sports section of your website or app, and this user's account indicates male between the ages of 18 - 32, 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?
Clear search
Close search
Google apps
Main menu