DCR Integration Utilizing S2S

This guide shows you how to integrate the Nielsen S2S(Server to Server) to enable Digital Content Ratings (DCR), and fuel other measurement products on your Apps.

PLease note that you have to use the Staging S2S Endpoint(<env>=stage)until you get the green light to move to Production, you will then get the Production S2S Endpoint!

Prerequisites

To get started, you will need a Nielsen App ID. The App ID is a unique ID assigned to your app. This will be provided to you by your assigned Technical Account Manager upon starting the integration.

Item	Description	Source
App ID (apid)	Unique ID assigned to the player/site and configured by product.	Provided by Nielsen
Integration ID (IntID)	Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewsership pipelines (dcr)	Provided by Nielsen
Partner ID (PartnerID)	Partner id provided by Nielsen. Used for the client specific S3 bucket . Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.	Provided by Nielsen

Introduction

This interface specification depicts the file format that needs to be used to supply Nielsen with end-user viewing data captured by a “Server-to-Server” method for the Nielsen Digital Content Ratings (DCR) product.

The specification is defined using a JSON schema, with each file ideally containing all the

viewing that has been captured within an hour.

In the case of a stream that has one version with blackouts and one without, one with

mobile and one non-mobile, each stream would have it’s own unique asset id.

The Asset Metadata file should arrive before the viewing data file for the same hour.

SLA

The files must be delivered into the proper S3 bucket immediately after each hour of viewing on a device, but latest within 3 hour of the start of that hourly viewing file interval. For example files from 1:00 AM to 2:00 AM must be delivered latest before 4 AM.

When SLA for receiving exposure file for date xx/xx, UTC hour xx has expired. The system will continue to wait for 60 min, after which it will skip the missing file and continue processing subsequent files. Any reprocessing of the missed SLA data will require an explicite request from clients

Accuracy of the Measurement

Send Viewing Time (Video Player Events) At Least Each 10 Seconds To Your Backend

Capture content viewing time each second and send the aggregated viewing time at least each 10 seconds to your backend:

referencestart : Wall clock reference start time (In UTC time, 32-bit unsigned int in seconds)
referenceend : Wall clock reference end time (In UTC time, 32-bit unsigned int in seconds)
playheadstart : Content position start time in seconds
playheadend : Content position end time in seconds

Send Viewing Time When The Video Playback Is Interrupted

Send the aggregated viewing time to your backend when the video playback is interrupted, i.e. paused.

Capture Accurately Each Second The Viewing Time When The Network Is Lost And The Video Playback Continues

Capture accurately each second the viewing time when the network is lost. Send the aggregated viewing time to your backend when the network is back.

Send The Viewing Time Early On Browser Refreshed/Closed

Capture and send the viewing time to your backend by implementing the 2 WINDOWS EVENTS:

Please include a logic to make sure that only one of the 2 following event handler is executed

window.addEventListener("pagehide", function (e) { 
   // SEND THE VIEWING TIME TO YOUR BACKEND
});
window.addEventListener("beforeunload", function (e) {
   // ONLY IF pagehide" was not triggered, SEND THE VIEWING TIME TO YOUR BACKEND
});

File Naming Convention and Delivery Specification

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:
- Uncompressed text files with utf-8 encoding in:
  - JSON format(.json);
  - PARQUET format(.parquet);
All files should have extensions to indicate the file format (.json or .parquet)
Data file can be partitioned into multiple parts with min size of 128MB - 256MB
Data can be delivered separately in multiple splits(platforms), 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 S2S system;

The 4 Different Files to deliver to Nielsen each hour

[Asset Metadata File]
[Asset Viewing File]
[Manifest File]
[Success File: Indication of a data delivery for a particular hour]

Nielsen will move files to indicate they are being processed.

S3 bucket and prefix(S3BucketPrefix) for all 4 Files

All files should be delived to: <S3BucketPrefix>: euwest1-nlsn-w-dig-sei-<PartnerID>-feeds-<env>/ProducType>/<Platform>/yyyy/mm/dd/hh/

Parameter Description

