DAR Tag Implementation Guide and Digital Measurement SEI Streaming Content Viewing: Difference between pages

From Engineering Client Portal

(Difference between pages)
 
 
Line 1: Line 1:
{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Ad Ratings}}  {{CurrentBreadcrumb}}
{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
[[Category:Digital]]


This interface specification depicts the file schema required to supply Nielsen with response-level Viewing data in a “Server-to-Server” relationship for incorporation into the Nielsen One Content and/or Nielsen One Ads products.


== Introduction ==
== Delivery Specifications ==
Files should be delivered at a fixed cadence in a dedicated S3 bucket following the outlined in this spec prefix and object naming conventions and data formats.


Nielsen Digital Ad Ratings is a measurement platform for online advertising campaigns. The platform provides a clear view of the true audience of a campaign, including '''Reach''', '''Frequency''', and '''GRP''' statistics by audience demographic group.
* All prefix labels and file names should be lowercase except for app ids.  
* Supported format are:
** Text files with utf-8 encoding in JSON Lines format;
** Apache Parquet format with snappy compression;
* All data files have extensions to indicate the file format (.json | .parquet)
* Data file can be partitioned into multiple parts with min size of 256MB
* Data can be delivered separately in multiple splits, if needed due to organizational, technical or privacy requirements. This allows to permission s3 access separately, to process data independently and to persist data partitioned, within the limits of the SEI system


The key innovation of the platform is the inclusion of demographic data from leading web publishers, including Facebook, to attach actual user demographics to ad impressions.
=== S3 Bucket and Prefix Naming Convention ===
<code>useast1-nlsn-w-dig-sei-<'''partnerid'''>-feeds-'''<env>/<filetype>/<split>/yyyy/mm/dd/hh/<object>'''</code>
{| class="wikitable"
!'''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:


The diagram below summarizes how the Nielsen tag measures the ad campaign:
* exposure is reserved for multi-product files
# Advertiser places ads on one or more websites
* <product>-exposure is for single product files, where <product> is [dar|dcr|dtvr|ctvc|audio]
#Website displays ad to a user
|-
#Nielsen tag counts impressions and controls redirect to the Data Enrichment Provider
|split
[[File:dar-image2.png|900px]]
|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
=== Support for Other Nielsen Ad Effectiveness Products ===
|
 
* yyyy - year
The tag used for Nielsen Digital Ad Ratings is compatible for all Nielsen Ad Effectiveness products, including (but not limited to) Brand Effect Extended View, Response Effect, and Sales Effect.
* mm - month
 
* dd - date padded with 0 example 01, 02,..., 31
=== User Experience ===
* hh - hour padded with 0 example 00, 02,..., 23
|}


The tags described in this document are used only to measure audience exposure to advertisements; they do not launch a survey, and have no impact on the user experience. Typical response time for the tag is on par with industry standards and because the code executed is simple and fires after the ad loads, they are transparent to the user.
=== S3 Bucket and Prefix Naming Convention ===
 
<code><'''partnerid'''>_<'''filetype'''>_<'''intid'''>_<'''appid'''>_<'''starttime'''>_<'''endtime'''>.['''json'''|'''parquet''']</code>
For further information on survey-based products, or any other products, please contact your Client Services Manager.
{| class="wikitable"
__TOC__
!'''Name'''
== Available Tag Versions ==
!'''Description'''
 
The Nielsen Digital Ad Ratings system offers 2 basic types of ad tags
 
* '''IMAGE (1X1) Pixel'''
This is the simplest version of the tag, generally for use by clients who cannot accept JavaScript format tags or have limited options for implementation. Itincludes encryption, but does not utilize referrer masking.
 
* '''JavaScript Tag'''
This is a more complex tag which includes encryption and masking of referrer site via a script call. This Tag may also be used to measure Viewability metrics.
There may be additional functionality offered by this format in future releases as well.
* '''Ad Networks''' This tag includes additional functionality to scrape the URL of the hosting website if associated to an ad network within the Nielsen system. Keep in mind URLs captured will only be used for “site adjustment factors” and not be included in any reporting
 
<blockquote>'''NOTE''' - Both tag types support macros and are available in secure and non-secure formats. Please reach out to your Nielsen Technical Account Manager for additional information.</blockquote>
 
While the IMAGE pixels are easiest to implement, the JavaScript versions are recommended because they provide the highest level of confidentiality by masking the source of the ad from being viewable by Data Providers. Some situations may not afford use of JavaScript and in those cases, the pixel version will be recommended. Note that in many cases the referrer is cast as the ad server due to the nature of being served inside iframes, so the “masking” here is extraneous.
 
=== Tag Examples ===
 
<br>
'''IMAGE Pixel Tag''' (Static example)
<syntaxhighlight lang="javascript">
<img src="http://secure-gl.imrworldwide.com/cgi-bim/m?ci=entXXXX&at=view&rt=banner&am=3&ca=cmpXXXX&cr=&pc=plcXXXX&r=[timestamp]"
width="1" height="1" alt=""/>
</syntaxhighlight>
 
'''IMAGE Pixel Tag''' (Macro example)
<syntaxhighlight lang="javascript">
<script type="text/javascript"
src="http://secure-gl.imrworldwide.com/cgi-bin/m?ci=entXXXX&am=1&mr=1&ty=js&at=view&rt=banner&ep=1&ca=%ebuy!&cr=%ecid!&pc=%epid!&r=[timestamp]">
</script>
</syntaxhighlight>
 
'''JavaScript Tag''' (Static example)
 
<syntaxhighlight lang="javascript">
<script type="text/javascript"
src="http://secure-gl.imrworldwide.com/cgi-bim/m?ci=entXXXX&at=view&rt=banner&am=3mr=1&ty=js&ca=cmpXXXX&cr=&pc=plcXXXX&r=[timestamp]"
></script>
</syntaxhighlight>
 
'''JavaScript Tag''' (Macro example)
 
<syntaxhighlight lang="javascript">
<script type="text/javascript"
src="http://secure-gl.imrworldwide.com/cgi-bin/m?ci=entXXXX&am=1&mr=1&ty=js&at=view&rt=banner&ep=1&ca=%ebuy!&cr=%ecid!&pc=%epid!&r=[timestamp]"></
script>
</syntaxhighlight>
<br>
 
The Nielsen Digital Ad Ratings system also features the ability to record Viewability information such as: How long an Ad has been visible on the screen, and what portion on the Ad. This is an additional feature that can be purchased from your Nielsen Client Services Representative.
 
Viewability for display ads can ONLY be offered through the JavaScript tag. If you select this service, the following is an example of the tag that will be provided to you by the Nielsen Digital Implementation Team:
 
'''JavaScript with Viewability for display ads:'''
<syntaxhighlight lang="javascript">
<script type="text/javascript"
src="http://secure-gl.imrworldwide.com/cgi-bin/m?ci=entXXXX&am=1&mr=1&ty=js&at=view&rt=banner&ep=1&ca=%ebuy!&cr=%ecid!&pc=%epid!&r=[timestamp]"></
script>
</syntaxhighlight>
 
<blockquote>The above tag is just examples and should not be placed in any live site or ad server. You will be provided with tags specifically designed for your media plan/campaign or be able to download tags after creation in CMI (Campaign Management Interface)</blockquote>
 
== Standard DAR Tag ==
The DAR tag is available as a 1x1 pixel. The following pixel/tag parameters must be specified for all DAR tags, 1x1, regardless of implementation type: browser, mobile browser, mobile app or connected device.
 
{| class="wikitable"
|-
|-
! Tag Parameter
|partnerid
! Description
|Abbreviation provided by Nielsen for each provider or publisher
|-
|-
| CI
|filetype
| Client ID: 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
|exposure, dcr-exposure, dar-exposure, audio-exposure, etc., where:
|- style="background-color:#eff8ef;"
 
| AM
* '''exposure''' is reserved for multi-product files
| Ad Server: an 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
* '''<product>-exposure''' is for single product files, where '''<product>''' is '''[dar|dcr|dtvr|ctvc|audio]'''
|-
|-
| CA
|initid
| Campaign Id: this is the ID associated with your DAR campaign. Unless you are creating and managing the Nielsen campaign via the DAR Tag API, then this parameter value will always be generated from the Nielsen campaign management system. Note: often maps to a media-plan I/O Id
|integration id: unique identifier provided by Nielsen
|- style="background-color:#eff8ef;"
| CR
| Creative Id: DAR does not currently report at the creative level; can be hard coded ad server id or associated with a macro expansion
|-
|-
| PC
|appid
| Placement Id: can be generated by the ad server via macro expansion or generated by the Nielsen campaign management system. Note: often maps to one of Ad Unit Id, Line Item Id or Video Ad Id
|Nielsen-provided server application identifier
|- style="background-color:#eff8ef;"
| CE
| Site Id: the Id that identifies a publisher site that the placement needs to be mapped to. Maps into the Nielsen MarketView database. Note: can be hardcoded to a pre-registered ad server site id in the Nielsen system or a macro expansion where more than one pre-existing site ids have been made known to Nielsen
|-
|-
| R
|starttime
| Cachebuster (web): timestamp / random number. Generated by ad server
|start date and hour of the data in the file in UTC
|- style="background-color:#eff8ef;"
 
| AT
* Example format: yyyymmddhh
| Fixed value: “view”
|-
|-
| RT
|endtime
| Fixed value: “banner”
|end date and hour (not inclusive)  of the data in the file in UTC
|- style="background-color:#eff8ef;"
 
| ST
* Example format: yyyymmddhh
| Fixed value: “image”
|}
|}
<blockquote> Do not URL encode the values</blockquote>


== Additional Parameters ==
=== Success File ===
=== HEM Support (Hashed Email) ===
Empty <code>'''_SUCCESS'''</code> 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).
{| class="wikitable"
 
|-
=== Manifest File ===
! NAME
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 <code>'''_manifest'''</code> suffix.
! DESCRIPTION
! AVAILABLE TAG PARAMETERS
|-
|  style="width: 15%"| Hashed Email
| User’s email address that has been run through a hashing algorithm (e.g. SHA256, MD5, SHA1) </br> to create a unique 32-character hexadecimal string. If a client is unable to determine hashing type, they should pass using &hem_unknown parameter.
|style="width: 20%"|<code>&hem_unknown</br>&hem_sha256</br>&hem_md5</br>&hem_md5</br>&hem_sha1</code>
|}


<blockquote>Please use the parameter that matches your hashing algorithm. 
For example, if you are using sha256 to encode the email address, then use <code>hem_sha256={encrypted_value_here}</code>
</blockquote>
Example:
Example:
<syntaxhighlight lang="javascript">
<syntaxhighlight lang="JSON">
hem_sha256=tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=
{
   "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
   }
}
</syntaxhighlight>
</syntaxhighlight>


=== Unified ID ===
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"
|-
!'''Parameter'''
! NAME
!'''Description'''
! DESCRIPTION
!'''Required'''
! AVAILABLE TAG PARAMETERS
!'''Specified'''
!'''Format / Example'''
!'''Type'''
|-
|schema_version
|Schema Version
|Yes
|Nielsen
|S2SV1.7.0
|String
|-
|-
| style="width: 15%"| Unified ID 2.0
|accreditation_status
| An identifier based on a user’s verifiable PII (e.g. hashed email). UID2.0 was initially created by The Trade Desk (TTD)</br> and is now managed by Prebid.
|Accreditation Status
| &uid2
|No
|Client
|MRC = 1
|String
|-
|-
| Unified ID 2.0 Token
|data_start_time
| Encrypted Unified ID 2.0
|Data Start Time (min)
| &uid_token
|Yes
|}
|Client
 
|Format:32-bit unsigned int Unix time in seconds
Example:
|String
<syntaxhighlight lang="javascript">
uid2=MTKVpUAzwYAPnHrtfE0wlINOMzhU7UUEjjVdCdRu63k=&uid_token=AgAAAAPFR0zA5ogv/yaAPiUsAdZPsfqS8
QlDSGxAB+rr8yekFs3AjLYVk5qqqiyV2XHbSuwzHmxSlLeQeKQI1mp015jsNnpX5/xGgXldcgVz+gFnyh3T8/3agMwRmyrhCxG4oH2C7
fc48AQk2eotE7FW0ZDEYM8fD9ZxDaxFUC/OV3OuZA&
width="1" height="1" alt=""/>
</syntaxhighlight>
 
=== Page and Bundle ===
{| class="wikitable"
|-
! NAME
! DESCRIPTION
! AVAILABLE TAG PARAMETERS
|-
|-
| style="width: 15%"|Page URL
|data_end_time
| style="width: 65%"| Canonical URL of the content where the Ad creative is served. (e.g. https://example.com/news/tech/article.html) The parameter value has to be encoded with JavaScript’s encodeURIComponent() method or equivalent. <br />Example: si=https%3A%2F%2Fexample.com%2Fnews%2Ftech%2Farticle.html
|Data Start Time (max)
| &si
|Yes
|Client
|Format:32-bit unsigned int Unix time in seconds
|String
|-
|-
| App Bundle ID
|record_count
| The app’s unique bundle ID (e.g. com.example.myapp). The ID can be used to look up the App in Apple’s App Store</br> or the Google Play Store. References:https://developer.android.com/studio/build/application-idhttps://developer.apple.com/documentation/appstoreconnectapi/bundle_ids
|Number of records in data file
| &c68=bndlid,
|Yes
|Client
|Example: 31337
|Number
|}
|}


Example:
=== Data delivery example for hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC): ===
<syntaxhighlight lang="javascript">
<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
<img src="http://secure-gl.imrworldwide.com/cgi-bim/m?ci=entXXXX&at=view&rt=banner&am=3&ca=cmpXXXX&cr=&
pc=plcXXXX&si=https%3A%2F%2Fexample.com%2Fnews%2Ftech%2Farticle.html&c68=bndlid,com.tam.nielsen.com&r=[timestamp]"
width="1" height="1" alt=""/>
</syntaxhighlight>
 
== Supported Creative Types ==
 
For consistency, Nielsen recommends tagging as much of the campaign creative types as possible, including site-served elements. '''Note:''' Nielsen may need to review/test on a case-by-case basis.
 
Nielsen Digital Ad Ratings supports banner ads, rich media and video units that are capable of being tagged with a 3rd party tracking pixel.
<blockquote>Some examples of non-standard campaign items that may be tagged include:
* microsite pages
* site “skins’”
* online mini-games
* streaming video
* pre-roll video banners
</blockquote>
Most often, these items will need to be site served and our pixel will need to be provided to the site to implement directly.
<blockquote>The following are items not tagged:
* click command/text links
* default/backup ads in a 3rd party ad server
* static ‘logo’ creatives
</blockquote>
 
Digital Ad Ratings Viewability Solution: All standard ad units listed under [http://www.iab.net/displayguidelines Universal Ad Package (UAP)] on are supported for Viewability.


Placements and sites that cannot support JavaScript cannot support Viewability.
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


'''‘Best Practices’ for Video Tags:''' Nielsen recommends all video tags be deployed as close to the beginning of the video stream as possible (post buffer).
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
Placements delivering to Flash creative should have our tag implemented within the Flash code.


== How the Tag Works ==
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


The following describes the masked javascript version of the tag. <br>
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
For the non-masked pixel version of the tag, steps 5-8 would be collapsed to just 2 steps.


[[File:image3-dar.png|right|500px]]
useast1-nlsn-w-dig-sei-acme-feeds-prod/dar-exposure/ios/2022/05/25/11/_SUCCESS</code>
# End-user uses her web browser to visit a website that contains an ad creative being measured by Nielsen.
# Website sends web page back to end-user. (Web page contains HTML describing web content & ads)
# End-user’s web browser requests the ad creative from Ad Server
# Ad Server sends an iframe ad creative back to the end-user which contains the Nielsen measurement tag
# End-user’s web browser makes a request to the Nielsen servers.
## The tag’s HTTP request contains a campaign ID and placement, which is collected by Nielsen
## The Nielsen system checks the user’s machine for an opt-out cookie – if one exists the process ends here
## The Nielsen system checks to see if the campaign value in the tag was selected for Viewability. If so it downloads the Integral Ad Science tag to the end-user’s browser.
# Nielsen server sends JavaScript code back to end-user’s web browser, including a 1x1 pixel.
# End-user’s web browser executes JavaScript code and makes an iframe request to Nielsen server to enable the “referrer masking redirect”
# Nielsen server sends an HTML message to the end-user’s web browser.
# End-user’s web browser executes HTML and requests a 1x1 pixel from the Data Provider using Nielsen server information as the HTTP referrer – thus masking the Website’s information
## The campaign ID and placement ID are passed through to Data Provider in an encrypted format
# If Viewability is enabled the JavaScript will download a Javascript tag that calls the viewability vendor (either Nielsen or 3rd Party) to begin tracking inview metrics.
# Data Provider responds with a 1x1 pixel. End process.


== '''Share Your Delivered Impressions''' ==
== 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.


'''Why the Media Plan is Needed'''
== Accuracy of Measurement ==
The reported “wall clock” time of viewing needs to be within 25 seconds of the actual viewing time.


Knowing the delivered impressions also helps Nielsen run automated QA checks, for example triggering alerts when data does not appear for a placement on an expected date. This ensures overall quality, and reduces errors in the tagging process.
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)''


It is the responsibility of the client to send Nielsen an impression delivery report, generally known as the “ad server report.” Nielsen can provide the client with a template with the inputs required to complete the quality checks. If the client does not send these reports, Nielsen will not be able to complete the quality checks. Below are instructions on how to send these reports to Nielsen.
== 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.


'''How to Share Your Delivered impressions'''
[[File:Phone_Playback.png]]


Set up an automated daily report from your ad server containing Site Name, Site ID, Placement Name, Placement ID, and data date.
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: <code>"secondscr":"MIR"</code> and include in respective mobile platform Viewing file.  


A secondary method to share your media plan information is to grant Nielsen “Reporting access” to your campaign in the designated ad server (such as DCM). To do this, simply grant the login [http://mailto:clientreporting@nielsen.com clientreporting@nielsen.com] access. In doing so Nielsen can directly access your media plan information, which enables us to check for updates, and reconcile any<br />
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.
discrepancies.
<syntaxhighlight lang="JSON">
 
{...
<blockquote>Please note that Nielsen is currently in discussions with several leading Ad Servers regarding direct integration between Nielsen and the ad server platforms. Once completed this could someday enable Nielsen to retrieve Media Plans on a completed automated basis.
  "sessionid":"ABC",
</blockquote>
  "streamid":"DEF",
 
  "position":[
== '''Apply the Tag''' ==
      {
=== '''Tag Generation''' ===
        "referencestart":"xxxxxxx123",
 
        "referenceend":"xxxxxxx183",
Your Nielsen representative will walk you through the Campaign Management Interface so that you can download tags at will at any point in the campaign.
        "playheadstart":"0",
 
        "playheadend":"60"
Nielsen supports macro-based tag generation for several major ad servers. Nielsen’s Technical Account Manager (TAM) can assist you in leveraging macro-based tags.
      },
 
      {
=== '''Tag Application''' ===
        "referencestart":"xxxxxxx243",
 
        "referenceend":"xxxxxxx303",
Apply the tag according to the 3rd party tracking pixel specifications of your ad server. If additional guidance is needed, please consult with the Technical Account Manager (TAM) for more specific instructions or recommendations, if available.
        "playheadstart":"120",
 
        "playheadend":"180"
== Special Note for Video Tags ==
      }
Nielsen’s recommended “Best Practice” for tagging your video ads is to apply the Digital Ad Ratings tag as close to the beginning of the video as possible and after initiation of the ad stream, when the ad itself begins to appear on the user’s browser, closest to the opportunity to see. To ensure video content initiates during Digital Ad Ratings measurement, tags should always be placed post buffer. Recognizing that it’s not always possible to give the Nielsen pixel priority positioning, please be aware that the placement of the tag should be discussed with the publisher/advertiser counterparty so that both sides agree on the measurement approach.
  ]
 
}
In accordance with MRC requirements, Clients must append “autop” parameter to detect click to play vs auto-play to their video tags. To detect auto-refresh (page refresh), “autof” parameter must be included (not limited to video tags).
<syntaxhighlight lang=javascript>
<img src="http://secure-gl.imrworldwide.com/cgi-bim/m?ci=entXXXX&at=view&rt=banner&am=3&ca=cmpXXXX&cr=&pc=plcXXXX&
autop=(value)&autof=(value)&r=[timestamp]" width="1" height="1" alt="" />
</syntaxhighlight>
</syntaxhighlight>


==== '''autop''' ====
- A value of 1 will be passed when Auto-Play is detected. (e.g. autop=1)<br />
- A value of 2 will be passed when Click-to-Play is detected. (e.g. autop=2)<br />
- When no value or parameter is not present, impressions are labeled as Unknown Play.


==== '''autof''' ====
<syntaxhighlight lang="JSON">
- A value of 1 will be passed when Auto-Refresh is detected. (e.g. autor=1)<br />
{...
- When no value or parameter is not present, impressions are labeled as Unknown Refresh.
  "sessionid":"ABC",
 
  "streamid":"DEF",
=== '''Special Note for Video Viewability Implementation:''' ===
  "position":[
* Nielsen does not support any Flash based video players for viewability measurement.
      {
* The ad and tag must be in the same division (div tag) in order to track Viewability
        "referencestart":"xxxxxxx183",
* Video:
        "referenceend":"xxxxxxx243",
** VPAID compliant players
        "playheadstart":"60",
** HTML5 Players (Flash not supported)
        "playheadend":"120"
** VPAID or mp4 creative
      }
** Video player must support VPAID and mp4
  ],
 
  "secondscr":"OTT"
=== '''Workflow and Tag Requirements for Nielsen Viewability with Qualified Ad Audience''' ===
}
The following steps represent the tag/data flow between the publisher and Nielsen, through to final reporting.
<blockquote> Please note that the assigned values for <code>CA, CI, AM, AM, PC and CR </code> in the example tags below are for illustrative purposes only to demonstrate the VW viewability state tag token. These values will need to be replaced with client specific data and/or macros specific to the ad serving situation.</blockquote>
 
# Ad creative exposed to the user<br />
# Ad Server technology fires DAR tag on the publisher site<br />
# Viewable state detected by Nielsen technology on publisher property; tag/signal sent to Nielsen collection system<br />
# Nielsen collection system generates and executes the DAR tag with one of the following viewable states.
# DAR data processing and reporting aggregates viewable impression states by campaign, placement and demographic attribution.
 
==== '''Viewability Base URL &amp; Ping Paths''' ====
<code> events.imrworldwide.com/VALUE?... </code>
 
==== '''Ping Path Values''' ====
* /nmp - Measure Ping
* /mp - Open Viewability Measure Ping
* >/psp - Primary Standard Ping
* /120sp - 120 Second Ping
* /cp - Cadence Ping (used by SDK)
* /fp - Final Ping
* /er - Error Ping
 
==== '''Nielsen DAR Tag/VPAID Query Strings''' ====
'''Measure Ping'''
<syntaxhighlight lang=html>
/nmp?impid=VALUE&amp;ca=VALUE&amp;ci=VALUE&amp;cr=VALUE&amp;ce=VALUE&amp;pc=VALUE&amp;am=VALUE&amp;
cy=VALUE&amp;meas=VALUE&amp;ss=VALUE&amp;vp=VALUE&amp;as=VALUE&amp;al=VALUE
</syntaxhighlight>
</syntaxhighlight>


'''Primary Standard Ping'''
==Schema Parameter Definitions ==
<syntaxhighlight lang=html>
{| class="wikitable"
/psp?impid=VALUE&amp;vs=VALUE
! colspan="2" |'''Parameter'''
</syntaxhighlight>
!'''Description'''
!'''Required'''
!'''Format / Example'''
|-
| colspan="2" |apn
|Application name
|Yes
|
Format: alphanumeric


'''120 Second Ping'''
Example:
<syntaxhighlight lang=html>
<code>BestAppIOS</code>
/120sp?impid=VALUE&amp;vs=VALUE&amp;vts=VALUE&amp;ats=VALUE
|-
</syntaxhighlight>
| colspan="2" |apv
'''Finish Ping'''
|Application version
<syntaxhighlight lang=html>
|Yes
/fp?impid=VALUE&amp;vs=VALUE&amp;ss=VALUE&amp;vp=VALUE&amp;as=VALUE&amp;ar=VALUE&amp;vts=VALUE&amp;ats=VALUE
|
</syntaxhighlight>
Format: alphanumeric
'''Error Ping'''
<syntaxhighlight lang=html>
/er?impid=VALUE&amp;ca=VALUE&amp;ci=VALUE&amp;cr=VALUE&amp;ce=VALUE&amp;pc=VALUE&amp;am=VALUE&amp;ercd=VALUE
</syntaxhighlight>


=== '''Workflow and Tag Requirements for 3rd Party Viewability''' ===
Example:
The following steps represent the tag/data flow between publisher, Nielsen and the 3rd party viewability vendor (hereafter referred to as “vendor”), through to final reporting.
<code>21.5</code>
|-
| 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
|
Format: alphanumeric


<blockquote>Please note that the assigned values for CA, CI, AM, AM, PC and CR in the example tags below are for illustrative purposes only to demonstrate the VW viewability state tag token. These values will need to be replaced with client specific data and/or macros specific to the ad serving situation.</blockquote>
Example: Random GUID:
<code>cdcde33c-b62f-4f17-a9c8-0db4f78e09d6</code>
|-
| colspan="2" |streamid
|ID for every new instance of exposure to a different asset
|Yes, if no sessionid
|
Format: alphanumeric


'''Requirements'''
Example: Random GUID:
* Ad creative exposed to the user<br />
<code>d7a909f1-5e77-4af7-8a9b-f2…</code>
*  Vendor technology fires DAR tag on the publisher site
|-
<syntaxhighlight lang=html>
| colspan="2" |streamended
http://secure-gl.imrworldwide.com/cgi-bin/m?ci=[clientid]&amp;am=[AdserverId]&amp;at=view
|Stream is known to have ended in this file
&amp;rt=banner&amp;st=image&amp;ca=[campaignId]&amp;cr=[creativeId/macro]
|Yes
&amp;pc=[placementId/macro]&amp;r=[timestamp]
|
</syntaxhighlight>
Format: integer
*  Viewable state detected by vendor detection technology (i.e. vendor Javascript containertag) on publisher property; tag/signal sent to vendor collection system
*  Vendor collection system generates and executes the DAR tag with one of the following viewable state (see highlight) embedded


==== '''onMeasureable''' ====
Example:
<syntaxhighlight lang=html>
*<code>1</code> (stream continues in subsequent file),
http://secure-gl.imrworldwide.com/cgi-bin/int?ci=[clientid]&amp;am=[AdserverId]&amp;at=view
*<code>2</code> (stream closed)
&amp;rt=banner&amp;st=image&amp;ca=[campaignI d]&amp;cr=[creativeId/macro]&amp;pc=
|-
[amvalue]_[placementId/macro]&amp;vw=meas&amp;r=[timestamp]</syntaxhighlight>
| colspan="2" |publisher_user_id
|Publisher-specific user ID (must remain persistent indefinitely)
|No
|
Format: alphanumeric


==== '''onInViewMRC''' ====
Example:  
<syntaxhighlight lang=html>
Salted, hashed user ID:  
http://secure-gl.imrworldwide.com/cgi-bin/int?ci=[clientid]&amp;am=[AdserverId]&amp;at=view
&amp;rt=banner&amp;st=image&amp;ca=[campaignId]&amp;cr=[creativeId/macro]
&amp;pc=[amvalue]_[placementId/macro]&amp;vw=view&amp;r=[timestamp ]</syntaxhighlight>
==== '''onSuspicious''' ====
<syntaxhighlight lang=html>
http://secure-gl.imrworldwide.com/cgi-bin/int?ci=[clientid]&amp;am=[AdserverId]&amp;at=view
&amp;rt=banner&amp;st=image&amp;ca=[campaignI d]&amp;cr=[creativeId/macro]
&amp;pc=[amvalue]_[placementId/macro]&amp;vw=susp&amp;r=[timestamp ]</syntaxhighlight>


*  DAR data processing and reporting aggregates viewable impression states by campaign, placement and demographic attribution.
<code>8f434346648f6b96d9dda901c5…</code>
<blockquote>'''Special Note for Nielsen Viewability with Qualified Ad Audience:''' Primary owner of campaign must provide assigned Technical Account Manager (TAM) VPAID tags per site/placement in order for VAST Wrapper to be delivered back to primary owner for implementation within their respective ad server, CMS, video serving platform, etc.
|-
</blockquote>
| colspan="2" |provider_user_id
|Provider-specific user ID (must remain persistent indefinitely)
|No
|
Format: alphanumeric


<blockquote>'''Special Note for Server Side Dynamic Ad Insertion:''' In cases where Server Side Dynamic Ad Insertion (SSDAI) is present, the Nielsen tag cannot execute unless the client side video player is coded to fire impression pixels when ads play. When this happens, all of the existing specifications for tag format, time, and criteria of execution (i.e. on play of ad) previously documented must be followed.
Example: Salted, hashed user ID:
</blockquote>


== '''QA Testing the Tag''' ==
<code>2cf24dba5fb0a30e26e83b2ab9…</code>
|-
| colspan="2" |assetid
|In-house id used for a video asset (TMS ID if available)
|Yes
|
Format: alphanumeric


Nielsen’s Technical Account Manager (TAM) will coordinate a plan to test fire tags in advance of the campaign go-live date.
Example:
<code>VID123456789</code>
|-
| colspan="2" |nielsen_id3_tag
|Encrypted Nielsen ID3 Tag. Contains SID (Source Identifier) codes (PC - Program Content  &  FD - Final Distributor).
|Optional
|
Format: alphanumeric;


In order to test the implementation of the Nielsen tag, at least one or two (more are<br />
Example:
recommended) live URLs should be provided to the TAM. If a live page cannot be made available, at staging page or offline test page should be provided. The object of this is so that the TAM can see the Nielsen call being made live, exactly as it has been implemented, to verify all of the values expected – dynamic and static - are in the tag. A spot check of a couple of placements should be sufficient unless otherwise requested. In lieu of an actual test page, we may recommend you provide a screenshot of you testing the implementation from your end, showing the Nielsen call exactly as it is being called.


Additionally, we will verify that the tags delivered have begun to receive data once the campaign actually goes live and will regularly (every 7-14 days, minimally) compare the Nielsen reporting to your 3rd party or publisher reporting to ensure we are capturing all of the data for all of the placements, as expected, and that the overall gap between your reporting and the Nielsen reporting is kept to a minimum.
<code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==<wbr />/AAAB2Jz2_k74GXSzx4npHuI<wbr />_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI<wbr />-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=<wbr />/00000/00000/00</code>


'''Detailed steps for confirming proper tag implementation'''
Note: Only Data Tags should be included, INFO Tags should not.  
* Open Chrome browser and enable “Developer Tools” (shortcuts: PC, “F12” - Mac, “Command+Option+I”)
<blockquote>'''NOTE''' - Other browsers or debugging tools can also be used as an alternative (ie Firefox w/HttpFox extension, Fiddler, Charles, Wireshark, etc).</blockquote>
* Paste test page into browser URL field
* Toggle to the “Network” tab
** To isolate the DAR ping you can also input “imr” into the filter box
[[File:image4-dar.png|900px]]


<blockquote>'''TIP''' - If DAR tag does not display try refreshing the test page</blockquote>
INFO Tag is characterized by the following CID prefix: X100zdCIGeIlgZnkYj6UvQ==
=== '''If IMAGE tags were used''' ===
'''Confirm call status is 302'''
This ensures a redirect has been made to our Data Enrichment Provider
[[File:image5-dar.png|600px]]


'''Clicking on the call and navigating to the “Headers” tab will allow you to better evaluate tag construction'''
Example INFO Tag (not desired):
[[File:image6-dar.png|500px]]


'''The “Query String” section will disclose the tag parameter'''
<code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/<wbr />AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3<wbr />_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_<wbr />J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=<wbr />/00000/46016/00</code>
Confirm these values are displaying as expected
|-
<blockquote>'''NOTE''' - If ad server macro tokens are used, please ensure they are expanding properly
| colspan="2" |gracenote_id
</blockquote>
|Gracenote TMS ID (If available) should be passed for all telecasted content.
[[File:image7-dar.png|600px]]
|Required if id3 not provided
|
Format: 14 character string. Normally leading with 2 alpha characters ('EP', 'MV', 'SH' or 'SP'), followed by 12 numbers.


'''Optional - Review Data Enrichment Provider call'''
Example:
his can be identified by searching for “brandlift”
<code>SH009311820022</code>
[[File:image8-dar.png|594px]]
|-
Call status should be 200
| 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.


<blockquote>'''NOTE''' - campaign tag parameters are encrypted when passed to Data Enrichment Provider</blockquote>
Example:
[[File:image9-dar.png|600px]]
<code>Nightly News</code>


=== '''If JavaScript tags were used''' ===
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


Steps are same as the above except for the following:
Example:  
* Two Nielsen (“imr”) calls will be made, both with status of 200
<code>xyz</code>
** 1st - logs the impression on Nielsen servers
|-
** 2nd - initiates the call to our Data Enrichment Provider
| colspan="2" |channel_id
[[File:image10-dar.png|592px]]
|ID of channel
* 3rd (Optional) call is the same as above, review Data Enrichment Provider ping.  This can be identified by searching for “brandlift”
|Required if id3 not provided
[[File:image11-dar.png|580px]]
|
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" |dma
|Designated Market Area where viewing occurred
|Yes
|<code>501</code>
|-
| colspan="2" |ad_load_flag
|linear or dynamic ad load
|Yes
|
Format: integer;


== '''Managing Campaign Updates''' ==
*<code>0</code> = Default / Unknown
*<code>1</code> = linear ad load
*<code>2</code> = dynamic ad load
|-
| colspan="2" |ad_support_flag
|Intended method of monetizing the content
|Yes
|
Format: integer;


As part of the campaign monitoring process, your Nielsen TAM will stay in close contact with you throughout the campaign, including scheduling periodic check-ins to check on the campaigns (approximately every 7-14 days, but could be more often, as needed). If you have provided reporting access to the campaign via your 3rd party or have scheduled a report to be delivered on a regular (weekly) basis, this can significantly expedite the monitoring of your campaign.
*<code>0</code> = (no ads),
*<code>1</code> = (content is supported by ads)
*<code>2</code> = (not known)


If you have any questions regarding setting up the reporting to be delivered, fields that will need to be included, etc., please reach out to the TAM assigned to your campaign. If not providing direct access to reporting, please schedule reporting to be delivered on a weekly basis.
Note: set to "<code>1</code>" if content ad support was intended but did not occur
</blockquote>
|-
| colspan="2" |position
|Array of contiguous content viewing.


== '''Frequently Asked Questions''' ==
For viewing gaps < than 1 second, the gap can be smoothed over


'''What is a tag?'''
See below for additional details on position array parameters
|Yes
|
Format:


For our purposes, a tag is an HTML code that is placed directly on a website or inside a 3rd party ad server to track exposure to an online advertisement. Adding the Nielsen tag to the<br />
<syntaxhighlight lang="JSON">
banners/videos/etc. is referred to in general as ‘tagging a campaign’.
"position": [{
 "referencestart":"[timestamp]",
 "referenceend":"[timestamp]"
 "playheadstart":"[playhead position]",
 "playheadend":"[playhead position]"
}]
</syntaxhighlight>
|-
|
|referencestart
|Wall clock reference start time
|Yes
|
Format: Unix timestamp in 32-bit unsigned int in seconds


'''What is served by the Nielsen tag?'''
Example:
<code>1577858505</code>
|-
|
|referenceend
|Wall clock reference end time
|Yes
|
Format: Unix timestamp in 32-bit unsigned int in seconds


The tag call is a simple 1x1 pixel image call. There is not a survey delivered at the time of ad call so this is not intrusive to the end user and should not adversely affect site page load times.
Example:
<code>1577858775</code>
|-
|
|playheadstart
|Content position start time
|Yes
|
Format: Unix timestamp in 32-bit unsigned int in seconds or integer indexed from 0 (typical for VOD)


'''What should be tagged?'''
Example:
<code>1577858515</code>
|-
|<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)


As much of the campaign that can be tagged, should be, for consistency. In most cases, we generally do not tag items such as: click command/text links, default/backup ads in a 3rd party ad server, or static ‘logo’ creatives. Whenever possible, we will request that you attempt to tag all other creative types, including site-served elements.
Example:  
<code>1577858785</code>
|-
| colspan="2" |viewedads
|Array of ads viewed by client.


'''Is there a way to differentiate between video “auto-play” and “click-to-play” impressions?'''
See below for additional details on position array parameters
|Yes
|
Format:
<syntaxhighlight lang="JSON">
"viewedads":
[
  {
      "adpod":"0",
      "adposition":"0",
      "adid":"0",
      "isdarid":"0",
      "adstart":"utc",
      "adend":"utc",
      "advisible":"0",
      "adfocus":"0",
      "adaudio":"0"
  }
]
</syntaxhighlight>
|-
|{
|adpod
|AdPod sequence number.</code>


The Nielsen pixel does not gather this type of granularity if the events are both sharing the same ad server placement ID. If it is desirable to compare the performance between these two events, our recommendation is to traffic these as individual placements within your ad serving<br />
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.
technology.
|Yes
|
Format: Integer


'''What is the best way to add the Nielsen tag to my campaign?'''
Example:
<code>2</code>
|-
|
|adposition
|Ad sequence number.


The Nielsen pixel should be called as close to the same time as the banner ad/creative element on which you would like to track exposure. Typically, this is handled by placing our tag inside a 3rd party ad server, such as Google’s DCM or a Rich Media vendor, such as PointRoll. However, if need be, our tag can be placed directly on a site page, immediately after the ad call in the same &lt;/div&gt; as the creative file. Further instruction can be provided on the kickoff call or we can work directly with trafficking contact(s) to get the tags in place.
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


'''Do we need to use a 3rd party ad server to use the Nielsen tag?'''
Example:
<code>1</code>
|-
|
|adid
| The unique identifier for this Ad
|No
|
Format: alphanumeric


The short answer is no. In a lot of cases, we have provided a tag that can be implemented directly on a site. The benefit of placing our tag inside a 3rd party ad server is that we can provide a single tag (or minimal number of tags) that contain macros to simplify the tagging process.
In-house AdId, Industry AdID, AdNetwork ID or DAR placement ID
|-
|
|isdarid
|Is the AdId being passed a Nielsen DAR placement ID
|Required if AdID
|
Format: integer
*<code>0</code> = is NOT DAR ID;
*<code>1</code> = is a DAR ID
|-
|
|adstart
|Wall clock reference start time
|Yes
|
Format: Unix timestamp in 32-bit unsigned int in seconds
|-
|<nowiki>}</nowiki>
|adend
|Wall clock reference end time
|Yes
|
Format: Unix timestamp in 32-bit unsigned int in seconds
|-
| colspan="2" |device_id
|Mobile Ad ID (IDFA, ADID), Connected Device ID
|Yes,if


'''Is there anything that can’t be tagged?'''
available
|<code>A487421B-XXXX-YYYY-8343-E3BBB66E44F2</code>
|-
| colspan="2" |hem_sha256
|SHA-256 hashed email


We may need to review/test on a case-by-case basis, but realistically most campaign elements can be tagged. Most often, these items will need to be site served and our pixel will need to be provided to the site to implement directly. Some examples of non-standard campaign items that have been tagged before include: microsite pages, site ‘skins’, online mini-games, streaming video, pre-roll video banners.
Note: email normalization rules applied before hashing
|Strongly Preferred
|<code>55C06A30DAA5D5F382FDEB8C702EC57875CC9D91A7C78BB620053FD81DC…</code>
|-
| colspan="2" |luid
|Living Unit ID - Experian Household ID
|Yes, for CTV if available
|<code>B0EOFEDgD</code>
|-
| colspan="2" |uoo
|User opt out flag for demographic measurement
|Yes
|
Format: integer
*<code>0</code> = not opt-out
*<code>1</code> = opt-out
|-
| colspan="2" |xdua
|Device HTTP User Agent string
|Yes
|
Format: alphanumeric,  


'''The site has told us that they can accept only one pixel for the site served element. Can we append your tag to the end of ours?'''
Example:
 
<code>Apple-iPhone1C2/801.293</code>
If you are serving a DCM 1x1 pixel to track these elements of your campaign, we have a method for placing our tag behind this call, to be served as a redirect. For other situations, we may need to discuss further and consider other options.
|-
 
| colspan="2" |xff
'''I’m using more than one Nielsen study/product on this campaign. Will I need multiple/different tags for each?'''
|IP address
 
|Yes
You should not need separate tags for each study. To keep the tagging process simple, we have designed our products so that a single tag can be used for multiple online studies, however, your TAM needs to be informed of all studies before launch so that they can be enabled.
|
 
Format: xxx.xxx.xxx.xxx
'''How much detail can be tracked with the Nielsen tag?'''
|-
 
| colspan="2" |psudo_id_sha256
Typically, we do an overall read for these studies, but we can segment the data by site, placement, ad size or creative, for example. If more granular data is desired, this should be discussed ahead of the campaign launch and planned for at the time of tag creation. ''We cannot segment the data if we have not tagged for it''​ -- multiple tags will need to be created and implemented properly. Note that this can often be a time consuming process for the client trafficker and additional time should be allotted if this is needed. Lastly, keep in mind that exposure sample size may be a factor for segmenting the data at a more granular level.
|Hashed Device User Agent string + IP address
 
|No
'''Why is it recommended to implement a timestamp or random number on the tag?''' This value will ensure that the tag call will not be cached on a user’s browser. It’s not absolutely necessary to implement for the tag to work, but without it you may see a larger gap between the impressions ran and what Nielsen captures. It is recommended to minimize this gap.
|<code>421c76d77563afa1914846b010bd164f395bd34c2102e5e99e0cb9cf173…</code>
 
|-
'''For campaigns involving Facebook, what can’t be tagged on their site?'''
| colspan="5" | The following 4 parameters become mandatory if Device User Agent String (UAS) is not available
 
|-
Fan/Like pages are not allowed to be tagged, per Facebook. Additionally, Marketplace slots are not allowed to be tagged as these are user generated ads.
| colspan="2" |device_platform
 
|Device platform(mobile, desktop, connected device)
'''What if it is not possible to provide a test or staging page before launch?'''
|Required if no UAS
 
|<code>DSK</code>, <code>MBL</code>, <code>OTT</code>
While not ideal, we can view raw impression numbers on the day of the launch as well as review a live example if a URL is provided. Another option would to test from the client/site side and provide a screenshot of the Nielsen call being made using a proxy tool (HTTPWatch, Fiddler, Charles, etc.) – prior to launch. The aim either way is to minimize missing impressions for your campaign, so it is in your best interest to provide for this testing if you can.
|-
 
| colspan="2" |device_type
'''What is considered to be an acceptable gap in reporting?'''
|Device type for connected devices
 
|Required if no UAS
In a perfect world, we’d like to see no gap in the numbers. We realize this is simply not possible – it is a factor of the Internet and having different counting methodologies, so we will aim for the lowest overall gap we can. Even with everything trafficked correctly; it is not uncommon to see gaps in the range of 5 to 10%, so we shoot for this range (if it’s lower than that, that’s great). If it’s greater than 10%, it usually indicates that there was something that was missed from being tagged or there’s an additional issue that requires further attention. When issues arise, we make all attempts to highlight and communicate the issue seen, to minimize the overall impact to the study, but are reliant on the client to ensure the issue is fixed. In a campaign where there are issues such as this, we try to keep the gap under 20% and will document any issues found. What are the capabilities for tagging video and video based ads?
|<code>AMN</code>, <code>APL</code>, <code>DVD</code>, <code>GGL</code>, <code>PSX</code>, <code>RKU</code>, <code>STB</code>, <code>STV</code>, <code>XBX</code>
 
|-
Our tag is not a specific limitation as it is one of the simplest things that can be served – a 1x1 image. That being said, much of the video implementation limitations are often dictated by the video vendors themselves. Where you can add our tag is dependent on the capabilities of these vendors. Some have the ability to place the tag in multiple locations in the video (i.e. beginning, middle, end – multiple tags will be needed to separate these out) and some simply place the pixel directly on the webpage, next to video being served. Further discussion may need to happen with the vendor, Nielsen and the client to determine the optimum implementation that meets the client's needs.
| colspan="2" |os_group
</blockquote>
|Operating system of mobile devices. All other device should be NA
|Required if no UAS
|<code>IOS</code>, <code>DROID</code>, <code>NA</code>
|-
| colspan="2" |device_group
|Type of device: phone, tablet, desktop, set top box (CTV or OTT), unknown
|Required if no UAS
|<code>DSK</code>, <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="2" |robotic_flag
|Flag indicating IAB bot rule if IP address present in IAB bot list
|Required if no IP
|Format: integer
*<code>0</code> = not bot,
*<code>1</code> = bot
|-
| colspan="2" |zip_code
| ZIP code where viewing occurred
|Required if no IP
|<code>10001</code>
|-
| colspan="2" |country
|Country ISO 3166 ALPHA-2
|Required if no IP
| <code>US</code>, <code> CA</code>, etc.
|}
Note: All parameters are case sensitive.

Revision as of 22:45, 6 June 2024

Engineering Portal / Digital / Digital Measurement SEI Streaming Content Viewing

This interface specification depicts the file schema required to supply Nielsen with response-level Viewing data in a “Server-to-Server” relationship for incorporation into the Nielsen One Content and/or Nielsen One Ads products.

Delivery Specifications

Files should be delivered at a fixed cadence in a dedicated S3 bucket following the outlined in this spec prefix and object naming conventions and data formats.

  • All prefix labels and file names should be lowercase except for app ids.
  • Supported format are:
    • Text files with utf-8 encoding in JSON Lines format;
    • Apache Parquet format with snappy compression;
  • All data files have extensions to indicate the file format (.json | .parquet)
  • Data file can be partitioned into multiple parts with min size of 256MB
  • Data can be delivered separately in multiple splits, if needed due to organizational, technical or privacy requirements. This allows to permission s3 access separately, to process data independently and to persist data partitioned, within the limits of the SEI system

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>.[json|parquet]

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 Required 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.

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.

Phone Playback.png

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

Parameter Description Required Format / Example
apn Application name Yes

Format: alphanumeric

Example: BestAppIOS

apv Application version Yes

Format: alphanumeric

Example: 21.5

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: cdcde33c-b62f-4f17-a9c8-0db4f78e09d6

streamid ID for every new instance of exposure to a different asset Yes, if no sessionid

Format: alphanumeric

Example: Random GUID: d7a909f1-5e77-4af7-8a9b-f2…

streamended Stream is known to have ended in this file Yes

Format: integer

Example:

  • 1 (stream continues in subsequent file),
  • 2 (stream closed)
publisher_user_id Publisher-specific user ID (must remain persistent indefinitely) No

Format: alphanumeric

Example: Salted, hashed user ID:

8f434346648f6b96d9dda901c5…

provider_user_id Provider-specific user ID (must remain persistent indefinitely) No

Format: alphanumeric

Example: Salted, hashed user ID:

2cf24dba5fb0a30e26e83b2ab9…

assetid In-house id used for a video asset (TMS ID if available) Yes

Format: alphanumeric

Example: VID123456789

nielsen_id3_tag Encrypted Nielsen ID3 Tag. Contains SID (Source Identifier) codes (PC - Program Content  &  FD - Final Distributor). Optional

Format: alphanumeric;

Example:

www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/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

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

station_id GraceNote station ID that identifies the station Required if id3 not provided

Format: alphanumeric

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.

network_affiliate Network affiliation of a station Required if id3 not provided

Format: alphanumeric

Example: xyz

channel_id ID of channel Required if id3 not provided

Format: integer

channel_name Name of channel Required if id3 not provided

Format: alphanumeric

callsign FCC assigned unique identifier for a transmitter station Required if id3 not provided

Format: alphanumeric

dma Designated Market Area where viewing occurred Yes 501
ad_load_flag linear or dynamic ad load Yes

Format: integer;

  • 0 = Default / Unknown
  • 1 = linear ad load
  • 2 = dynamic ad load
ad_support_flag Intended method of monetizing the content Yes

Format: integer;

  • 0 = (no ads),
  • 1 = (content is supported by ads)
  • 2 = (not known)

Note: set to "1" if content ad support was intended but did not occur

position Array of contiguous content viewing.

For viewing gaps < than 1 second, the gap can be smoothed over

See below for additional details on position array parameters

Yes

Format: 

"position": [{
 "referencestart":"[timestamp]",
 "referenceend":"[timestamp]"
 "playheadstart":"[playhead position]",
 "playheadend":"[playhead position]"
}]
referencestart Wall clock reference start time Yes

Format: Unix timestamp in 32-bit unsigned int in seconds

Example: 1577858505

referenceend Wall clock reference end time Yes

Format: Unix timestamp in 32-bit unsigned int in seconds

Example: 1577858775

playheadstart 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

} 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

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 Ad sequence number.

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 Is the AdId being passed a Nielsen DAR placement ID Required if AdID

Format: integer

  • 0 = is NOT DAR ID;
  • 1 = is a DAR ID
adstart Wall clock reference start time Yes

Format: Unix timestamp in 32-bit unsigned int in seconds

} adend Wall clock reference end time Yes

Format: Unix timestamp in 32-bit unsigned int in seconds

device_id Mobile Ad ID (IDFA, ADID), Connected Device ID Yes,if

available

A487421B-XXXX-YYYY-8343-E3BBB66E44F2
hem_sha256 SHA-256 hashed email

Note: email normalization rules applied before hashing

Strongly Preferred 55C06A30DAA5D5F382FDEB8C702EC57875CC9D91A7C78BB620053FD81DC…
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

Format: alphanumeric,

Example: Apple-iPhone1C2/801.293

xff IP address Yes

Format: xxx.xxx.xxx.xxx

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 Required if no IP US, CA, etc.

Note: All parameters are case sensitive.

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