Kinja Data Team

it's A/B test time, my dudes

Here at Fusion Media Group, we have fully embraced Doubleclick For Publisher’s custom key-values - we use them in part as they are intended: for improved targeting and forecasting around things DFP doesn’t track natively (ex: article topics, how many pages a user has seen so far in their visit.) But we’ve also been using custom key-values in a less traditional way: to build a much more robust advertising reporting system than DFP offers out of the box.

We use key-values to do things like:

  • distinguish ad slots that share creative sizes but appear on wildly different parts of the page
  • record referral source to get a better sense of how much revenue different traffic sources drive
  • pull ad related metrics for A/B tests, to measure the impact, intended or not, that new features we’re building are having on the business.

Custom key-values have greatly improved our ability to report on, monitor and understand how ads on our site are performing. However, setting up a system like ours is not the easiest thing in the world.

DFP is an ad server: as an ad server, it happens to also have reporting capabilities. But, ultimately, DFP doesn’t want to be a reporting system; it doesn’t want to store and crunch and deal with any and all data you throw at it. So it takes some finagling to get DFP to work with key-values in a reporting-focused rather than solely trafficking-focused capacity, but it is possible!

Custom key-values 101

Taking a step back for a second - let’s go over what a custom key-value even is. All ad calls on your page at bare minimum will include what site it’s on (‘Ad Unit’ in DFP) and the creative sizes eligible for that slot. Custom key-values are extra parameters you can add to your ad call to further specify targeting criteria, so you can sell and traffic more targeted ads than just a 300x250 on Gizmodo.


DFP allows you to send these custom key-values because a lot of different types of websites with vastly different ad targeting needs use DFP. The extra targeting a shoe e-commerce site wants is likely vastly different than what we as a digital publisher have set up.

One basic example that we implemented is a key-value to indicate the ad’s position on the page. At the top and the bottom of our pages we have ad slots that serve leaderboard banners (728x90, 970x90, 970x250), but, as you might expect, the banners that serve at the top of the page perform much differently than the ads that serve at the bottom.


Sometimes advertisers want to run only in the top ‘above the fold’ slot, so we added a custom key-value called pos (for position) to these ad calls so that ad ops can target leaderboards to pos=top to ensure the ad always shows up in the top slot, rather than the bottom one.


This key-value also helped us in reporting, as now we can separate out and benchmark how ads perform when they show up in pos=top vs pos=bottom.


Reporting with key-values

In the case of pos, that key-value helped increase the granularity of our targeting capabilities for advertisers, but it also vastly improved our ad analytics - we always figured the top slot performed differently than the bottom one, but now we can measure exactly what that difference is.


This is pretty awesome - maybe we should send bunch of interesting key-values through to DFP and start slicing and dicing our ad data however we see fit. Not so fast, there are a few things we need to do to get key-value reporting to work right:

1. Define the expected values in the Inventory tab

Per the DFP documentation:

If you’re using free-form targeting values, you must do one of the following to report on them:

  • Add the value to the key in the “Key-values” section of the Inventory tab.
  • Target the entire key-value (not only the key) in at least one line item. The line item doesn’t need to deliver impressions.

Making sure there are line items targeted to every possible key-value we want to report on is not really scalable, so we want to go with the first bullet point.

This is the step that makes reporting on key-values the most difficult: key-values were built to enhance targeting capabilities, not reporting. DFP has no interest in storing any ol’ key-value you send to it. You have to tell DFP which values to expect for your key in order for them to show up in reporting. Get that sentence framed and put it on your desk, repeat it every night before you go to bed - this is the number one most important thing you need to remember to do in order to flesh out your DFP reporting using key-values.


If you start sending values to DFP that aren’t defined in the Inventory tab these values will not show up in reporting. For example, let’s say we added another leaderboard ad call in the middle of the page, and started sending pos=mid. If we don’t add mid to the list of values for our key in the Inventory tab, our report will continue to look like this:

oh no where is pos=mid!

pos=mid will not show up in reporting until we add it to the Inventory tab (these impressions will still obviously be counted and show up in reporting without the pos key-value as a dimension, we just won’t be able to tell how many impressions served to that key-value specifically)

But once we define mid as a possible value:


We’ll be able to report on this position when we pull by our pos key-value:


(PS, the documentation refers to free-form keys, but for our purposes free form and predefined both are fine - the distinction between the two types only affects what values ad ops can enter in on the line item level. If you add the values to either type of key, they will show up in reporting.)

2. Beware of system limits

Having to manually add values to each key in the Inventory tab obviously limits how far we can take DFP key-value reporting - we can’t use them for very dynamic data. For example, we can’t send through article IDs or URLs because we’d need to add new values every time a new post was published, which happens very, very often.


We’d also quickly hit the system limit of 100,000 active values per key (although luckily this limit is only for active values - you can always deactivate old values to keep under the limit if your use case allows for that)

  • Characters per key: 20
  • Characters per value: 40
  • Active values per network: 2,500,000
  • Active keys (free-form and pre-defined) per network: 200
  • Active values (free-form and pre-defined) per key: 100,000

For semi dynamic data, where there are enough possible values that it would be annoying - but not impossible - to add them in manually, we can use the DFP API automate the process for us.


That’s what we do for our A/B testing key-value, to which we send the current experiment ID and branch - we built a simple wrapper on top of the DFP API Python library ( and have a script to push new values to our key based on the new experiment ID and number of experiment arms, so we don’t have to manually add them in each time we run a test.

3. Remember you can only report on one key-value at a time

Key-value is a single dimension in DFP reporting, which means we can’t report on multiple key-values at a time in a meaningful way.


We send a key-value called tags for the topics editorial tags their post with. So let’s say I want to look at how our top leaderboard ad is performing on pages tagged ‘science.’

If I filter on the key-values pos=top or tags=science, all of the key-values matching that filter will show up in one column, with 1 row per each key-value. There’s no way for me to see impressions where pos=top AND tags=science. It’s only either/or.

this is not what I wanted

If there are values you need to be able to see together in reporting, the only way around this is to concatenate them into a single key-value. For our key-value on traffic source, we wanted to be able to pull data on utm_source, utm_medium and utm_campaign, but obviously can’t make three different keys and call it a day. So instead we made one key called utm, with a concatenated value of source&medium&campaign, so all of the data we need to slice by appears in that single column.


4. Key-value can’t be added as a dimension to any DFP report

There are, annoyingly, a fair number of limits to what dimensions and metrics DFP will let you pull along with key-values in a report. Some of the ones that I come across the most often/curse DFP for are:

  • You can’t pull Active View metrics when you have both key-value and country as dimensions/filters - this means we can’t ever pull position level viewability for US-only traffic, which is a common ask given that most of our direct advertising business is US-only.
  • You can’t pull any video metrics by key-value - this makes any A/B test that affects video ads really fun.
  • You can’t pull total impressions or total clicks by key-value, device category and creative size - I’m always surprised by this one, and have no idea why DFP has such an issue combining device category, which only has 4 possible values, with key-value.

You should go through the query tool and make sure you can pull the dimensions and metrics you’ll need before going too far down the key-value path.


Custom key-values can be really useful in getting more out of your ad data - we have been able to add so much value to our A/B testing set up by being able to report on how product changes affect our ad performance. Just remember that they can’t do everything, but if worked with correctly they can do a lot!

Share This Story

Get our newsletter