Key-Value Implementation

Introduction

Key-values are a set of information that Freestar can pass into the Ad Server that will be used in either targeting for Direct Campaigns or for reporting purposes. See below for a clarification of terms before proceeding to the other tabs to apply key-values.

Clarification of terms:

Key-Value Pair

A set of two linked data items, known as the key and the value. The format of a key-value pair is key=value.

Key

Each targeting key represents a category to which a line item is targeted, where a "category" is represented by a value assigned to the key. Consider a targeting key of "color", where allowable values are "red" and "blue". In this case, "color = red" represents a key/value pair that can be passed in the ad request and used for targeting an ad. Keys can have multiple values assigned to them.

Value

A value passed for a specific targeting key, which can be used in line item targeting. For example, the value in the key-value pair for "color = red" is "red".

Ad Slot

A space on a website where code is placed where an ad is shown.
Ad slots will represent each ad space defined on your page, regardless of which ad unit/placement they are using.
Ad slots can re-use ad units/placements (as long as they have a unique slot and div id).

Ad Placement (This is also known to Google as an Ad Unit)

This is the generic term used when talking about a single type of ad.
It defines the type, size and can be targeted to specific campaigns.
An ad unit/placement loads into an ad slot.

Div ID

The id of the div of the ad slot.

Page-level

A page-level key-value is a set of values that you want to set for the whole page.

Slot-Level

A slot-level key-value is a set of values that you want to set for a specific ad slot.

Unacceptable values

Below is a list of invalid characters that cannot be passed in the value field.
NOTE: Spaces are acceptable in the value field.

" (double quotes)
' (apostrophe)
= (equal sign)
! (exclamation point)
+ (plus sign)
# (pound sign)
* (asterisk)
~ (tilde)
; (semicolon)
^ (caret)
() (parentheses)
< > (angle brackets)
[ ] (square brackets)
, (comma)
& (ampersand)

Page-Level

Page-Level Key-Values

Generally, this is used for things like an article type or author of a page where the value is not different for each ad slot but applies to the whole page. This needs to be inside the freestar.queue.

To add a page-level key-value

Add the example below to the <head> of your page in your code editor. This should be placed below the Freestar enabled_slots call that you should already have in the head of your page.
Edit the example to suit your needs:
1. key(1) = The name of the key you would like to use.
  1. If using Freestar's GAM: Freestar defines the keys and values in our GAM and should not be customized or modified as it needs to match a key and/or value name we have set in our system. Check with your Onboarding Specialist or Customer Service Manager on available key/value names.
  2. If using your GAM: If you are in your own instance of GAM, then you will create the key & values in your account and can use custom key-values.
2. value(1) = The name of the value you would like to use.
  1. See notes above on values needing to be created in GAM.
  2. If multiple values need to be passed for a key send it in an array, like the first example. If only one value is needed use the second example.

freestar.queue.push(function() {
    // More than one value
    googletag.pubads().setTargeting('key1', ['value 1', 'value 2', 'value 3']);
 
    // One value only
    googletag.pubads().setTargeting('key1', 'value');
});

Slot Level

Slot Level Key-Values

Generally, this is used for things like the position of the ad unit on the page where the value would be different for each ad slot or some ad slots so it cannot apply to the whole page. This needs to be inside the freestar.queue.

To add a slot-level key-value

Add the example below to the <head> of your page in your code editor. This should be placed below the Freestar enabled_slots call that you should already have in the head of your page.
Edit the example to suit your needs:
1. div_id(1) = The id of the div being used for the slot you want to target. This should also be equal to the slot id as these should be the same for both.
  1. Example:
    1. ```
    
    <div align="center" data-freestar-ad="__300x250 __970x250" id="yoursite_incontent_leaderboard_10_2">
    <script data-cfasync="false" type="text/javascript">
      freestar.config.enabled_slots.push({
         placementName: "yoursite_incontent_leaderboard_10", slotId: "yoursite_incontent_leaderboard_10_2" });
     </script>
```
2. key(1) = The name of the key you would like to use.
  1. If using Freestar's GAM: Freestar defines the keys and values in our GAM and should not be customized or modified as it needs to match a key and/or value name we have set in our system. Check with your Onboarding Specialist or Customer Service Manager on available key/value names.
  2. If using your GAM: If you are in your own instance of GAM, then you will create the key & values in your account and can use custom key-values.
