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-server 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 | MandatoryMacro | FreeWheel Macro | Description | Comments | Filed Field Ownership | |
|---|---|---|---|---|---|---|
| site |  | 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 | | hardcoded | This variable must contain one of the following strings
| Ad server/ broadcaster player | ||
| stream | | hardcoded | This variable contains always the fixed string
| Broadcaster player | ||
| mobid |
| macro_1 | #e{request.deviceId} | 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.We do not believe it is really needed to url-encode the IDFA since it should be alphanumeric already. The encoding is "just in case", so it can never break the tracking-URL structure | 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 | | macro_2#e{ad.externalId} | Clearcast 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 | | macro_3? | The BCID from 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 | | macro_4? | The player name. | Broadcaster player to submit as a key/value pair when the ad call is made. | ||
| plv | | macro_5? | The player version. | Broadcaster player to submit as a key/value pair when the ad call is made. | ||
| login |  | macro_6 | ? | This 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 | | macro_7 #{ad.ref.random} qqqqqqqqqqqqqqqqqqqq | Kantar’s own specification is a random number in base36 encoding, but other formats are acceptable too.
| 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 | | 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 |
| 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
| Event | Tracking URL's |
|---|---|
| start | https://sitename.2cnt.net/j0=,,,;+,event=start+stream=ad-vast+mobid=#e{request.deviceId}macro_1+cq=#e{ad.externalId}macro_2+cq2=macro_3+pl=macro_4+plv=macro_5+login=macro_6+uid=#{ad.ref.random}macro_7+uid2=macro_8+app=macro_9;;; |
| firstQuartile | https://sitename.2cnt.net/j0=,,,;+,event=firstQuartile+stream=ad-vast+mobid=#e{request.deviceId}macro_1+cq=#e{ad.externalId}macro_2+cq2=macro_3+pl=macro_4+plv=macro_5+login=macro_6+uid=#{ad.ref.random}macro_7+uid2=macro_8+app=macro_9;;; |
| midpoint | https://sitename.2cnt.net/j0=,,,;+,event=midpoint+stream=ad-vast+mobid=#e{request.deviceId}macro_1+cq=#e{ad.externalId}macro_2+cq2=macro_3+pl=macro_4+plv=macro_5+login=macro_6+uid=#{ad.ref.random}macro_7+uid2=macro_8+app=macro_9;;; |
| thirdQuartile | https://sitename.2cnt.net/j0=,,,;+,event=thirdQuartile+stream=ad-vast+mobid=#e{request.deviceId}macro_1+cq=#e{ad.externalId}macro_2+cq2=macro_3+pl=macro_4+plv=macro_5+login=macro_6+uid=#{ad.ref.random}macro_7+uid2=macro_8+app=macro_9;;; |
| complete | https://sitename.2cnt.net/j0=,,,;+,event=complete+stream=ad-vast+mobid=#e{request.deviceId}macro_1+cq=#e{ad.externalId}macro_2+cq2=macro_3+pl=macro_4+plv=macro_5+login=macro_6+uid=#{ad.ref.random}macro_7+uid2=macro_8+app=macro_9;;; |