Digital Measurement SEI Ad Exposure: Difference between revisions
From Engineering Client Portal
(6 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}} | {{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Ad Ratings}} {{CurrentBreadcrumb}} | ||
This document outlines the required specification for facilitating Nielsen ONE advertising measurement, Digital Ad Ratings (DAR) measurement, Ad Effectiveness (MTA, Lift, etc.), and Activation products leveraging the Single Endpoint integration (SEI). Integration specifications for other Nielsen products (DCR, DTVR, etc.) via SEI are available separately. | This document outlines the required specification for facilitating Nielsen ONE advertising measurement, Digital Ad Ratings (DAR) measurement, Ad Effectiveness (MTA, Lift, etc.), and Activation products leveraging the Single Endpoint integration (SEI). Integration specifications for other Nielsen products (DCR, DTVR, etc.) via SEI are available separately. | ||
Line 5: | Line 5: | ||
The Single Endpoint integration contains two components: | The Single Endpoint integration contains two components: | ||
# '''Exposure File''' transmission to Nielsen with event level data shared via a Server-to-Server (S2S) method. This S2S file transfer supplies event data and related campaign, study, and user metadata required for facilitating measurement. | # '''Exposure File'''- the specifications of which are described in this document for the transmission to Nielsen with event level data shared via a Server-to-Server (S2S) method. This S2S file transfer supplies event data and related campaign, study, and user metadata required for facilitating measurement. | ||
# '''Audit | # '''Audit Beacon'''- (implementation details available here: [[Digital Measurement Ads Audit Beacon]]) are HTTPS requests that emanate from the end-user device at a minimum of once per Session (uninterrupted user experience with gaps shorter than 30 minutes, or as mutually agreed upon). The Audit Ping provides Nielsen the ability to 1) validate traffic volume 2) provide a signal that Nielsen meters can detect for participating Nielsen panelists. | ||
=== Ad Measurement Considerations === | === Ad Measurement Considerations === | ||
Line 113: | Line 113: | ||
} | } | ||
</syntaxhighlight> | </syntaxhighlight> | ||
The manifest contains a complete list of all files provided for a given period and split, as well as a meta data (a.k.a. header) which should include the following attributes: | The manifest contains a complete list of all files provided for a given period and split, as well as a meta data (a.k.a. header) which should include the following attributes: | ||
{| class="wikitable" | {| class="wikitable" | ||
Line 181: | Line 183: | ||
|'''Format / Example''' | |'''Format / Example''' | ||
|- | |- | ||
| colspan="2" | | | colspan="2" |sessionid | ||
| | |Unique, client generated value that represents the start of a user session. “Session” is defined as continuous (flexible) interaction with an application that may span multiple streams. | ||
|Yes | |Yes | ||
|Format: alphanumeric | | | ||
Format: alphanumeric | |||
Example: | Example: Random GUID: <code>70fa265f-5d49-4af7-ba9e-5e9da416bf78</code> | ||
|- | |- | ||
| colspan="2" | | | colspan="2" |ad | ||
| | |Array that contains advertisement-related parameters indented below | ||
|Required | |||
| | |||
Format: | |||
<syntaxhighlight lang="JSON"> | |||
"viewedads": | |||
[ | |||
{ | |||
"dar_url":"http://secure-gl.imr...", | |||
"publisher_name":"Publisher 123", | |||
... | |||
} | |||
] | |||
</syntaxhighlight> | |||
|- | |||
|{ | |||
|dar_url | |||
|The DAR url for the specific Nielsen campaign to be tracked. In cases of 3rd party DAR urls, this url should be intercepted and unaltered by the publisher/provider | |||
|Yes | |Yes | ||
| | | | ||
Example: | |||
<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> | |||
|- | |- | ||
| | | | ||
| | |publisher_name | ||
|Name of the publisher where the ad or content is being served. | |||
|Yes | |Yes | ||
| | | | ||
Example: | |||
Example: | <code>Publisher 123</code> | ||
|- | |- | ||
| | | | ||
| | |publisher_user_id | ||
| | |Publisher-specific (first party) user ID (should remain persistent). | ||
|Yes | |Yes | ||
| | | | ||
Example: | |||
Example: | <code>ed36968977606872e4312943c218568123786342</code> | ||
|- | |- | ||
| | | | ||
| | |provider_name | ||
| | |Name of the provider supplying the data to Nielsen. | ||
|For CTV (only for provider onboarding) | |||
| | |||
Example: | Example: | ||
<code>Provider 123</code> | |||
|- | |- | ||
| | | | ||
|provider_user_id | |||
|Provider-specific user ID (must remain persistent indefinitely) | |Provider-specific user ID (must remain persistent indefinitely) | ||
| | |For CTV (only for provider onboarding) | ||
| | | | ||
Example: | |||
Example: | <code>A769C2B-3CBD-5784-852F-C57875CC9D91A</code> | ||
|- | |- | ||
| | | | ||
|gracenote_id | |||
|Gracenote TMS ID (If available) should be passed for all telecasted content. | |Gracenote TMS ID (If available) should be passed for all telecasted content. | ||
|Required if id3 not provided | |Required if id3 not provided | ||
|Format: 14 character string. Normally leading with 2 alpha characters ('EP', 'MV', 'SH' or 'SP'), followed by 12 numbers. | | | ||
Format: 14 character string. Normally leading with 2 alpha characters ('EP', 'MV', 'SH' or 'SP'), followed by 12 numbers. | |||
Example: SH009311820022 | Example: <code>SH009311820022</code> | ||
|- | |- | ||
| | | | ||
| | |program_genre | ||
|Required | |Original broadcast time of content (if applicable) in Unix epoch timestamp format | ||
| | |Required for CTV | ||
| | |||
|- | |- | ||
| | | } | ||
| | |original_airtime | ||
| | |Gracenote TMS ID (If available) should be passed for all telecasted content. | ||
|Required for CTV | |||
|Example: <code>1531337551</code> | |||
|Required | |||
| | |||
Example: | |||
|- | |- | ||
| colspan="2" |dma | | colspan="2" |dma | ||
|Designated Market Area where viewing occurred | |Designated Market Area where viewing occurred | ||
|Yes | |Yes | ||
|501 | |<code>501<code> | ||
|- | |- | ||
| colspan="2" |device_id | | colspan="2" |device_id | ||
|Mobile Ad ID (IDFA, ADID), Connected Device ID | |Mobile Ad ID (IDFA, ADID), Connected Device ID | ||
|Yes,if | |Yes, if available | ||
|<code>A487421B-XXXX-YYYY-8343-E3BBB66E44F2</code> | |||
available | |- | ||
|A487421B-XXXX-YYYY-8343-E3BBB66E44F2 | | colspan="2" |is_device_id_hashed | ||
|If device_id is SHA-256 hashed | |||
|Yes | |||
| | |||
*<code>1</code> = hashed | |||
*<code>0</code> = else | |||
|- | |- | ||
| colspan="2" |hem_sha256 | | colspan="2" |hem_sha256 | ||
Line 312: | Line 291: | ||
Note: email normalization rules applied before hashing | Note: email normalization rules applied before hashing | ||
|Strongly Preferred | |Strongly Preferred | ||
| | |<code>671638d17df92ac6e46e3f00ad0e78f09116ca29128e93dcb53ff340abdeb2c2</code> | ||
|- | |- | ||
| colspan="2" |luid | | colspan="2" |luid | ||
|Living Unit ID - Experian Household ID | |Living Unit ID - Experian Household ID | ||
|Yes, for CTV if available | |Yes, for CTV if available | ||
| | |<code>B0EOFEDGD</code> | ||
|- | |- | ||
| colspan="2" |uoo | | colspan="2" |uoo | ||
|User opt out flag for demographic measurement | |User opt out flag for demographic measurement | ||
|Yes | |Yes | ||
|Format: integer | | | ||
Format: integer | |||
0 = not opt-out | *<code>0</code> = not opt-out | ||
*<code>1</code> = opt-out | |||
|- | |- | ||
| colspan="2" |xdua | | colspan="2" |xdua | ||
|Device HTTP User Agent string | |Device HTTP User Agent string | ||
|Yes | |Yes, or alternatives below | ||
|Format: alphanumeric | | | ||
Format: alphanumeric | |||
Example: Apple-iPhone1C2/801.293 | Example: <code>Apple-iPhone1C2/801.293</code> | ||
|- | |- | ||
| colspan="2" |xff | | colspan="2" |xff | ||
|IP address | |IP address | ||
|Yes | |Yes, or alternatives below | ||
|Format: xxx.xxx.xxx.xxx | | | ||
Format: xxx.xxx.xxx.xxx | |||
Example: <code>172.217.22.14</code> | |||
|- | |- | ||
| colspan="2" |psudo_id_sha256 | | colspan="2" |psudo_id_sha256 | ||
|Hashed Device User Agent string + IP address | |Hashed Device User Agent string + IP address | ||
|No | |No | ||
| | |<code>421c76d77563afa1914846b010bd164f395bd34c2102e5e99e0cb9cf173</code> | ||
|- | |- | ||
| colspan="5" |The following 4 parameters become mandatory if Device User Agent String (UAS) is not available | | colspan="5" |The following 4 parameters become mandatory if Device User Agent String (UAS) is not available | ||
Line 348: | Line 332: | ||
|Device platform(mobile, desktop, connected device) | |Device platform(mobile, desktop, connected device) | ||
|Required if no UAS | |Required if no UAS | ||
|DSK, MBL, OTT | |<code>DSK</code>, <code>MBL</code>, <code>OTT</code> | ||
|- | |- | ||
| colspan="2" |device_type | | colspan="2" |device_type | ||
|Device type for connected devices | |Device type for connected devices | ||
|Required if no UAS | |Required if no UAS | ||
|AMN, APL, DVD, GGL, PSX, RKU, STB, STV, XBX | |<code>AMN, <code>APL</code>, <code>DVD</code>, <code>GGL</code>, <code>PSX</code>, <code>RKU</code>, <code>STB</code>, <code>STV</code>, <code>XBX</code> | ||
|- | |- | ||
| colspan="2" |os_group | | colspan="2" |os_group | ||
|Operating system of mobile devices. All other device should be NA | |Operating system of mobile devices. All other device should be NA | ||
|Required if no UAS | |Required if no UAS | ||
|IOS, DROID, NA | |<code>IOS</code>, <code>DROID</code>, <code>NA</code> | ||
|- | |- | ||
| colspan="2" |device_group | | colspan="2" |device_group | ||
|Type of device: phone, tablet, desktop, set top box (CTV or OTT), unknown | |Type of device: phone, tablet, desktop, set top box (CTV or OTT), unknown | ||
|Required if no UAS | |Required if no UAS | ||
|DSK, PHN, TAB, STV, DVD, PMP, OTHER, STB, XBX, PSX, AMN, APL, GGL, RKU, UNWN | |<code>DSK, <code>PHN</code>, <code>TAB</code>, <code>STV</code>, <code>DVD</code>, <code>PMP</code>, <code>OTHER</code>, <code>STB</code>, <code>XBX</code>, <code>PSX</code>, <code>AMN</code>, <code>APL</code>, <code>GGL</code>, <code>RKU</code>, <code>UNWN</code> | ||
|- | |- | ||
| colspan="5" |The following 4 parameters become mandatory if IP Address is not available | | colspan="5" |The following 4 parameters become mandatory if IP Address is not available | ||
Line 370: | Line 354: | ||
|Flag indicating IAB bot rule if IP address present in IAB bot list | |Flag indicating IAB bot rule if IP address present in IAB bot list | ||
|Required if no IP | |Required if no IP | ||
|Format: integer | | | ||
Format: integer | |||
0 = not bot | *<code>0</code> = not bot | ||
*<code>1</code> = bot | |||
|- | |- | ||
| colspan="2" |zip_code | | colspan="2" |zip_code | ||
|ZIP code where viewing occurred | |ZIP code where viewing occurred | ||
|Required if no IP | |Required if no IP | ||
|10001 | |<code>10001</code> | ||
|- | |- | ||
| colspan="2" |country | | colspan="2" |country | ||
|Country ISO 3166 ALPHA-2 | |Country ISO 3166 ALPHA-2 | ||
| | |Preferred; required if no IP | ||
|US, CA, etc. | |<code>US</code>, <code>CA</code>, etc. | ||
|} | |} | ||
Note: All parameters are case sensitive. | Note: All parameters are case sensitive. | ||
[[Category:Digital]] | [[Category:Digital]] |
Latest revision as of 16:59, 20 November 2024
This document outlines the required specification for facilitating Nielsen ONE advertising measurement, Digital Ad Ratings (DAR) measurement, Ad Effectiveness (MTA, Lift, etc.), and Activation products leveraging the Single Endpoint integration (SEI). Integration specifications for other Nielsen products (DCR, DTVR, etc.) via SEI are available separately.
The Single Endpoint integration contains two components:
- Exposure File- the specifications of which are described in this document for the transmission to Nielsen with event level data shared via a Server-to-Server (S2S) method. This S2S file transfer supplies event data and related campaign, study, and user metadata required for facilitating measurement.
- Audit Beacon- (implementation details available here: Digital Measurement Ads Audit Beacon) are HTTPS requests that emanate from the end-user device at a minimum of once per Session (uninterrupted user experience with gaps shorter than 30 minutes, or as mutually agreed upon). The Audit Ping provides Nielsen the ability to 1) validate traffic volume 2) provide a signal that Nielsen meters can detect for participating Nielsen panelists.
Ad Measurement Considerations
Nielsen ad campaign setup is required using the Campaign Management Interface (CMI) tool or Tagging API for each campaign where Nielsen reporting is expected - this applies to new or current Nielsen clients transitioning from standard client-device-fired pixel tags to Single Endpoint style.
Nielsen ad pixel tags should not directly fire for any exposures already included in the Exposure File after the testing period. Third-party Nielsen pixel tags should be intercepted, suppressed, and included in a server file transfer with all associated information.
The Audit Ping is required for facilitating MRC Accredited measurement.
S3 Bucket and Prefix Naming Convention
useast1-nlsn-w-dig-sei-<partnerid>-feeds-<env>/<filetype>/<split>/yyyy/mm/dd/hh/<object>
Name | Description |
---|---|
partnerid | Abbreviation provided by Nielsen for each provider or publisher |
env | “test” or “prod” |
filetype | exposure, dcr-exposure, dar-exposure, audio-exposure, etc., where:
|
split | a separate data split, can be by platform (ex.: ios, browser, android, ctv), by country (us, ca, jp, etc.), by publisher, by team, etc. or “all” (if data is provided in one split). |
yyyy/mm/dd/hh |
|
S3 Bucket and Prefix Naming Convention
<partnerid>_<filetype>_<intid>_<appid>_<starttime>_<endtime>.[parquet|json]
Name | Description |
---|---|
partnerid | Abbreviation provided by Nielsen for each provider or publisher |
filetype | exposure, dcr-exposure, dar-exposure, audio-exposure, etc., where:
|
initid | integration id: unique identifier provided by Nielsen |
appid | Nielsen-provided server application identifier |
starttime | start date and hour of the data in the file in UTC
|
endtime | end date and hour (not inclusive) of the data in the file in UTC
|
Success File
Empty _SUCCESS file should be provided to indicate that data delivery for a particular hour and split is completed (even if there is no data for that particular hour and split).
Manifest File
A manifest should be provided which contains metadata related to the uploaded file(s). The manifest is a text file in json format that implements the AWS unload manifest file format. It has the same name as the data file, but has the _manifest
suffix.
Example:
{
"entries": [
{"url":"s3://bucket/prefix/0000_object_00.snappy.parquet", "mandatory":true},
{"url":"s3://bucket/prefix/0001_object_00.snappy.parquet", "mandatory":true},
{"url":"s3://bucket/prefix/0002_object_00.snappy.parquet", "mandatory":true},
{"url":"s3://bucket/prefix/0003_object_00.snappy.parquet", "mandatory":true}
],
"meta": {
"schema_version": "S2SV1.7.0",
"accreditation_status": "0",
"start_time": "1710154800",
"end_time": "1710158399",
"record_count": 55
}
}
The manifest contains a complete list of all files provided for a given period and split, as well as a meta data (a.k.a. header) which should include the following attributes:
Parameter | Description | Require | Specified | Format / Example | Type |
schema_version | Schema Version | Yes | Nielsen | S2SV1.7.0
|
String |
accreditation_status | Accreditation Status | No | Client | MRC = 1
|
String |
data_start_time | Data Start Time (min) | Yes | Client | Format:32-bit unsigned int Unix time in seconds | String |
data_end_time | Data Start Time (max) | Yes | Client | Format:32-bit unsigned int Unix time in seconds | String |
record_count | Number of records in data file | Yes | Client | Example: 31337
|
Number |
Data delivery example for hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):
useast1-nlsn-w-dig-sei-acme-feeds-prod/dar-exposure/ios/2022/05/25/11/acme_dtvr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2024031111_2024031112_0000.json
useast1-nlsn-w-dig-sei-acme-feeds-prod/dar-exposure/ios/2022/05/25/11/acme_dtvr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2024031111_2024031112_0001.json
useast1-nlsn-w-dig-sei-acme-feeds-prod/dar-exposure/ios/2022/05/25/11/acme_dtvr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2024031111_2024031112_0002.json
useast1-nlsn-w-dig-sei-acme-feeds-prod/dar-exposure/ios/2022/05/25/11/acme_dtvr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2024031111_2024031112_0003.json
useast1-nlsn-w-dig-sei-acme-feeds-prod/dar-exposure/ios/2022/05/25/11/acme_dtvr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2024031111_2024031112_manifest
useast1-nlsn-w-dig-sei-acme-feeds-prod/dar-exposure/ios/2022/05/25/11/_SUCCESS
SLA
The files must be delivered into the proper S3 bucket within 3 hours of the start of that hourly viewing file interval.For example files from 1:00 AM to 2:00 AM must be delivered before 4 AM.
Schema Parameter Definitions
Parameter | Description | Required | Format / Example | |
sessionid | Unique, client generated value that represents the start of a user session. “Session” is defined as continuous (flexible) interaction with an application that may span multiple streams. | Yes |
Format: alphanumeric Example: Random GUID: | |
ad | Array that contains advertisement-related parameters indented below | Required |
Format: "viewedads":
[
{
"dar_url":"http://secure-gl.imr...",
"publisher_name":"Publisher 123",
...
}
]
| |
{ | dar_url | The DAR url for the specific Nielsen campaign to be tracked. In cases of 3rd party DAR urls, this url should be intercepted and unaltered by the publisher/provider | Yes | |
publisher_name | Name of the publisher where the ad or content is being served. | Yes |
Example:
| |
publisher_user_id | Publisher-specific (first party) user ID (should remain persistent). | Yes |
Example:
| |
provider_name | Name of the provider supplying the data to Nielsen. | For CTV (only for provider onboarding) |
Example:
| |
provider_user_id | Provider-specific user ID (must remain persistent indefinitely) | For CTV (only for provider onboarding) |
Example:
| |
gracenote_id | Gracenote TMS ID (If available) should be passed for all telecasted content. | Required if id3 not provided |
Format: 14 character string. Normally leading with 2 alpha characters ('EP', 'MV', 'SH' or 'SP'), followed by 12 numbers. Example: | |
program_genre | Original broadcast time of content (if applicable) in Unix epoch timestamp format | Required for CTV | ||
} | original_airtime | Gracenote TMS ID (If available) should be passed for all telecasted content. | Required for CTV | Example: 1531337551
|
dma | Designated Market Area where viewing occurred | Yes | 501 | |
device_id | Mobile Ad ID (IDFA, ADID), Connected Device ID | Yes, if available | A487421B-XXXX-YYYY-8343-E3BBB66E44F2
| |
is_device_id_hashed | If device_id is SHA-256 hashed | Yes |
| |
hem_sha256 | SHA-256 hashed email
Note: email normalization rules applied before hashing |
Strongly Preferred | 671638d17df92ac6e46e3f00ad0e78f09116ca29128e93dcb53ff340abdeb2c2
| |
luid | Living Unit ID - Experian Household ID | Yes, for CTV if available | B0EOFEDGD
| |
uoo | User opt out flag for demographic measurement | Yes |
Format: integer
| |
xdua | Device HTTP User Agent string | Yes, or alternatives below |
Format: alphanumeric Example: | |
xff | IP address | Yes, or alternatives below |
Format: xxx.xxx.xxx.xxx Example: | |
psudo_id_sha256 | Hashed Device User Agent string + IP address | No | 421c76d77563afa1914846b010bd164f395bd34c2102e5e99e0cb9cf173
| |
The following 4 parameters become mandatory if Device User Agent String (UAS) is not available | ||||
device_platform | Device platform(mobile, desktop, connected device) | Required if no UAS | DSK , MBL , OTT
| |
device_type | Device type for connected devices | Required if no UAS | AMN, | |
os_group | Operating system of mobile devices. All other device should be NA | Required if no UAS | IOS , DROID , NA
| |
device_group | Type of device: phone, tablet, desktop, set top box (CTV or OTT), unknown | Required if no UAS | DSK, | |
The following 4 parameters become mandatory if IP Address is not available | ||||
robotic_flag | Flag indicating IAB bot rule if IP address present in IAB bot list | Required if no IP |
Format: integer
| |
zip_code | ZIP code where viewing occurred | Required if no IP | 10001
| |
country | Country ISO 3166 ALPHA-2 | Preferred; required if no IP | US , CA , etc.
|
Note: All parameters are case sensitive.