Parameter	Description
PartnerID	Publisher abbreviation provided by Nielsen for each Publisher or Provider
env	stage for Staging or prod for Production
ProductType	dcr-exposure for Asset Viewing File, dcr-metadata for Asset Metadata File
Platform	ios, browser, android, ott
yyyy/mm/dd/hh	UTC start of the period of the data in file yyyy = Year mm = Month dd = Date padded with 0 example 01, 02,..., 31 hh = Hour padded with 0 example 00, 02,..., 23 example: 2023/02/12/05

Examples for the iOS platform

Asset Metadata File

euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/

Asset Viewing File

euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/

Manifest File

euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/

Success File

euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/

File Name(FileName) format for the Asset Metadata and Asset Viewing Files

Asset Metadata and Asset Viewing Files should be delivered to:

<S3BucketPrefix><FileName>

<FileName> : <PartnerID>_<ProductType>_<IntID>_<AppID>_<StartTime>_<EndTime><FileSuffix>

Parameter Description

Parameter	Description
PartnerID	Publisher abbreviation provided by Nielsen for each Publisher or Provider
IntID	Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewsership pipelines (dar, dtvr, dcr, etc.)
ProductType	dcr-exposure for Asset Viewing File, dcr-metadata for Asset Metadata File
AppID	Nielsen provided server application identifier
StartTime	start date and hour of the data in the file in GMT: yyyymmddhh
EndTime	end date and hour of the data in the file in GMT: yyyymmddhh
yyyymmddhh	UTC time of the period of the data in file yyyy = Year mm = Month dd = Date padded with 0 example 01, 02,..., 31 hh = Hour padded with 0 example 00, 02,..., 23 example: 2023021205
FileSuffix	Uncompressed json lines (no extension) - splittable, ideal for medium size files, less than 5 GB, preferred for metadata. supported: .json json file .parquet parquet file

Examples for Asset Metadata and Asset Viewing Files

Asset Metadata File

Asset Metadata File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json

Asset Viewing File

Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json

Manifest File for the Asset Metadata and Asset Viewing Files

The Manifest File should be delivered to: <S3BucketPrefix><FileName>

<FileName> : <PartnerID>_<ProductType>_<IntID>_<AppID>_<StartTime>_<EndTime>_manifest

A manifest contains metadata related to the uploaded file(s). It is a text file in json format that implements the AWS unload manifest file format. It follows the s3 objects naming notation, but has the _manifest suffix. Here’s an example of manifest file contents:

{

 "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 platform, as well as a meta data (a.k.a. header) which should include the following attributes:

Keys	Description	Values	Required
schema_version	Schema Version	String, i.e. "S2SV1.7.0"	✓
data_start_time	Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds	String, i.e. "1710154800"	✓
data_start_time	Data End UTC Time (max), 32-bit unsigned int Unix time in seconds	String, i.e. "1710158399"	✓
record_count	Records Count in data file	Number: i.e. 55	✓

If ‘entries’ array is not specified, or manifest file is not available, the system will still attempt to load all data file(s) (.json or .parquet) from the prefix location. Optionally the manifest file can contain the full schema of the data files as shown in the manifest file format document .

Example for the Manifest File

Manifest File for the Asset Metadata File

The Manifest File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

{
    "schema_version": "S2SV1.7.0",
    "accreditation_status": "0",
    "start_time": "1710154800",
    "end_time": "1710158399",
    "record_count": 15
}

Manifest File for the Asset Viewing File

The Manifest File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

{
    "schema_version": "S2SV1.7.0",
    "accreditation_status": "0",
    "start_time": "1710154800",
    "end_time": "1710158399",
    "record_count": 55
}

Success File: Indication of a data delivery for a particular hour

An Empty _SUCCESS file should be provided to indicate that data delivery for a particular hour and platform is completed successfully. This file should be uploaded last (after all other files). If there is no data data for a particular hour and platform, the _SUCCESS file is still required to indicate that the delivery process for the hour is completed and no data files are expected. This file is only required for integrations that support data partitioned into multiple parts. The name of the file is configurable.

Example for Asset Viewing Delivery Files

For hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC): euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/_SUCCESS

Example for Asset Metadata Delivery Files

For hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC): euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS

Data Delivery Example for hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):

Asset Metadata Delivery Files

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS

Asset Viewing Delivery Files

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0000.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0001.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0002.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0003.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/_SUCCESS

S2S Metadata Specifications for the Asset Metadata and Asset Viewing Files

Asset Metadata File

The Asset Metadata File contains 1 Header Record followed by Body Records

Header Record

Description

Parameter Description

Keys	Description	Values	Required
schemaversion	Json Schema Version	String, "S2SAssetMetaDataDCRV2.09"	✓
mvpdid	mvpd ID specified ny Nielsen	String, i.e. "NLSN"	✓
creationtime	File creation time (UTC time in 32-bit unsigned int UTC in seconds)	String, i.e. "1473781507"	✓
recordcount	Records Count in body of file	String, i.e. "1" for only 1 Record	✓

Example

{
    "schemaversion": "S2SAssetMetaDataDCRV2.09",
    "mvpdid": "NLSN",
    "creationtime": "1473781507",
    "recordcount": "1"
}

Body Record

Description

Note: All metadata values should be passed as UTF-8 strings.
Note: Do not include personal data in the content metadata.

Keys	Description	Values	Required
assetid	unique ID assigned to asset	custom (no Special Characters)	✓
programname	name of program	custom	✓
episodetitle	episode name	custom	✓
episodelen	length of content in seconds	Length of content in seconds (86400 seconds for live stream (24/7). For Event-Live streams planned length. For VoD video length)	✓
islivestn	Indicates if a stream is playing on a live channel	"y" playing on a live channel "n" otherwise i.e. VoD	✓
subbrand	vcid/sub-brand/Channel ID – value is automatically populated through provided AppID. In order to override the sub-brand configured to the App ID, value can be passed here (e.g. multiple sub-brands/Channels in the App)	provided by Nielsen	✓

Example

{
    "assetid": "VA12345",
    "program" : "program name",
    "title" : "episode title",
    "length" : "length in seconds",
    "islivestn": "y",
    "subbrand": "c05"
}

Asset Viewing File

The Asset Viewing File contains 1 Header Record followed by Body Records Note: All metadata values should be passed as UTF-8 strings.

Please do not include ZERO DURATION viewing portion in the Asset Viewing File.

Header Record

Description

Parameter Description

Keys	Description	Values	Required
schemaversion	Json Schema Version	String, "S2SViewingDataV1.7.0"	✓
appid	Nielsen provided server application identifier	String, i.e. "P47C2495B-XXXX-56DE-BE99-14758F92F034"	✓
type	Type of the data	String, "content"	✓
producttype	Product Type	String, "DCR"	✓
starttime	Viewing Data Start Time (UTC time in 32-bit unsigned int UTC in seconds)	String, i.e. "1473781507"	✓
endtime	Viewing Data End Time (UTC time in 32-bit unsigned int UTC in seconds)	String, i.e. "1473791507"	✓
recordcount	Records Count in body of file	String, i.e. "100" for only 100 Records	✓

Example

{
    "schemaversion": "S2SViewingDataV1.7.0",
    "appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
    "type": "content",
    "producttype": "DCR",
    "starttime": "1473781507",
    "endtime": "1473791507",
    "recordcount": "100"
}

Body Record

Description

