A Publisher’s Ultimate Guide To Key-Value Pairs

Ad Optimization
February 18, 2021 | by Kean Graham
A Publisher's Ultimate Guide To Key-Value Pairs

Key-Value Pairs (KVPs) help you better understand your site visitors, market your inventory more effectively, and earn more for your traffic. KVPs are parameters added to the ad request to facilitate targeting at a more granular level.

Your strategies around KVPs should ideally align with your goals. What are you trying to achieve? That question alone can determine the succeeding steps you need to take. Let’s start!

Step 1: Determine your KVP strategy

Depending on the type of data your advertisers might be interested to know, identify which keys would be useful. For example, Advertiser AAA would like to reach an audience that loves Football, within the age range of 18-45. Based on that, create two keys: “section” and “age.” If necessary, add a third one, “sport,” to specifically identify the pages or articles on your site where football is the topic among the many other sports.

If your users are signing in to access your site, and you already collect their demographic information, you could leverage that to set your “age” key with values such as “10-17”, “18-45”, “46+”.

Step 2: Decide on the type of values to set

A Publisher's Ultimate Guide To Key-Value Pairs MonitizeMore

Dynamic values – when the values are changing or unknown. For example, the user’s school or company name or the user’s search terms. These are passed dynamically in your ad tag. You can have thousands of possible values without defining them ahead of time.

Predefined values – when you know all the possible values. For example, all your site sections, categories, or list of sports you publish about. The key-value is hardcoded in the ad tag.

Step 3: Setup Key-Values on your account

In your Google Ad Manager account (GAM), go to Inventory > Key-values.

1) Create a new Key-Value

2) Give it a name. This is the Key that should match exactly what is in the tag.

3) Display name is what appears in the Google Ad Manager interface. This can be the same as the ‘Name’ or can be different. For example, the Key or name is ‘a’ (hardcoded in the ad tag), but when trafficking in GAM, it shows ‘age.’ Some publishers would do this, so it’s less identifiable externally.

A Publisher's Ultimate Guide To Key-Value Pairs MonitizeMore

4) Set the value type based on what you decided on in the previous step.

5) Select ‘Include values in reporting’ so you can generate reports based on the Key.

A Publisher's Ultimate Guide To Key-Value Pairs MonitizeMore

6) Clicking ‘New values’ will save the Key you have created. Only do so when everything has been checked for spelling errors and all settings are verified to be correct, especially the Key or name, which cannot be changed once saved.

7) Type in all the targeting values if using Pre-defined KVP.

8) Click Save

Step 4: Generate the tags with KVPs

Key-Values can be set in the ad slot-level or page-level.

A Publisher's Ultimate Guide To Key-Value Pairs MonitizeMore

Page-level – this is to target specific pages or sections on your site. For example, you can assign values such as “food” “news” on pages that fall under those categories. When targeting in the line item, it then targets the entire page or all the ad units deployed on the page.

Ad slot-level – this is to target specific ad units on a page. For example, you have buyers that would like to target only the premium placements. You can set a KVP for the top 3 ad slots with the highest viewability. When targeting the KVP in the line items, you prevent them from serving on slots you determined to have low viewability.

Dynamic data such as URL or page title can also be pulled from the page to be included as key-values in the ad request. For example:

  • Store the page title in a variable:

var pageTitle = document.title;

  • When defining the ad slot, reference this variable in your key-value targeting:

.setTargeting(“title”, pageTitle);

Step 5: Target Key-Values via Line items

You can tell Google Ad Manager to make the line item eligible to serve or not, using Key-Value targeting. You can either include (“is”) or exclude (“is not”) Key-Values.

A Publisher's Ultimate Guide To Key-Value Pairs MonitizeMore

In your Google Ad Manager account, go to Delivery > Orders > open the relevant order, then line item or create a new one if needed. Under the “Add targeting” section within the line item settings page, click Custom targeting. Search for the key relevant to that line item and select the values you’d like that line item to target. Use logical expressions to target multiple key-values to a line item. Click Save.

Step 6: Reports and Forecasting

You need about 28 days to begin forecasting on Key-Values and having Key-Values as a dimension in your reports. A forecast gives you an estimate of impressions available based on your targeting criteria. For example, if you include Key-Values in your targeting, you’ll have an insight into the potential volume of visitors you’ll get for your News page. When setting up PMP (Private Marketplace) deals, you can present this data to the advertisers and show how your site fits their campaign.


A Publisher's Ultimate Guide To Key-Value Pairs MonitizeMore

  1. On your GAM account, go to Delivery > Line items
  2. Click Forecasting
  3. Select the inventory type
  4. Set the rest of the line item settings
  5. Set your Key-Values in Custom Targeting
  6. Click Check Inventory


A Publisher's Ultimate Guide To Key-Value Pairs MonitizeMore

  1. Run a historical report
  2. Add Key-values as a filter if needed
  3. Add Key-values as a dimension


Following our step by step guide will enable you to set up your key-values and use them in various ways to increase your ad revenue. Do you need additional help to optimize your ad inventory? MonetizeMore is a Google Certified Publisher Partner who has helped hundreds of publishers optimize their ads! Are you ready to take your ad revenue to the next level? Sign up to MonetizeMore today!

More than 1500 publishers see 50-400% ad revenue growth with us.

Don't just take our word for it


Paid to Publishers


Ad Requests Monthly


Happy Publishers

Recommended Reading

April 19, 2024

Navigating the Online Real Estate Marketplace: 8 Tips for Monetized Publishers

Read More
April 17, 2024

ViewBotting: How Bad Bots Affect Publishers?

Read More
Ad Network Reviews, Tips & Guides
April 16, 2024

2024’s Best Video Ad Networks

Read More

Trusted by 1,500+ publishers worldwide

10X your ad revenue with our award-winning solutions.

Let's Talk


Ready to 10X your ad revenue with the #1 ad management partner?

Start Now