Digital Measurement SEI Ad Exposure: Difference between revisions

From Engineering Client Portal
 
(17 intermediate revisions by 2 users 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 Ping''' (not required for ad effectiveness) 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.
# '''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 16: Line 16:


=== S3 Bucket and Prefix Naming Convention ===
=== S3 Bucket and Prefix Naming Convention ===
<code>useast1-nlsn-w-dig-sei-<partnerid>-feeds-<env>/<filetype>/<split>/yyyy/mm/dd/hh/<object></code>
<code>useast1-nlsn-w-dig-sei-<'''partnerid'''>-feeds-<'''env'''>/<'''filetype'''>/<'''split'''>/'''yyyy'''/'''mm'''/'''dd'''/'''hh'''/<object></code>
{| class="wikitable"
{| class="wikitable"
!'''Name'''
!'''Name'''
Line 31: Line 31:


* '''exposure''' is reserved for multi-product files
* '''exposure''' is reserved for multi-product files
* '''<product>-exposure''' is for single product files, where '''<product>''' is '''[dar|dcr|dtvr|ctvc|audio]'''
* '''<product>-exposure''' is for single product files, where '''<product>''' is '''[<code>dar</code>|<code>dcr</code>|<code>dtvr</code>|<code>ctvc</code>|<code>audio</code>]'''
|-
|-
|split
|split
Line 45: Line 45:


=== S3 Bucket and Prefix Naming Convention ===
=== S3 Bucket and Prefix Naming Convention ===
<partnerid>_<filetype>_<intid>_<appid>_<starttime>_<endtime>.[json|parquet]
<code><'''partnerid'''>_<'''filetype'''>_<'''intid'''>_<'''appid'''>_<'''starttime'''>_<'''endtime'''>.[parquet|json]</code>
{| class="wikitable"
{| class="wikitable"
|'''Name'''
!'''Name'''
|'''Description'''
!'''Description'''
|-
|-
|partnerid
|partnerid
Line 57: Line 57:


* '''exposure''' is reserved for multi-product files
* '''exposure''' is reserved for multi-product files
* '''<product>-exposure''' is for single product files, where '''<product>''' is '''[dar|dcr|dtvr|ctvc|audio]'''
* '''<product>-exposure''' is for single product files, where '''<product>''' is '''[<code>dar</code>|<code>dcr</code>|<code>dtvr</code>|<code>ctvc</code>|<code>audio</code>]'''
|-
|-
|initid
|initid
Line 80: Line 80:


=== Manifest File ===
=== 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose AWS unload manifest file] format. It has the same name as the data file, but has the '''_manifest''' suffix.
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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose AWS unload manifest file] format. It has the same name as the data file, but has the <code>'''_manifest'''</code> suffix.


'''Example:'''
'''Example:'''
{
<syntaxhighlight lang="JSON">
{


    "entries": [
    "entries": [
Line 110: Line 111:


    }
    }
}
</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 125: Line 128:
|Yes
|Yes
|Nielsen
|Nielsen
|S2SV1.7.0
|<code>S2SV1.7.0</code>
|String
|String
|-
|-
Line 132: Line 135:
|No
|No
|Client
|Client
|MRC = 1
|<code> MRC = 1</code>
|String
|String
|-
|-
Line 153: Line 156:
|Yes
|Yes
|Client
|Client
|Example: 31337
|Example: <code>31337</code>
|Number
|Number
|}
|}
'''Data delivery example for hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):'''
'''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
<code>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</code>
 
<code>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</code>


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
<code>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</code>


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
<code>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</code>


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
<code>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</code>


useast1-nlsn-w-dig-sei-acme-feeds-prod/dar-exposure/ios/2022/05/25/11/_SUCCESS
<code>useast1-nlsn-w-dig-sei-acme-feeds-prod/dar-exposure/ios/2022/05/25/11/_SUCCESS</code>


= SLA =
= 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.
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.
= Accuracy of Measurement =
The reported “wall clock” time of viewing needs to be within 25 seconds of the actual viewing time.
The reported content “reference” time needs to match the actual content that was played out with plus/minus 10 seconds ''(for clarity: start and end times can each be off by up to 10 seconds, so the combined under/over reporting for each individual viewing segment should be no greater than 20 seconds)''
= CTV, Mirroring, and Casting =
For apps native to the OTT device ''(i.e. downloading and viewing a streaming app to an Apple TV)'', audit ping should fire from the OTT device, and Viewing data should reside in OTT Viewing file.
[[File:Phone Playback.png|thumb]]
For mirroring, where video playback occurs on the mobile device and OTT device, only one Viewing file row is necessary where, if possible to determine, set: "secondscr":"MIR" and include in respective mobile platform Viewing file.
For a casting scenario where content is controlled via the mobile device, but displayed only on the OTT device such as an AppleTV or Chromecast, an audit ping must fire from the mobile device before the casting occurs and at the end of playback from the mobile device only. Viewing data resides in the respective mobile platform Viewing file.
{ ... "sessionid":"ABC","streamid":"DEF","position":[{"referencestart":"xxxxxxx123","referenceend":"xxxxxxx183","playheadstart":"0","playheadend":"60"},{"referencestart":"xxxxxxx243","referenceend":"xxxxxxx303","playheadstart":"120","playheadend":"180"}]}
{ ... "sessionid":"ABC","streamid":"DEF","position":[{"referencestart":"xxxxxxx183","referenceend":"xxxxxxx243","playheadstart":"60","playheadend":"120"}],"secondscr":"OTT"}


== Schema Parameter Definitions ==
== Schema Parameter Definitions ==
Line 193: Line 182:
|'''Required'''
|'''Required'''
|'''Format / Example'''
|'''Format / Example'''
|-
| colspan="2" |apn
|Application name
|Yes
|Format: alphanumeric
Example: BestAppIOS
|-
| colspan="2" |apv
|Application version
|Yes
|Format: alphanumeric
Example: 21.5
|-
|-
| colspan="2" |sessionid
| 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.
|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: Random GUID: ce6c1c95-de3e-431e-b11e-77…
Example: Random GUID: <code>70fa265f-5d49-4af7-ba9e-5e9da416bf78</code>
|-
|-
| colspan="2" |streamid
| colspan="2" |ad
|ID for every new instance of exposure to a different asset
|Array that contains advertisement-related parameters indented below
|Yes, if no sessionid
|Required
|Format: alphanumeric
|
 
Format:  
Example: Random GUID: d7a909f1-5e77-4af7-8a9b-f2…
<syntaxhighlight lang="JSON">
"viewedads":  
[
  {
      "dar_url":"http://secure-gl.imr...",
      "publisher_name":"Publisher 123",
      ...
  }
]
</syntaxhighlight>
|-
|-
| colspan="2" |streamended
|{
|Stream is known to have ended in this file
|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
|Format: integer,
|
 
Example:  
Example: 1 (stream continues in subsequent file), 2 (stream closed)
<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>
|-
|-
| colspan="2" |publisher_user_id
|
|Publisher-specific user ID (must remain persistent indefinitely)
|publisher_name
|No
|Name of the publisher where the ad or content is being served.
|Format: alphanumeric
 
Example: Salted, hashed user ID:
 
8f434346648f6b96d9dda901c5…
|-
| colspan="2" |provider_user_id
|Provider-specific user ID (must remain persistent indefinitely)
|No
|Format: alphanumeric
 
Example: Salted, hashed user ID:
 
2cf24dba5fb0a30e26e83b2ab9…
|-
| colspan="2" |assetid
|In-house id used for a video asset (TMS ID if available)
|Yes
|Yes
|Format: alphanumeric
|
 
Example: VID123456789
|-
| colspan="2" |nielsen_id3_tag
|Encrypted Nielsen ID3 Tag. Contains SID (Source Identifier) codes (PC - Program Content  &  FD - Final Distributor).
|Optional
|Format: alphanumeric;
 
Example:  
Example:  
 
<code>Publisher 123</code>
www.nielsen.com/0UQ1mB-DRZMCTQ3Fr9zLjw==/EnVp4bRmgPx7KDNctoTVpQ==/AAcCEP7hk_DDqQuocAM3JRHB7raS8j8yKAM2b3Na2F9Po4yWm87KA6Ubefb3Hb6Fj_GOijXnlXw1yzgKzpc0J-cCEFEQqjGD2HHpSj5upGJyz6V0lx5j64rfFd4jyv3cxHGz_UKb-yJdHKTHKB11Iv_LJls1P1xbNT9iOo8=/29100/36900/00
 
Note: Only Data Tags should be included, INFO Tags should not.
 
INFO Tag is characterized by the following CID prefix: X100zdCIGeIlgZnkYj6UvQ==
 
Example INFO Tag (not desired):
 
www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00
|-
|-
| colspan="2" |gracenote_id
|
|Gracenote TMS ID (If available) should be passed for all telecasted content.
|publisher_user_id
|Required if id3 not provided
|Publisher-specific (first party) user ID (should remain persistent).
|Format: 14 character string. Normally leading with 2 alpha characters ('EP', 'MV', 'SH' or 'SP'), followed by 12 numbers.
 
Example: SH009311820022
|-
| colspan="2" |station_id
|GraceNote station ID that identifies the station
|Required if id3 not provided
|Format: alphanumeric
|-
| colspan="2" |program_name
|Name of program
|Required if id3 not provided
|Format: alphanumeric, Max 25 characters; no special characters.
 
Example: Nightly News
 
See below for more specific guidance on Program Name.
|-
| colspan="2" |network_affiliate
|Network affiliation of a station
|Required if id3 not provided
|Format: alphanumeric
 
Example: xyz
|-
| colspan="2" |channel_id
|ID of channel
|Required if id3 not provided
|Format: integer
|-
| colspan="2" |channel_name
|Name of channel
|Required if id3 not provided
|Format: alphanumeric
|-
| colspan="2" |callsign
|FCC assigned unique identifier for a transmitter station
|Required if id3 not provided
|Format: alphanumeric
|-
| colspan="2" |ad_load_flag
|linear or dynamic ad load
|Yes
|Yes
|Format: integer;
|
 
Example:  
0 = Default / Unknown
<code>ed36968977606872e4312943c218568123786342</code>
 
1 = linear ad load
 
2 = dynamic ad load
|-
|-
| colspan="2" |ad_support_flag
|
|Intended method of monetizing the content
|provider_name
|Yes
|Name of the provider supplying the data to Nielsen.
|Format: integer;
|For CTV (only for provider onboarding)
 
|
0 = (no ad's),
Example:
 
<code>Provider 123</code>
1 = (content is supported by ad’s),
 
2 = (not known)
 
Note: set to "1" if content ad support was intended but did not occur
|-
|-
| colspan="2" |position
|
|Array of contiguous content viewing.
|provider_user_id
 
|Provider-specific user ID (must remain persistent indefinitely)
For viewing gaps < than 1 second, the gap can be smoothed over
|For CTV (only for provider onboarding)
 
|
See below for additional details on position array parameters
Example:  
|Yes
<code>A769C2B-3CBD-5784-852F-C57875CC9D91A</code>
|Format:  
 
"position": [{
 
 "referencestart":"[timestamp]",
 
 "referenceend":"[timestamp]",
 
 "playheadstart":"[playhead position]",
 
 "playheadend":"[playhead position]"
 
}]
|-
| colspan="2" |dma
|Designated Market Area where viewing occurred
|Yes
|501
|-
|{
|referencestart
|Wall clock reference start time
|Yes
|Format: Unix timestamp in 32-bit unsigned int in seconds
 
Example: 1577858505
|-
|-
|
|
|referenceend
|gracenote_id
|Wall clock reference end time
|Gracenote TMS ID (If available) should be passed for all telecasted content.
|Yes
|Required if id3 not provided
|Format: Unix timestamp in 32-bit unsigned int in seconds
 
Example: 1577858775
|-
|
|
|playheadstart
Format: 14 character string. Normally leading with 2 alpha characters ('EP', 'MV', 'SH' or 'SP'), followed by 12 numbers.
|Content position start time
|Yes
|Format: Unix timestamp in 32-bit unsigned int in seconds or integer indexed from 0 (typical for VOD)
 
Example: 1577858515
|-
|<nowiki>}</nowiki>
|playheadend
|Content position end time
|Yes
|Format: Unix timestamp in 32-bit unsigned int in seconds or integer indexed from 0 (typical for VOD)


Example: 1577858785
Example: <code>SH009311820022</code>
|-
| colspan="2" |viewedads
|Array of ads viewed by client.
 
See below for additional details on position array parameters
|Yes
|Format:
 
"viewedads": [{"adpod":"0","adposition":"0","adid":"0","isdarid":"0","adstart":"utc","adend":"utc","advisible":"0","adfocus":"0","adaudio":"0"}]
|-
|{
|adpod
|AdPod sequence number.
 
Increment for each AdPod. If the same AdPod is played out twice (due to rewind), still increment the AdPod sequence to reflect the sequence the AdPods are played.
|Yes
|Format: Integer
 
Example: 2
|-
|-
|
|
|adposition
|program_genre
|Ad sequence number.
|Original broadcast time of content (if applicable) in Unix epoch timestamp format
 
|Required for CTV
Increment each time a new Ad is encountered. If the same Ad is played out twice (due to rewind), still increment the Ad sequence to reflect the sequence the Ads are played
|Yes
|Format: Integer
 
Example: 1
|-
|
|
|adid
|The unique identifier for this Ad
|No
|Format: alphanumeric
In-house AdId, Industry AdID, AdNetwork ID or DAR placement ID
|-
|-
|
| }
|isdarid
|original_airtime
|Is the AdId being passed a Nielsen DAR placement ID
|Gracenote TMS ID (If available) should be passed for all telecasted content.
|Required if AdID
|Required for CTV
|Format: integer
|Example: <code>1531337551</code>


0 = is NOT DAR ID; 1 = is a DAR ID
|-
|-
|
| colspan="2" |dma
|adstart
|Designated Market Area where viewing occurred
|Wall clock reference start time
|Yes
|Yes
|Format: Unix timestamp in 32-bit unsigned int in seconds
|<code>501<code>
|-
|<nowiki>}</nowiki>
|adend
|Wall clock reference end time
|Yes
|Format: Unix timestamp in 32-bit unsigned int in seconds
|-
|-
| 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 465: Line 291:
Note: email normalization rules applied before hashing
Note: email normalization rules applied before hashing
|Strongly Preferred
|Strongly Preferred
|55C06A30DAA5D5F382FDEB8C702EC57875CC9D91A7C78BB620053FD81DC…
|<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
|B0EOFEDgD
|<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, 1 = 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
|421c76d77563afa1914846b010bd164f395bd34c2102e5e99e0cb9cf173…
|<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 501: 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 523: 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, 1 = 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
|Required if no IP
|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

Engineering Portal / Digital / Digital Ad Ratings / Digital Measurement SEI Ad Exposure

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:

  1. 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.
  2. 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:
  • exposure is reserved for multi-product files
  • <product>-exposure is for single product files, where <product> is [dar|dcr|dtvr|ctvc|audio]
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
  • yyyy - year
  • mm - month
  • dd - date padded with 0 example 01, 02,..., 31
  • hh - hour padded with 0 example 00, 02,..., 23

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:
  • exposure is reserved for multi-product files
  • <product>-exposure is for single product files, where <product> is [dar|dcr|dtvr|ctvc|audio]
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
  • Example format: yyyymmddhh
endtime end date and hour (not inclusive)  of the data in the file in UTC
  • Example format: yyyymmddhh

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: 70fa265f-5d49-4af7-ba9e-5e9da416bf78

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

Example: 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

publisher_name Name of the publisher where the ad or content is being served. Yes

Example: Publisher 123

publisher_user_id Publisher-specific (first party) user ID (should remain persistent). Yes

Example: ed36968977606872e4312943c218568123786342

provider_name Name of the provider supplying the data to Nielsen. For CTV (only for provider onboarding)

Example: Provider 123

provider_user_id Provider-specific user ID (must remain persistent indefinitely) For CTV (only for provider onboarding)

Example: A769C2B-3CBD-5784-852F-C57875CC9D91A

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: SH009311820022

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
  • 1 = hashed
  • 0 = else
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

  • 0 = not opt-out
  • 1 = opt-out
xdua Device HTTP User Agent string Yes, or alternatives below

Format: alphanumeric

Example: Apple-iPhone1C2/801.293

xff IP address Yes, or alternatives below

Format: xxx.xxx.xxx.xxx

Example: 172.217.22.14

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, APL, DVD, GGL, PSX, RKU, STB, STV, XBX
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, PHN, TAB, STV, DVD, PMP, OTHER, STB, XBX, PSX, AMN, APL, GGL, RKU, UNWN
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

  • 0 = not bot
  • 1 = bot
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.

Retrieved from "https://engineeringportal.nielsen.com/w/index.php?title=Digital_Measurement_SEI_Ad_Exposure&oldid=7120"