DAR Paramater Reference: Difference between revisions
From Engineering Client Portal
(36 intermediate revisions by the same user not shown) | |||
Line 2: | Line 2: | ||
[[Category:Digital]] | [[Category:Digital]] | ||
The purpose of this document is to describe all necessary data inputs for Nielsen to conduct ad measurement on ''Computer Mobile'' and ''Connected TV'' platforms. | The purpose of this document is to describe all necessary data inputs for Nielsen to conduct ad measurement on ''Computer, Mobile'' and ''Connected TV'' platforms. | ||
== Mandatory campaign metadata From Nielsen CMI == | == Mandatory campaign metadata From Nielsen CMI == | ||
{| class="wikitable sortable" style="table-layout: fixed; width:100%;" | {| class="wikitable sortable" style="table-layout: fixed; width:100%;" | ||
|- | |- | ||
! style="width: | ! style="width: 11%;" | Param Name | ||
! style="width: | ! style="width: 10%;" | Legacy Parameter Name | ||
! style="width: | ! style="width: 30%;" | Description | ||
! style="width: 10%;" | Required for Computer / Mobile (C/M) | ! style="width: 10%;" | Required for Computer / Mobile (C/M) | ||
! style="width: 10%;" | Required for CTV | ! style="width: 10%;" | Required for CTV | ||
!| Example Value | !| Example Value | ||
|- | |- | ||
| | | client_id || ci || The ID that is associated with the DAR account that processed tag data is associated with. Will always be hardcoded to a Nielsen generated value that comes from the Nielsen campaign management system || ✔ || ✔ || <code>nlsnci123</code> | ||
|- | |- | ||
| | | ad_server || am || ad server participating on the campaign media-plan. This is an internal Nielsen generated value when the ad server is indicated on the campaign during setup || ✔ || ✔ || <code>3</code> | ||
|- | |- | ||
| campaign_id || ca || Custom campaign hierarchy mapping to Campaign id || ✔ || ✔ || <code>1234567</code> | | campaign_id || ca || Custom campaign hierarchy mapping to Campaign id || ✔ || ✔ || <code>1234567</code> | ||
Line 26: | Line 26: | ||
| campaign_id || ca || Custom campaign hierarchy mapping to Campaign id || ✔ || ✔ || <code>1234567</code> | | campaign_id || ca || Custom campaign hierarchy mapping to Campaign id || ✔ || ✔ || <code>1234567</code> | ||
|- | |- | ||
| | | action_type || at || Fixed value "view" || ✔ || ✔ || <code>view</code> | ||
|- | |- | ||
| | | resource_type || rt || Fixed value "banner" || ✔ || ✔ || <code>banner</code> | ||
|- | |- | ||
| | | subresource_type || st || Fixed value "image" || ✔ || ✔ || <code>image</code> | ||
|} | |} | ||
Line 36: | Line 36: | ||
{| class="wikitable sortable" style="table-layout: fixed; width:100%;" | {| class="wikitable sortable" style="table-layout: fixed; width:100%;" | ||
|- | |- | ||
! style="width: | ! style="width: 11%;" | Param Name | ||
! style="width: | ! style="width: 10%;" | Legacy Parameter Name | ||
! style="width: | ! style="width: 30%;" | Description | ||
! style="width: 10%;" | Required for Computer / Mobile (C/M) | ! style="width: 10%;" | Required for Computer / Mobile (C/M) | ||
! style="width: 10%;" | Required for CTV | ! style="width: 10%;" | Required for CTV | ||
!| Example Value | !| Example Value | ||
|- | |- | ||
| session_id || || Unique, client-generated value that represents uninterrupted app interaction | | session_id || impid || Unique, client-generated value that represents uninterrupted app interaction with content with gaps no greater than 30 minutes. || ✔ || ✔ || <code>R487421B-XXXX-YYYY-3343-E3BBB46E44F2</code> | ||
|- | |- | ||
| device_id || c9 || Mobile Ad ID (IDFA, ADID), Connected Device ID. Should not be the user ID. || ✔ || Preferred if available || <code>A487421B-XXXX-YYYY-8343-E3BBB66E44F2</code> | | device_id || c9 || Mobile Ad ID (IDFA, ADID), Connected Device ID. Should not be the user ID. || ✔ || Preferred if available || <code>A487421B-XXXX-YYYY-8343-E3BBB66E44F2</code> | ||
|- | |- | ||
| | | publisher_id || pubid || This is a unique and persistent identifier supplied by the publisher of the connected device content, which represents the user that is exposed to the ad. This is equivalent to the advertiser ID on mobile devices. || || ✔ || <code>ab1cdef2-gh34-56ij-kl78-opq</code> | ||
<!-- | <!-- | ||
Line 65: | Line 65: | ||
| address || || Registration address || || ✔<br>if HEM unavailable || <code>625 6th Ave, New York, NY 10011</code> | | address || || Registration address || || ✔<br>if HEM unavailable || <code>625 6th Ave, New York, NY 10011</code> | ||
|- | |- | ||
| | | country || || Country of delivery ISO 3166 ALPHA-2 (US, CA, etc.) || Preferred, else derived from IP || Preferred, else derived from IP || <code>US</code> | ||
--> | --> | ||
|- | |- | ||
| | | hem_sha256 || hem_sha256 || SHA-256 hashed email Note: [[#Email Normalization]] rules applied before hashing || Preferred || Preferred || <code>55C06A30DAA5D5F382FDEB8C702EC57875CC9D91A7C78<br>BB620053FD81DC4335C</code> | ||
|- | |- | ||
| | | uoo || uoo || User opt out flag based on OS “Limit Ad Tracking” or “Opt out of Ads Personalization” in mobile setting). This is an indicator for users who have opted out of ad tracking on their app and/or device. The absence of uoo in the tag is interpreted as an implicit opt-in (ie. not opted out). Nielsen offers an opt out from DAR measurement as described in the [https://www.nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=en-us Nielsen privacy policy]. Nielsen requires each application that contains active Nielsen measurement software to disclose that measurement software is included in that app, and provide access to an opt out mechanism: 0 = not-opted-out, 1 = opt-out || ✔ || ✔ || <code>0</code>, <code>1</code> | ||
|- | |- | ||
| publisher_user_id || || Publisher-specific (first party) user ID (must remain persistent indefinitely. || ✔<br>required for publishers || ✔<br>required for publishers || <code>ed36968977606872e4312943c218568123786342</code> | | publisher_user_id || || Publisher-specific (first party) user ID (must remain persistent indefinitely. || ✔<br>required for publishers || ✔<br>required for publishers || <code>ed36968977606872e4312943c218568123786342</code> | ||
Line 81: | Line 77: | ||
|- | |- | ||
| dar_url || || The DAR URL for the specific Nielsen campaign to be tracked. In cases of 3rd party DAR RULs, this URL should be intercepted and unaltered by the publisher/provider. || ✔ || ✔ || <code>http://secure-gl.imrworldcwide.com/cgi-bin/m?ca=nlsn1234&cr=678&ce=abc&pc=12345&ci=nlsnci123&am=1&at=view&rt=banner&st=image&r=12345</code> | | dar_url || || The DAR URL for the specific Nielsen campaign to be tracked. In cases of 3rd party DAR RULs, this URL should be intercepted and unaltered by the publisher/provider. || ✔ || ✔ || <code>http://secure-gl.imrworldcwide.com/cgi-bin/m?ca=nlsn1234&cr=678&ce=abc&pc=12345&ci=nlsnci123&am=1&at=view&rt=banner&st=image&r=12345</code> | ||
|- | |||
| advertiser_id || || Publisher Advertiser ID/Account ID (if necessary via API from ad server) || Preferred || Preferred || <code>001C000001MEebYIAT</code> | |||
|- | |||
| advertiser_name || || Publisher Advertiser Name/Account Name || Preferred || Preferred || <code>Account ABC</code> | |||
--> | --> | ||
Line 90: | Line 90: | ||
| provider_name || prov || Name of the provider supplying the data to Nielsen. || || ✔<br>required for providers || <code>Provider 123</code> | | provider_name || prov || Name of the provider supplying the data to Nielsen. || || ✔<br>required for providers || <code>Provider 123</code> | ||
|- | |- | ||
| tms_id || || Gracenote program ID || || ✔ || <code>EP019890770017</code> | | tms_id || c36 || Gracenote program ID || || ✔ || <code>EP019890770017</code> | ||
|- | |||
| gracenote_ch_id || gc_id || Gracenote channel ID || || ✔ || <code>123456</code> | |||
|- | |||
| app_name || c42=provapn || This is a publisher supplied value, passed either directly or via the platform provider, which represents the name of the app where the user was exposed to the ad. A separate app name will be provided for production use. Please request the app name from your Nielsen representative. || || ✔ || <code>hoolivideo</code> | |||
|- | |- | ||
| program_name || c43 || | | program_name || c43 || This is a publisher supplied value, passed either directly or via the provider, which represents the program name of the content where the user was exposed to the ad. It is critical that these values are formatted and passed consistently. These values should be URL encoded. || || ✔<br>if tms_id not provided || <code>Name Of TV Show S06+<S06:E13></code> | ||
|- | |- | ||
| | | channel_name || ch_name || This is a publisher-supplied value, passed either directly or via the provider, which represents the name of the channel where the user was exposed to the ad. This value should be URL encoded. || || ✔<br>if tms_id not provided|| <code>abc</code> | ||
|- | |- | ||
| | | publisher_genre || c44=provcg || This is a publisher-supplied value which represents the genre of the content where the user was exposed to the ad. In case multiple genre values are present, delimited values can be passed string in order of relevance. It is critical that these values are formatted and passed consistently. These values should be URL encoded. || || ✔<br>if tms_id not provided|| <code><drama>+<comedy></code> | ||
|- | |- | ||
| | | program_type || c45=provgencls || TThis is a publisher-supplied value which distinguishes between television and movie content. One of the following two fixed string values (“television” or “movie”) should be passed, depending on the combination being represented. || || ✔<br>if tms_id not provided|| <code>television</code>, <code>movie</code> | ||
|- | |- | ||
<!-- | <!-- | ||
| original_airtime || || Original broadcast time of content (if applicable) in Unix epoch timestamp format || || ✔ if tms_id not provided || <code>1593633600</code> | |||
|- | |- | ||
| campaign_name || || Custom campaign hierarchy mapping to Campaign name || Preferred || Preferred || <code>Campaign 1</code> | | campaign_name || || Custom campaign hierarchy mapping to Campaign name || Preferred || Preferred || <code>Campaign 1</code> | ||
Line 125: | Line 130: | ||
| gdpr_consent || || TC string. Required if Publisher is using TCF framework || Preferred / Required in some markets || Preferred / Required in some markets || <code>CLcVDxRMWfGmWAVAHCENAXCkAKDAADnAABRgA5mdfCKZuYJez-NQm0TBMYA4oCAAGQYIAAAAAAEAIAEgAA.argAC0gAAAAAAAAAAAA</code> | | gdpr_consent || || TC string. Required if Publisher is using TCF framework || Preferred / Required in some markets || Preferred / Required in some markets || <code>CLcVDxRMWfGmWAVAHCENAXCkAKDAADnAABRgA5mdfCKZuYJez-NQm0TBMYA4oCAAGQYIAAAAAAEAIAEgAA.argAC0gAAAAAAAAAAAA</code> | ||
--> | --> | ||
|- | |- | ||
| os_group || c7 || Operating system of device || Preferred || Preferred || <code>IOS</code>, <code>ANDROID</code>, <code>NA</code> | | os_group || c7 || Operating system of device || Preferred || Preferred || <code>IOS</code>, <code>ANDROID</code>, <code>NA</code> | ||
|- | |- | ||
| device_group || c8=devgrp || | | device_group || c8=devgrp || This is the device type where the user was exposed to the ad. Nielsen relies on both the c8 and c10 values to make platform determination; these values must be consistently populated. If c8 or c10 are not present in the tag, then Nielsen collections will infer the device and platform based on the user agent present in the tag. If one of the below values cannot be determined, then the parameter should not be included in the call or should be left empty. || ✔ ||✔ || See [[#Device Group]] | ||
|- | |- | ||
| device_platform || c10=plt || Platform name || ✔ || ✔ || <code>OTT/code>, <code>MBL/code>, <code>DSK</code> | | device_platform || c10=plt || Platform name || ✔ || ✔ || <code>OTT</code>, <code>MBL</code>, <code>DSK</code> | ||
<!-- | <!-- | ||
|- | |- | ||
Line 141: | Line 143: | ||
--> | --> | ||
|- | |- | ||
| intid || || Single ID assigned per integration provided by Nielsen || | | intid || || Single ID assigned per integration provided by Nielsen || ✔ || ✔ || <code>abc123abc123abc123abc123</code> | ||
|- | |- | ||
| app_id || c13=asid || Server App ID provided by Nielsen || ✔ || ✔ || <code>AB57421Z-XXXX-YYYY-8343-FJQBJ26E44NT</code> | | app_id || c13=asid || Server App ID provided by Nielsen || ✔ || ✔ || <code>AB57421Z-XXXX-YYYY-8343-FJQBJ26E44NT</code> | ||
|- | |||
| timestamp || || Server Unix time in milliseconds (UTC) when exposure occurs || ✔ || ✔ || <code>1548395046744</code> | |||
|- | |||
| ip_address || || Plain-text IP address || ✔ || ✔ || <code>86.100.256.123</code> | |||
|- | |||
| device_useragent || || Client-device user agent string || ✔ || ✔ || <code>Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) hrome/84.0.4147.125 Safari/537.36</code> | |||
|} | |} | ||
=== Email Normalization === | |||
The below procedures should be performed before hashing emails: | The below procedures should be performed before hashing emails: | ||
*remove all leading and trailing whitespace | *remove all leading and trailing whitespace | ||
Line 160: | Line 168: | ||
=== Device Group === | |||
This is the device type where the user was exposed to the ad. Nielsen relies on both the c8 and c10 values to make platform determination; these values must be consistently populated. If c8 or c10 are not present in the tag, then Nielsen collections will infer the device and platform based on the user agent present in the tag. If one of the below values cannot be determined, then the parameter should not be included in the call or should be left empty. | This is the device type where the user was exposed to the ad. Nielsen relies on both the c8 and c10 values to make platform determination; these values must be consistently populated. If c8 or c10 are not present in the tag, then Nielsen collections will infer the device and platform based on the user agent present in the tag. If one of the below values cannot be determined, then the parameter should not be included in the call or should be left empty. | ||
Line 173: | Line 181: | ||
* PSX ''(PlayStation devices)'' | * PSX ''(PlayStation devices)'' | ||
* DVD ''(BluRay & DVD player devices)'' | * DVD ''(BluRay & DVD player devices)'' | ||
{| class="wikitable" | {| class="wikitable" | ||
Line 184: | Line 189: | ||
|- | |- | ||
| "AMN" || STB || Smart TV (STV), Tablet (TAB), Mobile (PHN), Desktop (DSK) | | "AMN" || STB || Smart TV (STV), Tablet (TAB), Mobile (PHN), Desktop (DSK) | ||
|} | |} | ||
Note: For OS, “Android” and “iOS” only applicable for Mobile and Tablet devices | Note: For OS, “Android” and “iOS” only applicable for Mobile and Tablet devices |
Latest revision as of 16:45, 14 July 2023
The purpose of this document is to describe all necessary data inputs for Nielsen to conduct ad measurement on Computer, Mobile and Connected TV platforms.
Mandatory campaign metadata From Nielsen CMI
Param Name | Legacy Parameter Name | Description | Required for Computer / Mobile (C/M) | Required for CTV | Example Value |
---|---|---|---|---|---|
client_id | ci | The ID that is associated with the DAR account that processed tag data is associated with. Will always be hardcoded to a Nielsen generated value that comes from the Nielsen campaign management system | ✔ | ✔ | nlsnci123
|
ad_server | am | ad server participating on the campaign media-plan. This is an internal Nielsen generated value when the ad server is indicated on the campaign during setup | ✔ | ✔ | 3
|
campaign_id | ca | Custom campaign hierarchy mapping to Campaign id | ✔ | ✔ | 1234567
|
creative_id | cr | Custom campaign hierarchy mapping Creative id | ✔ | ✔ | 765432
|
placement_id | pc | Custom campaign hierarchy mapping to Placement id | ✔ | ✔ | placement_plc0001
|
campaign_id | ca | Custom campaign hierarchy mapping to Campaign id | ✔ | ✔ | 1234567
|
action_type | at | Fixed value "view" | ✔ | ✔ | view
|
resource_type | rt | Fixed value "banner" | ✔ | ✔ | banner
|
subresource_type | st | Fixed value "image" | ✔ | ✔ | image
|
Parameter listing
Param Name | Legacy Parameter Name | Description | Required for Computer / Mobile (C/M) | Required for CTV | Example Value |
---|---|---|---|---|---|
session_id | impid | Unique, client-generated value that represents uninterrupted app interaction with content with gaps no greater than 30 minutes. | ✔ | ✔ | R487421B-XXXX-YYYY-3343-E3BBB46E44F2
|
device_id | c9 | Mobile Ad ID (IDFA, ADID), Connected Device ID. Should not be the user ID. | ✔ | Preferred if available | A487421B-XXXX-YYYY-8343-E3BBB66E44F2
|
publisher_id | pubid | This is a unique and persistent identifier supplied by the publisher of the connected device content, which represents the user that is exposed to the ad. This is equivalent to the advertiser ID on mobile devices. | ✔ | ab1cdef2-gh34-56ij-kl78-opq
| |
hem_sha256 | hem_sha256 | SHA-256 hashed email Note: #Email Normalization rules applied before hashing | Preferred | Preferred | 55C06A30DAA5D5F382FDEB8C702EC57875CC9D91A7C78
|
uoo | uoo | User opt out flag based on OS “Limit Ad Tracking” or “Opt out of Ads Personalization” in mobile setting). This is an indicator for users who have opted out of ad tracking on their app and/or device. The absence of uoo in the tag is interpreted as an implicit opt-in (ie. not opted out). Nielsen offers an opt out from DAR measurement as described in the Nielsen privacy policy. Nielsen requires each application that contains active Nielsen measurement software to disclose that measurement software is included in that app, and provide access to an opt out mechanism: 0 = not-opted-out, 1 = opt-out | ✔ | ✔ | 0 , 1
|
publisher_user_id | Publisher-specific (first party) user ID (must remain persistent indefinitely. | ✔ required for publishers |
✔ required for publishers |
ed36968977606872e4312943c218568123786342
| |
publisher_name | pub | This is a Nielsen-supplied value representing the publisher of the content where the ad was served. | ✔ | ✔ required for publishers |
HOO
|
provider_user_id | Provider-specific device ID (must remain persistent indefinitely, must match ID in user mapping file, no collisions). | ✔ required for providers |
A769C2B-3CBD-5784-852F-C57875CC9D91A
| ||
provider_name | prov | Name of the provider supplying the data to Nielsen. | ✔ required for providers |
Provider 123
| |
tms_id | c36 | Gracenote program ID | ✔ | EP019890770017
| |
gracenote_ch_id | gc_id | Gracenote channel ID | ✔ | 123456
| |
app_name | c42=provapn | This is a publisher supplied value, passed either directly or via the platform provider, which represents the name of the app where the user was exposed to the ad. A separate app name will be provided for production use. Please request the app name from your Nielsen representative. | ✔ | hoolivideo
| |
program_name | c43 | This is a publisher supplied value, passed either directly or via the provider, which represents the program name of the content where the user was exposed to the ad. It is critical that these values are formatted and passed consistently. These values should be URL encoded. | ✔ if tms_id not provided |
Name Of TV Show S06+<S06:E13>
| |
channel_name | ch_name | This is a publisher-supplied value, passed either directly or via the provider, which represents the name of the channel where the user was exposed to the ad. This value should be URL encoded. | ✔ if tms_id not provided |
abc
| |
publisher_genre | c44=provcg | This is a publisher-supplied value which represents the genre of the content where the user was exposed to the ad. In case multiple genre values are present, delimited values can be passed string in order of relevance. It is critical that these values are formatted and passed consistently. These values should be URL encoded. | ✔ if tms_id not provided |
<drama>+<comedy>
| |
program_type | c45=provgencls | TThis is a publisher-supplied value which distinguishes between television and movie content. One of the following two fixed string values (“television” or “movie”) should be passed, depending on the combination being represented. | ✔ if tms_id not provided |
television , movie
| |
os_group | c7 | Operating system of device | Preferred | Preferred | IOS , ANDROID , NA
|
device_group | c8=devgrp | This is the device type where the user was exposed to the ad. Nielsen relies on both the c8 and c10 values to make platform determination; these values must be consistently populated. If c8 or c10 are not present in the tag, then Nielsen collections will infer the device and platform based on the user agent present in the tag. If one of the below values cannot be determined, then the parameter should not be included in the call or should be left empty. | ✔ | ✔ | See #Device Group |
device_platform | c10=plt | Platform name | ✔ | ✔ | OTT , MBL , DSK
|
intid | Single ID assigned per integration provided by Nielsen | ✔ | ✔ | abc123abc123abc123abc123
| |
app_id | c13=asid | Server App ID provided by Nielsen | ✔ | ✔ | AB57421Z-XXXX-YYYY-8343-FJQBJ26E44NT
|
timestamp | Server Unix time in milliseconds (UTC) when exposure occurs | ✔ | ✔ | 1548395046744
| |
ip_address | Plain-text IP address | ✔ | ✔ | 86.100.256.123
| |
device_useragent | Client-device user agent string | ✔ | ✔ | Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) hrome/84.0.4147.125 Safari/537.36
|
Email Normalization
The below procedures should be performed before hashing emails:
- remove all leading and trailing whitespace
- force lowercase
- for
@gmail.com
addresses only: - remove dots
- remove + suffix, including sign
Example: Art.Nielsen+JR@gmail.com
→ artnielsen@gmail.com
Device Group
This is the device type where the user was exposed to the ad. Nielsen relies on both the c8 and c10 values to make platform determination; these values must be consistently populated. If c8 or c10 are not present in the tag, then Nielsen collections will infer the device and platform based on the user agent present in the tag. If one of the below values cannot be determined, then the parameter should not be included in the call or should be left empty.
Valid values for connected devices are as follows:
- STV (Smart TVs)
- STB (Set-top boxes)
- RKU (Roku devices, excluding SmartTVs)
- APL (Apple devices)
- AMN (Amazon devices, excluding SmartTVs)
- GGL (Google devices, excluding SmartTVs)
- XBX (Xbox devices)
- PSX (PlayStation devices)
- DVD (BluRay & DVD player devices)
Device Group | Include | Exclude |
---|---|---|
"APL" (Apple devices) | Apple TV | Desktop (use DSK), Tablet (TAB), Mobile (PHN) |
"AMN" | STB | Smart TV (STV), Tablet (TAB), Mobile (PHN), Desktop (DSK) |
Note: For OS, “Android” and “iOS” only applicable for Mobile and Tablet devices