Keys	Description	Values	Required
apn	app name	i.e. "BestAppIOS"	✓
apv	app build version	i.e. "1.3"	✓
sessionid	Unique, client generated value that represents the start of a user session. Must match sessionid in Audit Ping.	created using the UUID Generator code provided	✓
streamid	streamid ID for every new instance of an asset	created using the UUID Generator code provided	✓
streamended	Stream is known to have ended in this file	"1" (stream will continue in next file) "2" (stream closed)	✓
secondscr	Second Screen Indicator. For Mirroring & Extended Screen via OTT device scenarios	"" (empty String if viewed directly on the device) "MIR" (Mirroring) "OTT" (Extended Screen via OTT device)	✓
assetid	unique ID assigned to asset	custom (no Special Characters)	✓
position	Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds)	`[{ "referencestart":"utc time", "referenceend":"utc time", "playheadstart":"playhead start position", "playheadend":"playhead end position" }]` Description: referencestart : Wall clock reference start time (In UTC time, 32-bit unsigned int in seconds) referenceend : Wall clock reference end time (In UTC time, 32-bit unsigned int in seconds) playheadstart : Content position start time in seconds playheadend : Content position end time in seconds For Content position start and end time(playheadstart, playheadend): For VoD stream use the player position for Content as the playhead position in seconds. At playback start of a content from the begin, playheads will then be 0,1,2,3,.... For Live streams, use Unix Time (in seconds) matching the broadcast time as the playhead position in seconds. Additional Notes: For viewing gaps < than 1 second, the gap can be smoothed over For playouts that are abandoned before the first whole second of viewing is rendered, a position record of zero duration should be created. IF an audit ping has already been fired See below for additional details on position array parameters	✓
device_id	Mobile Ad ID IDFA,ADID, Connected Device ID unique Device ID of a user device (e.g. SHA-256 hashed value of i.e. Advertising ID, Roku Device ID). Please verify your implemented SHA-256 by passing "00000000-0000-0000-0000-000000000000" which should return "12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8"	i.e "12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8"	✓
xdua	Device HTTP raw User Agent string - OPTIONAL if passed in the Audit Ping to the Nielsen Server	Example: "Apple-iPhone1C2/801.293"	✓
xff	IP address - OPTIONAL if passed in the Audit Ping to the Nielsen Server	Format: "xxx.xxx.xxx.xxx" or "xxx.xxx.xxx.000" Examples : IPV4: "4.12.345.67" IPV6: "2600:6c58:7900:33f2:2505:42b9:5a34:0000"	✓
fpid	First Party ID	created using the UUID Generator code provided / validity time 180 days.
fpcrtm	Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds)	custom
hem_sha1	hashed (SHA256) value of member id	i.e. for the sample memberID "userMemberID123", the value to pass is "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826"
uid2	hashed(SHA256) value of UID2	i.e. for the sample UID2 "userUID2", the value to pass is i.e. "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05"
hem_sha256	hashed(SHA256) value of the user email address	i.e. for the sample email address "useremail@company.com", the value to pass is "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969"
uoo	device opt-out status	"true" for opted out, "false" for NOT opted out or opted in.	✓

Example

{
    "apn": "BestAppiOS",
    "apv": "1.3",
    "sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
    "streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique streamid for each video play using UUID Generator code provided
    "streamended": "1",
    "assetid": "VA12345",
    "secondscr": "MIR",
    "position": [
        {
            "referencestart": "1628735452",
            "referenceend": "1628736052",
            "playheadstart": "0",
            "playheadend": "600"
        }
    ],
    "xdua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130Safari/537.36",
    "xff": "4.12.345.67",
    
    "uid2": "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05",
    "device_id": "8ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
    "hem_sha1": "9ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
    "hem_sha256": "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969",
    "uoo": "false",
    "fpid": "U4EDwDcpvWIbguYVyjlhzS1v0eaov1631180980",
    "fpcrtm": "1631098029000",
}

Metadata based on User Consent in your App

The following user consent use cases need to be implemented in your App.

The user explicitly accepts measurement

All Device/User IDs are captured in the Nielsen S2S Metadata. The Opt-in Flag is set to "false" and all IDs have to be set accordingly:

 {
  "device_id": "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
  "hem_sha1": "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
  "uid2": "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05",
  "hem_sha256": "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969",
  "uoo"": "false",
  "fpid": "U4EDwDcpvWIbguYVyjlhzS1v0eaov1631180980",
  "fpcrtm": "1631098029000"
  }

The user explicitly refuses measurement

The Nielsen S2S is NOT initiated and No Nielsen S2S measurement will occur.

The user did not explicitly give consent for the measurement(consent neither given nor refused)

The Nielsen S2S is initiated and no IDs are captured. The Nielsen S2S Opt-out Flag is set to "true" and all Device/User IDs are empty:

