Key-values targeting in Google Ad Manager on WordPress sites

On This Page,You can easily know about Key-values targeting in Google Ad Manager on WordPress sites.

Google Adsense is a program is run by Google. The program allows the publishers around the Google network of content sites to offer automatic text, video, images, advertisements to name a few. All of this is directly targetted towards the site content and the audience.

Imagine that you’re running a blog with three categories of content: sports, nutrition, and wellness. You want to allow one of your clients — a sports gear company — to only appear on your sports pages and another — a snack bar advertiser — to only show its ads next to articles about nutrition.

Now, if you’d implemented Google Ad Manager some years ago, you’d have to create different ad units to achieve this and manually place them on the pages accordingly. Hence, you’d have to put your “sports” ad unit only on sports pages and inject the “nutrition” ad unit into the nutrition pages. But since Google introduced key-value pairs, using tons of ad units has become obsolete.

With key-values, you can use the same ad unit on all pages. You would then use key-values to target nutrition content vs. sports content. It’s easier, faster, and allows you to sell your inventory more granularly and at a premium, while offering each of your advertising clients the reach and ROI, they are looking for.

In this tutorial, we’ll take a look at how to configure key-values in Google Ad Manager and on your WordPress site so that you’ll be able to target your line items against such classifiers (aka, keys) as the post category, tag, or placements.

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)
  • (asterisk)
  • ; (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.

How to set up key-values (aka. Custom targeting) in Advanced Ads 

To set up custom targeting, I would first head to my WordPress dashboard and ensure that the Google Ad Manager Integration add-on is activated.

Now, navigate to Advanced Ads > Ads and click on “New Ad”.

new ad custom targeting

In this example, I name this ad unit “Advanced Ads” and select the AdvancedAds ad unit, which I have previously created in my Google Ad Manager account.

ad manager import ad unit

Next, I’ll scroll down to configure my ad sizes and the Key-value options to target specific categories.

Note: The ad sizes available will depend on the ones I have configured in my Google Ad Manager account. In my case, I want this ad unit to target 970×90 for large screens and 300×250 for smaller screens. Therefore, I’m simultaneously leveraging the responsive feature to configure my ad unit properly. You’re welcome to skip this step if you already configured the ad in a way you’d like it to be!

key values advanced ads

You’ll see the Key-value targeting box below the size settings. In my case, I have already created one key, which I have named “postcategory”.

And what if I want to target that same ad unit with multiple key-values pairs?

Then, I would add all of the targeting keys that I need to use in the Key-Value targeting section. For example, imagine that I want to target my Advanced Ads ad unit together with the targeting key “postcategory” and “placementID”. I would add both to my ad configuration in Advanced ads, as shown below:

manage key values

Note: You can set up different key-values for each ad in Advanced Ads. Of course, they can be the same for other Ad Manager units. You can also deliver the same ad unit with different key-value pairs. In that case, create multiple ads in Advanced Ads with the same ad unit assigned to it.

How to use the WordPress post category for key-values targeting

PHP code

First, we need to implement a few lines of code in WordPress, to get the categories from the post.

I am saying categories because it is possible that a post has more than just one.

  • Log in to your WordPress Dashboard
  • Go to Advanced Ads > Ads and create a new ad
  • Enter a title and choose the Plain text and code ad type and add the code from below to the code field
  • Enable the Allow PHP option
  • Click on the Publish button at the top right
  • Go to Advanced Ads > Placements and create a new HEAD ad and assign the just created ad to it.

The code above collects the category slugs belonging to the current post or the category if this is a category archive. It ignores any hierarchy. In the client project, we picked categories only from specific hierarchies. You can edit this code or reach out to me for help if you want to change the behavior about when which category is picked.

A word on the used category slug. This is normally your category name converted into a string that could be used in the URL. E.g., if your category name is “Car”, the slug would be just “car”. If you change your category name later, the slug might persist. This is good for SEO purposes. You could rewrite the code above to use the category name instead.

Using key-values in Google Ad Manager

You can use key-values for targeting line items.

Go to Line items > {Choose the line item} > Settings.

Go to the Add targeting section and click on key-values.

Now you can choose the key (e.g., “category”) and select the values. You will find a list of choices from the key-values you set up earlier here. If you investigate the available options you will see that you can also choose to target only ad units that don’t have a specific value or use string operators like begins with here.

In the example below, I just target ad units with the “news” value.

This is it. The line item with that category will be displayed only for assigned ad units that also have the key “category” with the value “news” in it.

Leave a Reply