3. value(1) = The name of the value you would like to use.
  1. See notes above on values needing to be created in GAM.
  2. If multiple values need to be passed for a key send it in an array, like the first example. If only one value is needed use the second example.
Repeat the config object for each slot you want to target.

// Slot level targeting
freestar.config.targeting = [{
        "div_id_1": {
            "key1": ["value 1", "value 2", "value 3"],
            "key2": "value"
        }
    },
    {
        "div_id_2": {
            "key1": ["value 1", "value 2", "value 3"],
            "key2": "value"
        }
    }
];

Page & Slot Example

Here's an example of the Head when using both Page Level and Slot level Targeting.

<!-- PLACE THIS SECTION INSIDE OF YOUR HEAD TAGS -->
<!-- Below is a link to a CSS file that accounts for Cumulative Layout Shift, a new Core Web Vitals subset that Google uses to help rank your site in search -->
<!-- The file is intended to eliminate the layout shifts that are seen when ads load into the page. If you don't want to use this, simply remove this file -->
<!-- To find out more about CLS, visit https://web.dev/vitals/ -->
<link rel="stylesheet" href="https://a.pub.network/core/pubfig/cls.css">
<script data-cfasync="false" type="text/javascript">
var freestar = freestar || {};
freestar.queue = freestar.queue || [];
freestar.config = freestar.config || {};
freestar.config.enabled_slots = [];

// Page level targeting
freestar.queue.push(function() {
    // More than one value
    googletag.pubads().setTargeting('key1', ['value 1', 'value 2', 'value 3']);
    // One value only
    googletag.pubads().setTargeting('key1', 'value');
});

// Slot level targeting
freestar.config.targeting = [{
        "div_id_1": {
            "key1": ["value 1", "value 2", "value 3"],
            "key2": "value"
        }
    },
    {
        "div_id_2": {
            "key1": ["value 1", "value 2", "value 3"],
            "key2": "value"
        }
    }
];

freestar.initCallback = function() {
    (freestar.config.enabled_slots.length === 0) ? freestar.initCallbackCalled = false: freestar.newAdSlots(freestar.config.enabled_slots) }
</script>
<script src="https://a.pub.network/yoursite-com/pubfig.min.js" async></script>

Dynamic Key-Values

When setting key-values for ad slots that are being dynamically inserted either through Freestar's scripts or when using SPA the key-values will need to be defined in the head of the page to ensure the targeting is set.

For Example: If you wanted to set a key-value at the slot-level for an ad that Freestar is injecting into the page with our JavaScript like the Adhesion (aka Sticky Footer) or the Sidewall slots, then you would use this method instead of the slot-level instructions above. OR If you wanted to set a key-value at the slot-level for an ad that you are injecting into your SPA page, then you would use this method instead of the slot-level instructions above.

To add a key-value for a dynamic ad

Add the example below to the <head> of your page in your code editor.
Edit the example to suit your needs:
1. div_id(1) = The id of the div being used for the slot you want to target. This should also be equal to the slot id as these should be the same for both.
  1. Example:
    1. ```
    
    <div align="center" data-freestar-ad="__300x250 __970x250" id="yoursite_incontent_leaderboard_10_2">
    <script data-cfasync="false" type="text/javascript">
      freestar.config.enabled_slots.push({
         placementName: "yoursite_incontent_leaderboard_10", slotId: "yoursite_incontent_leaderboard_10_2" });
     </script>
```
2. key(1) = The name of the key you would like to use.
  1. If using Freestar's GAM: Freestar defines the keys and values in our GAM and should not be customized or modified as it needs to match a key and/or value name we have set in our system. Check with your Onboarding Specialist or Customer Service Manager on available key/value names.
  2. If using your GAM: If you are in your own instance of GAM, then you will create the key & values in your account and can use custom key-values.
3. value(1) = The name of the value you would like to use.
  1. See notes above on values needing to be created in GAM.
  2. If multiple values need to be passed for a key send it in an array, like the first example. If only one value is needed use the second example.
Repeat the config object for each slot target.

<script>
window.freestar = freestar || {};
freestar.config = freestar.config || {};
freestar.config.targeting = [{
        "div_id_1": {
            "key1": "value1",
            "key2": "value2"
        }
    },
    {
        "div_id_2": {
            "key1": "value1",
            "key2": "value2"
        }
    }
];
</script>