{
  "device_id": "",
  "hem_sha1": "",
  "uid2": "",
  "hem_sha256": "",
  "uoo"": "true",
  "fpid": "",
  "fpcrtm": ""
  }

OTT, 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 OTT device, and Viewing data should reside in OTT Viewing file. 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 respective mobile platform Viewing file.

{ // ...

   "sessionid": "xx..xxxABC",
   "streamid": "xx..xxxDEF",
   "position": [
       {
           "referencestart": "xxxxxxx123",
           "referenceend": "xxxxxxx183",
           "playheadstart": "0",
           "playheadend": "60"
       },
       {
           "referencestart": "xxxxxxx243",
           "referenceend": "xxxxxxx303",
           "playheadstart": "120",
           "playheadend": "180"
       }
   ]

}

{ // ...

   "sessionid": "xx..xxxABC",
   "streamid": "xx..xxxDEF",
   "position": [
       {
           "referencestart": "xxxxxxx183",
           "referenceend": "xxxxxxx243",
           "playheadstart": "60",
           "playheadend": "120"
       }
   ],
   "secondscr": "OTT"

}

S2S Audit Ping Specifications

Introduction

The Nielsen server to server solution needs audit pings to validate audience reach and video viewing duration, one start and one end for each video stream playback. These pings will go from the end user device to Nielsen Collections servers.

start audit ping(“Startstream = 1”)

A start audit ping is sent when the stream starts(playback start).
Also a new start audit ping is sent when the stream playback resumes after a playback interruption for more than 30 minutes, typically playback paused. PLEASE note that a new “streamid” parameter has to be created before sending a new start audit ping.

end audit ping(“Endstream = 3”)

An end audit ping is sent when the stream ends(either playback completed or switch to another stream).
Also an end audit ping is sent when the stream playback after a playback interruption for more than 30 minutes, typically playback paused.

Ping Structure

Ping should be named with following convention structure: https://audit.imrworldwide.com/cgi-bin/gn?prd=audit& query param list (see table below)

Please note that you have to send the Audit Ping in real time on the device running your App.

(Please note that this URL could change as we respond to security upgrades in the market.) The Start Audit Ping will carry all parameters in the matrix below. The End Audit Ping will carry a subset of the parameters in the matrix below as denoted in the mandatory column. Under normal operating circumstances, the Nielsen collection system will return return codes:

For security reasons, downstream servers reject cross-origin HTTP requests with preflight. To ensure that audit ping requests are accepted, allowable Content-Types like "text/plain" in simple GET requests ensure that preflight requests are not invoked, which is the preferred behavior.
200: The ping was successfully received, inspect traffic to ensure no CORS errors

Ping Session & Stream Details

Sessions

a) When a new player is created a session id is also created.
b) If you have more than one video player within the same App (e.g. picture in picture) you must use a different session id for each.

Streams

a) The Distributor must generate a new UNIQUE stream id with every video stream playback.
b) If two people watch the same show, they would have different stream id's as Nielsen would expect the stream id(“streamid”) to be a random GUId generated by the client device.
c) If one person watches a show, and FF, rewind, playout, pause, play, RW, play - they would keep the same stream id(“streamid”) throughout the entire playout of that video asset (stream).
d) If a stream play out is suspended for 30 mins or more (paused or background):
- An end audit ping(“Endstream = 3”) is sent when the stream playback after a playback interruption for more than 30 minutes, typically playback paused.
- A new start audit ping(“Startstream = 1”) is sent when the stream playback resumes after a playback interruption for more than 30 minutes, typically playback paused. PLEASE note that a new “streamid” parameter has to be created before sending a new start audit ping.
e) If the user reaches the very end of the stream (content complete), and then starts to play again (replay from anywhere in the stream), then a new “streamid” should be created and a start audit ping should be sent. Also an end audit should be sent when the stream replay is completed or the user switches to another stream.

Audit Pings

a) Audit pings should be fired at the beginning and end of a stream. These will be referred to as the Audit Start Ping and the Audit End Ping.

query param list

Example:

Required S2S Audit Ping Query String Parameters - Note: All parameters are case sensitive

