Table of contents
Key Values in Google Ad Manager are often overlooked or misunderstood. Originally introduced as DFP Targeting Parameters, Key-Values are a deceptively simple mechanism that provide greatly improved flexibility for both targeting and reporting.
This free guide explains exactly how to use Ad Manager Key-Values, highlights some of the limitations and pitfalls and gives useful examples for publishers to use. The guide has been completely rewritten in 2019 to account for the changes made as DFP changed to Ad Manager and new Key-Value options were introduced.
Just looking for specific information? Jump ahead to the relevant section:
What are Google Ad Manager Key-Values?
Key values are a way of passing additional data into Google Ad Manager so that the ad-server knows more about each ad request. They consist of two pieces of information: A key, such as “gender” and a value, such as “female”.
Key-Values are just a mechanism for passing data. So, whilst I can theoretically create a key for almost anything, I’ll need to collect and pass that information into Ad Manager for it to be useful.
This is different from Ad Manager’s in-built targeting criteria, such as Country or Device-type where Ad manager already has that data.
There are two ways that key-values are usually used: Either for line item targeting, that is targeting ads based on custom criteria or for reporting, such as comparing performance across content types. We’ll show examples of each use-case shortly, but first we’ll look at how to create key values and what we have to consider when doing so.
Creating key-value pairs in Google ad Manager
Keys are created first. This is done by selecting Inventory > Key-values and clicking New Key. The resulting screen asks for 5 pieces of information: Name, Display name, Values type, Report on values & Make a dimension.
Name : The name is used to identify what information is being passed into Ad Manager. Because this name will be used in code it can be useful to use a short, memorable version. Names can up up to 20 characters long. They are not case sensitive and cannot contain any of the special characters shown here. They also cannot begin with a number.
” (double quotes)
‘ (apostrophe)
= (equal sign)
! (exclamation point)
+ (plus sign)
# (pound sign)
* (asterisk)
~ (tilde)
; (semicolon)
^ (caret)
() (parentheses)
< > (angle brackets)
[ ] (square brackets)
, (comma)
& (ampersand)
(space)
Display name: This is a friendly name used when choosing the key within the Ad Manager UI. Having a seperate display name field not only allows you to add more descriptive but also to keep obvious values out of your source code and keep request URLs short.
Values type: There are two options for values type. The first allows for free-form values. Free-form allow for any value to be given to the key when targeting, creating line items of checking inventory. This option gives the most flexibility in what values can be used, but there are drawbacks.
Free-form values are useful for keys where the values are unknown or changing and are predominantly used for targeting. An example would be content-tags, which a publisher might populate with wordpress tags in order to target particular topics within their website.
It used to be true that free-form keys could not be used in reporting. This changed at the end of 2018, but you may still find this being referred to in places. You can’t though use free-form values where you want to report on a key as a dimension – more on that later.
The other option requires that values are pre-defined. Predefining values is useful to create consistency and accuracy, but does require that you know the possible values in advance. For example, if WordPress tags are usually best suited to being free-form, the categories or sections of a website are usually better suited to being predefined.
Report on values: Selecting this option allows you to generate reports based on this key. If, for example, you wanted to compare performance on inventory by category you would need to select this option for your category key. Due to limits on the number of reportable values, this option should be left as “no” unless you definitely want to report of this key. If left set to “No” then the key can only be used for targeting, not reporting, unless this is changed later.
Make a dimension: If you have chosen to make a key reportable you can also select the option of making it a dimension, which offers more powerful reporting. However the limits of the number of values that can be reported as dimensions are very restrictive, so use of this option needs to be planned carefully.
Adding values: If you have opted to predefined values, this can be done by clicking “Add values” and either typing or pasting the values one per line. Like keys, values are not case sensitive, and have some restrictions on the characters that can be used. However, unlike key names you can use spaces in values and can be up to 40 characters in length.
If you are bulk adding values the UI reports that you are limited to entering 200 at a time. This is worth experimenting with though, as we usually find that you can add up to 500 at a time without a problem.
One thing worth drawing attention to is this notice: Whilst Key-values can be used to pass personal information, they cannot be used to pass any information that would allow the user to be personally identified. For example age and gender are allowed, but values like email addresses or phone numbers must not be passed into Google Ad Manager.
Understanding System limits
Whilst key-values are powerful, Ad Manager has limits on the number that can be used in different ways. These limits can be quite restrictive, so it is important to understand them when planning how you will implement key-values.
Active keys: Each Google Ad Manager network can have up to 200 active keys at any time.
Active values: There is a total limited of 2.5 million active values per network, with a maximum of 100,000 values on any key (either free-form or predefined).
These general limits are generous enough for most situations, but there are additional limits relating to key-value reporting:
Reportable key-values: 30,000
Custom dimension key-values: 5,000
The limits on reportable and custom-dimension key-values are not only much smaller, but the way they are calculated means that they are more restrictive than they at first appear. The limits are based on the possible combinations
In this example we have a key with 1000 values and another with 5 values defined. Both have been made into reportable dimensions. Even though we have only defined 1005 different values we have reached maximum 5,000 custom dimension key values and an error is generated if another value is added.
The reportable values, and custom dimension value limits are surprising each to reach if you haven’t planned how your key values will be used.
Passing values into Google Ad Manager
With keys defined you need to then pass some value data into Google Ad Manager to begin using those key-values in any useful way. This is done through the Google Publisher tag on page, using the setTargeting function.
When passing values into Ad Manager you can either have that value associated with just the requests made by a particular adslot, or to all the requests on the current page.
Page level targeting is set in the header portion of the GPT code and is automatically then passed into all ad requests made on that page. This is a good choice when you want to pass details of the user or the page itself, such as the gender of a registered user of the website category they are viewing.
Slot level targeting is set when the ad slot itself is defined. These are most useful when passing values that relate only to requests served into that slot such as it’s position on a page or a viewability prediction.
If you would rather not edit GPT tags directly, either type of tag can also be specified when creating tags in Google Ad Manager.
Targeting lines to key-values
One of the most frequent uses of key-values is in ad targeting. Many publishers will be familiar with this as it being the way that winning bids from header bidding are turned into price priority line items.
Other uses might include targeting different ads based on user registration data, ad position or the users behaviour within the site. The possibilities are really only limited by the data that you are able to apply and your own creativity.
Key-value targeting is usually used to target specific values. For example showing particular ads where “gender = male”. You can though target based on a number of other patterns: “Begins with”, “Includes” or “begins with and includes”.
Multiple keys can even be combined in advanced targeting expressions that use boolean operators.
Reporting on key-values
Besides targeting, the other main use of key-values is in reporting. There are three different ways that key-values can be used in reporting:
Filter on key-values
The first option is to filter a report to only show values that include a certain key-value. If, for example, we had a key for website category we could choose to report only on requests from within a particular category to understand how content in that category performed financially.
A Key does not need to be set to reportable in order to filter on it this way.
Reports values as a dimension
Another way of using key-values is creating a query with reportable values as a dimension. This can be useful for comparing performance between different values, such as comparing placements or reporting on impressions won by each header bidding bucket.
This method requires that the key you want to report on is enabled for reporting (see “Creating key-value pairs in Google ad Manager” above). More useful reports can be made by combining this method with the filtering above. For example Reporting on Key-values as the dimension with a filter on key-value containing hb_pb to get the aforementioned header bidding data.
Reports as a custom dimension
The final key value reporting option is to use keys that have been enabled as dimensions, which was introduced as an option at the end of 2018. This allows one key to be broken down by each of the values. Importantly this allows key-values to be nested by selecting multiple dimensions or combining this with the other methods above.
Wrapping up
Although the ways that key-values can be used are complex, the concept itself is easy to follow. By planning your use of Keys and Values carefully it is possible to make Google Ad Manager more powerful and to produce more insightful reports.
I’d love to update this guide with more real-world examples of how publishers are using Key-Values on their websites. I’d love to hear how you are using them in the comments below.
