Key-Values

Key-Value Implementation

Introduction

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

  1. 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.

  2. 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

  1. 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.

  2. 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. <!-- Tag ID: yoursite_incontent_leaderboard_10_2 -->
          <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.

  3. 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

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

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

  1. Add the example below to the <head> of your page in your code editor. 

  2. 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. <!-- Tag ID: yoursite_incontent_leaderboard_10_2 -->
          <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.

  3. 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>

Keys for Key-Values

Keys for Key-Values

For sites using the Freestar GAM instance, we have a list of keys that you will be able to use, which you can find below:

Zip
wdwsite
wdwsection
utm_term
utm_source
utm_medium
utm_content
utm_campaign
user-agent
url
upoint
uploader
up_recovery
up_bidder
unique
ul
title
tg
test
template
Tag
ta_category
Subcategory
status
State
sr_site_id
song
SiteURL
site
segment
section_type
section
schoolID
sbi_size
sbi_mouse
sbi_dozer
sbi_apoc
religion
referrer
ReferingURL
PropertyType
product
powerlinks
PostID
post
pos
plan
permutive
pagetype
pageId
oxb1
oxb
org
NSFW
MSACode
MinPrice
Member
mediatype
MaxPrice
MagIdList
MagId
m_data
Listing_Zip
Listing_State
Listing_Country
Listing_City
layout
kuid
ksg
keywords
katie_test_key
instabi
iiq
ie
hb_size_freestar_pre
hb_size
hb_pb_freestar_prebi
hb_pb
hb_native_title
hb_native_linkurl
hb_native_image
hb_native_brand
hb_native_body
hb_format
hb_env
hb_bidder_districtm
hb_bidder
hb_adid_freestar_pre
hb_adid
hasAllAccess
gy
gkhsection
gcst
games
g
fsrefresh
fsrebid
fspbg
fsbid
fs_test_variant_id
fs_safeframe
fs_placementName
fs_optimization
fs_app
fs_ad_product
freestar_domain
forums
floors_responsetime
floors_noreponse
floors_id
floors_hour
FeatureTypeList
eth
env
domain
dm_ssp
dm_size
dm_cpm
dm_adslot
dc_seg
date
custom_bidder_size
County
Country
coreg
content
comicid
ComboType
coindesk_pid
City
Category
campaign
browsiViewability
browsiId
block
bid_cpm2
bid_cpm
Beds
Baths
Author
artist
articleID
amznsz
amznslots
amznp
amznbid
advelvet
admiral-recovered
admiral-engaged
act
a