Keys	Description	Values	Required
apid	Unique ID assigned to the player/site and configured by your Nielsen Technical Account Manager.	Example: FC984EC1-E044-B465-E040-070AAD3173A1	✓
intid	Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewership pipelines (dar, dtvr, dcr, etc.)		✓
sessionid	Unique, client-generated value that represents the start of a user browsing session. Must match sessionid in the Exposure file.	created using the UUID Generator code provided	✓
streamid	Unique Id for every new instance of a client video asset playout. Must match streamid in the Exposure file.	created using the UUID Generator code provided	✓
pingtype	pingtype Indicator for state type: “start” or “end” audit ping & if the ping is for a stream	Startstream = 1 Startsession=0 Endstream = 3 Endsession=2	✓
product	Indicates which Nielsen product the audit ping corresponds to.	dcr	✓
createtm	Time the ping was fired: utc (in seconds) If server time available, use it instead of device time		✓
devid	devid, SHA-256 value of Device Id (IDFA, ADID) - OPTIONAL is passed in the Asset Viewing File		✓
uoo	device opt-out status	"true" for opted out, "false" for NOT opted out or opted in.	✓

Generic Ping Format:

https://audit.imrworldwide.com/cgi-bin/gn?prd=audit&apid=<App id>&intid=<Integration ID>&sessionid=<Session Id>&streamid=<Stream Id>&pingtype=<Ping Type>&uoo=<Optout Status >&product=<dcr or dtvr>&createtm=<Session Start or End time>&devid=<Android ADID>'''

Audit Ping Examples:

End Audit Ping Example (Startsession)

https://audit.imrworldwide.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&uoo=false&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8

UUID Generator Code

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

Create random GUID

function buildGUID() {
    var UAIDbase62Characters = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
    var UAIDpayloadLength = 29;

    function UAIDgetRandom62() {
        var r1;
        do {
            r1 = Math.floor(Math.random() * (16 * 62));
        } while (r1 > 61); 
        return r1;
    }

    var uid = '';
    for (var a = 0; a < UAIDpayloadLength; a++) {
        uid += UAIDbase62Characters.charAt(UAIDgetRandom62());
    }
    var timestamp_ms = new Date().getTime();
    uid += String(timestamp_ms).substring(3);
    return uid;
}

DCR Poland Video S2S

From Engineering Client Portal

DCR Integration Utilizing S2S

Prerequisites

Introduction

SLA

Accuracy of the Measurement

Send Viewing Time (Video Player Events) At Least Each 10 Seconds To Your Backend

Send Viewing Time When The Video Playback Is Interrupted

Capture Accurately Each Second The Viewing Time When The Network Is Lost And The Video Playback Continues

Send The Viewing Time Early On Browser Refreshed/Closed

File Naming Convention and Delivery Specification

The 4 Different Files to deliver to Nielsen each hour

S3 bucket and prefix(S3BucketPrefix) for all 4 Files

Examples for the iOS platform

Asset Metadata File

Asset Viewing File

Manifest File

Success File

File Name(FileName) format for the Asset Metadata and Asset Viewing Files

Examples for Asset Metadata and Asset Viewing Files

Asset Metadata File

Asset Viewing File

Manifest File for the Asset Metadata and Asset Viewing Files

Example for the Manifest File

Manifest File for the Asset Metadata File

Manifest File for the Asset Viewing File

Success File: Indication of a data delivery for a particular hour

Example for Asset Viewing Delivery Files

Example for Asset Metadata Delivery Files

Data Delivery Example for hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):

Asset Metadata Delivery Files

Asset Viewing Delivery Files

S2S Metadata Specifications for the Asset Metadata and Asset Viewing Files

Asset Metadata File

Header Record

Description

Example

Body Record

Description

Example

Asset Viewing File

Header Record

Description

Example

Body Record

Description

Example

Metadata based on User Consent in your App

The user explicitly accepts measurement

The user explicitly refuses measurement

The user did not explicitly give consent for the measurement(consent neither given nor refused)

OTT, Mirroring, and Casting

S2S Audit Ping Specifications

Introduction

Ping Structure

Ping Session & Stream Details

Sessions

Streams

Audit Pings

query param list

UUID Generator Code