Ad-Server Macros

Owned by Hendrik Vermeylen (KASRL) (Unlicensed)
Last updated: Jul 05, 2018

Introduction

The goal of this document is to make the link between the variables that are defined in the VAST tracking pixel from Kantar on the one side, and the macros that are available in the FreeWheel and other ad-servers that can provide the information that is required in each variable on the other side. It is important to note that this document has a hard dependency on the tracking pixel specification.

Official FreeWheel Documentation

Document for FreeWheel macros can be found at http://adssn.com/FW/creativecheck.html.

Binding Adserver-specific macros to Kantar Variables

Variable

Mandatory

Macro

Description

Comments

Field Ownership
site(tick)hardcoded

The site name for the url.

The site name will be specified by Kantar Media spring and will be communicated to each Ad server provider.


Broadcaster player
event(tick)hardcoded

This variable must contain one of the following strings

  • start - stream is started
  • firstQuartile - 25% of stream is viewed
  • midpoint - 50% of stream is viewed
  • thirdQuartile - 75% of stream is viewed
  • complete - 100% of stream is viewed

Ad server/ broadcaster player
stream(tick)hardcoded

This variable contains always the fixed string

  • ad-vast

Broadcaster player
mobid

(tick) iOS

(tick) Android

(error) Other

macro_1

Apple or Google IDFA in cleartext. Structure is xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

We expect this variable to be filled in the case of an Apple or Android device. In other environments, we expect this to be empty.

Apple's convention seems to be IDFA's in uppercase, while Google's convention seems to be IDFA's in lowercase. We expect this to be respected in the data because Kantar system that process this information are case-sensitive.

Broadcaster player to submit as a key/value pair when the ad call is made.
cq(tick)macro_2Clearcast ClockID. Commercial UK-wide unique ID. Example: AGY/COKY123/030. The last 3 digits are the duration of the clip in seconds.We do not believe it is really needed to url-encode the ClockID since it should be alphanumeric already. The encoding is "just in case", so it can never break the tracking-URL structure.Ad server
cq2(tick)macro_3The BCID of the content alongside which the ad was served.
Broadcaster player to submit as a key/value pair when the ad call is made.
pl(tick)macro_4The player name.
Broadcaster player to submit as a key/value pair when the ad call is made.
plv(tick)macro_5The player version.
Broadcaster player to submit as a key/value pair when the ad call is made.
login(error)macro_6This is a unique identifier assigned by the broadcaster app to identify the user. 
This will have different formats for different broadcaster apps. It is also available in the TVPR-data in the same variable.
TBC
uid(tick)macro_7

Kantar’s own specification is a random number in base36 encoding, but other formats are acceptable too.

  • Math.round((Math.random()*10000000000)).toString(36);

Random number generated unique for each time the ad is referenced in the ad choreography of the response.

For example, #{ad.ref.random} is a FreeWheel macro that will generate a random ID based on the combination of the ad ID + replica ID (replica ID is used in case an ad is played more than one time per response).

Ad server
uid2(tick)macro_8

The UID is a random generated value coming from the Kantar libraries that are built into the broadcaster players. This value is generated once for every content video view and it is exposed to the broadcaster player.

We expect the uid2-variable to be filled with this UID-value for every ad served alongside the content.


Broadcaster player to submit as a key/value pair when the ad call is made.
app

(tick) iOS

(tick) Android

(error)  Other

macro_9

The app name in the case that it is an Apple or Android device.

We expect this variable to be only set when it is an Apple or Android device.

It is also possible to set some other value, f.e. a string indicating the platform.

Kantar uses this variable to determine if the request should be treated as mobile or stationary.
If this is impossible to deliver according to the description (i.e. empty for non-mobile), then it is also possible for Kantar to look for the mobid instead.		Ad Server/Broadcaster Player

Resulting Tracking URL's

EventTracking URL's
start
https://sitename.2cnt.net/j0=,,,;+,event=start+stream=ad-vast+mobid=macro_1+cq=macro_2+cq2=macro_3+pl=macro_4+plv=macro_5+login=macro_6+uid=macro_7+uid2=macro_8+app=macro_9;;;
firstQuartile
https://sitename.2cnt.net/j0=,,,;+,event=firstQuartile+stream=ad-vast+mobid=macro_1+cq=macro_2+cq2=macro_3+pl=macro_4+plv=macro_5+login=macro_6+uid=macro_7+uid2=macro_8+app=macro_9;;;
midpoint
https://sitename.2cnt.net/j0=,,,;+,event=midpoint+stream=ad-vast+mobid=macro_1+cq=macro_2+cq2=macro_3+pl=macro_4+plv=macro_5+login=macro_6+uid=macro_7+uid2=macro_8+app=macro_9;;;
thirdQuartile
https://sitename.2cnt.net/j0=,,,;+,event=thirdQuartile+stream=ad-vast+mobid=macro_1+cq=macro_2+cq2=macro_3+pl=macro_4+plv=macro_5+login=macro_6+uid=macro_7+uid2=macro_8+app=macro_9;;;
complete
https://sitename.2cnt.net/j0=,,,;+,event=complete+stream=ad-vast+mobid=macro_1+cq=macro_2+cq2=macro_3+pl=macro_4+plv=macro_5+login=macro_6+uid=macro_7+uid2=macro_8+app=macro_9;;;