Documentation

Key-values

URL macros in image and click URLs

If you are using the GAM Email AdServer product, you can use one of the existing supported key-values for targeting purposes, or add your own.

📘

Key-value configuration in GAM

Please make sure to configure the key-values you want to use in the “Key-values” section under the Inventory tab in GAM in order use them for targeting or reporting in your line items.

Default key-values

The following key-values are automatically passed through to GAM. The values are passed in lowercase.

🌐 Geo-targeting

Key-valueDescription
pi_geo_countryThe country code in ISO 3166-1 alpha-2 form. This can be used to target a line item to one or more countries.

For example, you can target to a line item only if the traffic is from us, ca or gb
pi_geo_regioncodeThe region code in ISO 3166-2 form.

Each ISO 3166-2 code consists of two parts, separated by a hyphen:

- the ISO 3166-1 alpha-2 code of the country. For example us for USA.
- a string of up to three alphanumeric characters representing the region. For example co for Colorado.If you want to target a line item to only traffic from the state of Colorado, you would target to the key pi_geo_regioncode with the value us-co.Note: due to the amount of proxy traffic in email, using targeting via K/V below the country level will implicitly filter out the majority of the traffic.
pi_geo_cityThe name of the city.

For example, if you want to target a line item to only traffic from Paris, you would target to the key pi_geo_city with the value paris.

You can find the list of city names via https://www.geonames.org/
pi_geo_postalcodeThe postal code
pi_geo_metrocodeThe Nielsen DMA code.

For example, if you want to target a line item based to traffic from the Boston / Manchester region, you would target the key pi_geo_metrocode with the value 506.

🎯 Proxy targeting

Key-valueDescription
pi_proxySet to true if the email client uses an image proxy.

Gmail uses an image proxy and this will be set to true when the ad impression is from Gmail, as well as for Yahoo, Outlook and Apple Proxy.
pi_proxy_typeThe name of the proxy when pi_proxy is true. You can use this to include/exclude different proxies or set different CPM values based on the traffic characteristics

The value will be one of:

googleImage
yahooMail
outlook
apple

🚧

Limitations for proxy traffic

For Proxy traffic, the following fields will not be set as the data is of unknown accuracy:

  • pi_geo_regioncode
  • pi_geo_city
  • pi_geo_postalcode
  • pi_geo_metrocode

Custom key-values

You can pass custom key value pairs to GAM by adding query params to your image and click urls using the dfp_ prefix.

For example if you wanted to pass the day of the week as a key value to GAM, you would:

  • Add the following query parameter to your image and click urls dfp_dayofweek=<value> (for example sunday).
  • Target your line items in GAM to the key dayofweek with value sunday.

📘

Key-value configuration in GAM

The dfp_ prefix is stripped off when passing the key-value. On the GAM side, you must use the name of the key without that prefix i.e if the query parameter is dfp_<key>, the key-value to configure in GAM will be <key> without the prefix.

Reporting

In order for the key-values to appear in reports, they must be marked as reportable.

Under Inventory / Key-values, edit the key-values you want to make reportable and select "Dynamic" and "Include values in reporting".

When running reports, you can add the Key-values dimension under Inventory

You can also optionally filter to a specific key-value


Custom reporting dimensions

If you want to use a specific key value as a custom dimension in reports, it needs to be pre-defined. Note that there is a limit of 200 values per key and this also counts against the total values limit in your account. Below are preset values for some of our key-values to help you set up your account.

Data setInformation
Full country listThis data set is too large to use for the pi_geo_country key-value. It is shared as a reference and starting point to make your own custom set.
Optimized country listThis data set is an optimized country list with the maximum of 200 entries, with a subset of countries excluded based on population, GDP and geographical area.

Depending on your audience, you may want to adjust the selection, using the full list as a starting point.
Proxy typesThe list of 4 recognized proxy types
Example of pre-defined values for proxy types

Example of pre-defined values for proxy types

Updated 10 months ago