Engineering Client Portal - User contributions [en]

DCR Germany Video S2S

2026-08-20T08:17:41Z

MichelFodjo: new section added "Data quality for long-duration video measurement"

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Option 1: Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Option 2: Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

'''The first hour of the day''' used in the following description of the optimization refers to '''03:00:00 AM to 03:59:59 AM German local time''' (01:00:00 AM to 01:59:59 AM UTC during daylight saving time; 02:00:00 AM to 02:59:59 AM UTC during standard time).

====Option 1: Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 02:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Option 2: Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''
* The metadata reported in the AGF measurement data for a given assetid (including episode title, duration, and custom variables nol_c0–nol_c19) is locked in by the first video request of the day and its corresponding hourly metadata file. Subsequent metadata changes during the day will be ignored.

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid)
||
'''Use only if the asset metadata file optimization is not used and is delivered per platform with this subbrand value'''

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

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF.
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider.
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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. Must match streamid in Audit Ping. || 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Use only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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 usage, one '''start''' and one '''end''' for each video stream playback. These pings will go from the end user device to Nielsen Collections servers.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will be excluded from AGF's reach measurement.'''

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

=== Data quality for long-duration video measurement ===

The Audit ping is used to enrich the S2S measurement data with device details and country which are mandatory for the measurement data delivered to AGF. If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will be excluded from AGF's reach measurement.

'''In order to maximize the data quality for long-duration video measurement, an additional start audit ping (“Startstream = 1”) should be sent every 3 hours''' in addition to the 2 standard pings (start audit ping (“Startstream = 1” and end audit ping (“Endstream = 3”))). An example audit ping call sequence will then look as follows:
* user starts a video playback at x hour : start audit ping (“Startstream = 1”)
* user continues to watch this video at x+3 hour : start audit ping (“Startstream = 1”)
* user continues to watch this video at x+6 hour : start audit ping (“Startstream = 1”)
* user ends the video playback at x+7 hour : end audit ping (“Endstream = 3”)

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

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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 is interrupted 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID)|| || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-22T15:29:15Z

MichelFodjo: /* Description */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Option 1: Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Option 2: Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

'''The first hour of the day''' used in the following description of the optimization refers to '''03:00:00 AM to 03:59:59 AM German local time''' (01:00:00 AM to 01:59:59 AM UTC during daylight saving time; 02:00:00 AM to 02:59:59 AM UTC during standard time).

====Option 1: Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 02:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Option 2: Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''
* The metadata reported in the AGF measurement data for a given assetid (including episode title, duration, and custom variables nol_c0–nol_c19) is locked in by the first video request of the day and its corresponding hourly metadata file. Subsequent metadata changes during the day will be ignored.

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid)
||
'''Use only if the asset metadata file optimization is not used and is delivered per platform with this subbrand value'''

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

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF.
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider.
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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. Must match streamid in Audit Ping. || 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Use only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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 usage, one '''start''' and one '''end''' for each video stream playback. These pings will go from the end user device to Nielsen Collections servers.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will be excluded from AGF's reach measurement.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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 is interrupted 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID)|| || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-21T07:52:56Z

MichelFodjo: /* query param list */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Option 1: Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Option 2: Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

'''The first hour of the day''' used in the following description of the optimization refers to '''03:00:00 AM to 03:59:59 AM German local time''' (01:00:00 AM to 01:59:59 AM UTC during daylight saving time; 02:00:00 AM to 02:59:59 AM UTC during standard time).

====Option 1: Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 02:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Option 2: Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''
* The metadata reported in the AGF measurement data for a given assetid (including episode title, duration, and custom variables nol_c0–nol_c19) is locked in by the first video request of the day and its corresponding hourly metadata file. Subsequent metadata changes during the day will be ignored.

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid)
||
'''Use only if the asset metadata file optimization is not used and is delivered per platform with this subbrand value'''

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

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF.
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider.
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Use only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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 usage, one '''start''' and one '''end''' for each video stream playback. These pings will go from the end user device to Nielsen Collections servers.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will be excluded from AGF's reach measurement.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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 is interrupted 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID)|| || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-21T07:16:58Z

MichelFodjo: /* Introduction */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Option 1: Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Option 2: Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

'''The first hour of the day''' used in the following description of the optimization refers to '''03:00:00 AM to 03:59:59 AM German local time''' (01:00:00 AM to 01:59:59 AM UTC during daylight saving time; 02:00:00 AM to 02:59:59 AM UTC during standard time).

====Option 1: Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 02:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Option 2: Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''
* The metadata reported in the AGF measurement data for a given assetid (including episode title, duration, and custom variables nol_c0–nol_c19) is locked in by the first video request of the day and its corresponding hourly metadata file. Subsequent metadata changes during the day will be ignored.

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid)
||
'''Use only if the asset metadata file optimization is not used and is delivered per platform with this subbrand value'''

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

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF.
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider.
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Use only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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 usage, one '''start''' and one '''end''' for each video stream playback. These pings will go from the end user device to Nielsen Collections servers.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will be excluded from AGF's reach measurement.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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 is interrupted 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-20T16:33:51Z

MichelFodjo: /* Description */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Option 1: Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Option 2: Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

'''The first hour of the day''' used in the following description of the optimization refers to '''03:00:00 AM to 03:59:59 AM German local time''' (01:00:00 AM to 01:59:59 AM UTC during daylight saving time; 02:00:00 AM to 02:59:59 AM UTC during standard time).

====Option 1: Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 02:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Option 2: Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''
* The metadata reported in the AGF measurement data for a given assetid (including episode title, duration, and custom variables nol_c0–nol_c19) is locked in by the first video request of the day and its corresponding hourly metadata file. Subsequent metadata changes during the day will be ignored.

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid)
||
'''Use only if the asset metadata file optimization is not used and is delivered per platform with this subbrand value'''

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

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF.
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider.
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Use only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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 usage, one '''start''' and one '''end''' for each video stream playback. These pings will go from the end user device to Nielsen Collections servers.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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 is interrupted 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-20T16:31:29Z

MichelFodjo: /* Description */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Option 1: Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Option 2: Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

'''The first hour of the day''' used in the following description of the optimization refers to '''03:00:00 AM to 03:59:59 AM German local time''' (01:00:00 AM to 01:59:59 AM UTC during daylight saving time; 02:00:00 AM to 02:59:59 AM UTC during standard time).

====Option 1: Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 02:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Option 2: Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''
* '''The metadata reported in the AGF measurement data for a given assetid (including episode title, duration, and custom variables nol_c0–nol_c19) is locked in by the first video request of the day and its corresponding hourly metadata file. Subsequent metadata changes during the day will be ignored.'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid)
||
'''Use only if the asset metadata file optimization is not used and is delivered per platform with this subbrand value'''

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

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF.
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider.
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Use only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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 usage, one '''start''' and one '''end''' for each video stream playback. These pings will go from the end user device to Nielsen Collections servers.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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 is interrupted 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-20T16:15:51Z

MichelFodjo: /* Description */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Option 1: Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Option 2: Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

'''The first hour of the day''' used in the following description of the optimization refers to '''03:00:00 AM to 03:59:59 AM German local time''' (01:00:00 AM to 01:59:59 AM UTC during daylight saving time; 02:00:00 AM to 02:59:59 AM UTC during standard time).

====Option 1: Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 02:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Option 2: Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''
* '''If the metadata values i.e. custom variables (nol_c0 to nol_c19) for a given assetid change during the day,the first meta data value from the first hour of the day is the one which will be used for the data aggregation.'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid)
||
'''Use only if the asset metadata file optimization is not used and is delivered per platform with this subbrand value'''

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

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF.
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider.
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Use only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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 usage, one '''start''' and one '''end''' for each video stream playback. These pings will go from the end user device to Nielsen Collections servers.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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 is interrupted 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-20T15:58:52Z

MichelFodjo: /* Introduction */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Option 1: Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Option 2: Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

'''The first hour of the day''' used in the following description of the optimization refers to '''03:00:00 AM to 03:59:59 AM German local time''' (01:00:00 AM to 01:59:59 AM UTC during daylight saving time; 02:00:00 AM to 02:59:59 AM UTC during standard time).

====Option 1: Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 02:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Option 2: Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid)
||
'''Use only if the asset metadata file optimization is not used and is delivered per platform with this subbrand value'''

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

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF.
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider.
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Use only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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 usage, one '''start''' and one '''end''' for each video stream playback. These pings will go from the end user device to Nielsen Collections servers.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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 is interrupted 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-20T15:52:39Z

MichelFodjo: /* Description */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Option 1: Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Option 2: Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

'''The first hour of the day''' used in the following description of the optimization refers to '''03:00:00 AM to 03:59:59 AM German local time''' (01:00:00 AM to 01:59:59 AM UTC during daylight saving time; 02:00:00 AM to 02:59:59 AM UTC during standard time).

====Option 1: Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 02:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Option 2: Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid)
||
'''Use only if the asset metadata file optimization is not used and is delivered per platform with this subbrand value'''

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

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF.
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider.
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Use only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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 is interrupted 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-20T15:51:46Z

MichelFodjo: /* Description */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Option 1: Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Option 2: Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

'''The first hour of the day''' used in the following description of the optimization refers to '''03:00:00 AM to 03:59:59 AM German local time''' (01:00:00 AM to 01:59:59 AM UTC during daylight saving time; 02:00:00 AM to 02:59:59 AM UTC during standard time).

====Option 1: Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 02:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Option 2: Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid)
||
'''Use only if the asset metadata file optimization is not used and is delivered per platform with this subbrand value'''

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

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF.
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Use only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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 is interrupted 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-20T15:32:22Z

MichelFodjo: /* SLA */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Option 1: Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Option 2: Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

'''The first hour of the day''' used in the following description of the optimization refers to '''03:00:00 AM to 03:59:59 AM German local time''' (01:00:00 AM to 01:59:59 AM UTC during daylight saving time; 02:00:00 AM to 02:59:59 AM UTC during standard time).

====Option 1: Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 02:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Option 2: Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid)
||
'''Use only if the asset metadata file optimization is not used and is delivered per platform with this subbrand value'''

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

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Use only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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 is interrupted 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-20T15:15:37Z

MichelFodjo: /* Description */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Option 1: Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Option 2: Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

'''The first hour of the day''' used in the following description of the optimization refers to '''03:00:00 AM to 03:59:59 AM German local time''' (01:00:00 AM to 01:59:59 AM UTC during daylight saving time; 02:00:00 AM to 02:59:59 AM UTC during standard time).

====Option 1: Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 02:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Option 2: Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid)
||
'''Use only if the asset metadata file optimization is not used and is delivered per platform with this subbrand value'''

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

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Use only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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 is interrupted 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-20T15:14:18Z

MichelFodjo: /* Description */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Option 1: Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Option 2: Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

'''The first hour of the day''' used in the following description of the optimization refers to '''03:00:00 AM to 03:59:59 AM German local time''' (01:00:00 AM to 01:59:59 AM UTC during daylight saving time; 02:00:00 AM to 02:59:59 AM UTC during standard time).

====Option 1: Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 02:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Option 2: Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid)
||
'''Note:'''
'''Use only if the asset metadata file optimization is not used and is delivered per platform with this subbrand value'''

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

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Use only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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 is interrupted 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-20T15:08:58Z

MichelFodjo: /* Description */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Option 1: Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Option 2: Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

'''The first hour of the day''' used in the following description of the optimization refers to '''03:00:00 AM to 03:59:59 AM German local time''' (01:00:00 AM to 01:59:59 AM UTC during daylight saving time; 02:00:00 AM to 02:59:59 AM UTC during standard time).

====Option 1: Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 02:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Option 2: Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Use only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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 is interrupted 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-20T14:59:36Z

MichelFodjo: /* Introduction */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Option 1: Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Option 2: Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

'''The first hour of the day''' used in the following description of the optimization refers to '''03:00:00 AM to 03:59:59 AM German local time''' (01:00:00 AM to 01:59:59 AM UTC during daylight saving time; 02:00:00 AM to 02:59:59 AM UTC during standard time).

====Option 1: Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 02:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Option 2: Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Ue only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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 is interrupted 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-20T07:49:40Z

MichelFodjo: /* Asset Metadata Delivery Optimization */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Option 1: Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Option 2: Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

'''The first hour of the day''' used in the following description of the optimization refers to '''03:00:00 AM to 03:59:59 AM German local time''' (01:00:00 AM to 01:59:59 AM UTC during daylight saving time; 02:00:00 AM to 02:59:59 AM UTC during standard time).

====Option 1: Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 02:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Option 2: Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Ue only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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 is interrupted 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-20T07:43:38Z

MichelFodjo: /* Streams */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

'''The first hour of the day''' used in the following description of the optimization refers to '''03:00:00 AM to 03:59:59 AM German local time''' (01:00:00 AM to 01:59:59 AM UTC during daylight saving time; 02:00:00 AM to 02:59:59 AM UTC during standard time).

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 02:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Ue only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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 is interrupted 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-20T07:40:45Z

MichelFodjo: /* Streams */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

'''The first hour of the day''' used in the following description of the optimization refers to '''03:00:00 AM to 03:59:59 AM German local time''' (01:00:00 AM to 01:59:59 AM UTC during daylight saving time; 02:00:00 AM to 02:59:59 AM UTC during standard time).

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 02:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Ue only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-20T07:16:04Z

MichelFodjo: /* Introduction */ line break removed

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

'''The first hour of the day''' used in the following description of the optimization refers to '''03:00:00 AM to 03:59:59 AM German local time''' (01:00:00 AM to 01:59:59 AM UTC during daylight saving time; 02:00:00 AM to 02:59:59 AM UTC during standard time).

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 02:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Ue only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-17T13:04:34Z

MichelFodjo: /* Asset Metadata File for the hour 02:00:00 AM UTC to 01:59:59 AM UTC */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

'''The first hour of the day''' used in the following description of the optimization refers to '''03:00:00 AM to 03:59:59 AM German local time''' (01:00:00 AM to 01:59:59 AM UTC during daylight saving time; 02:00:00 AM to 02:59:59 AM UTC during standard time).

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 02:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Ue only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-17T13:03:04Z

MichelFodjo: /* Asset Metadata Delivery Optimization */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

'''The first hour of the day''' used in the following description of the optimization refers to '''03:00:00 AM to 03:59:59 AM German local time''' (01:00:00 AM to 01:59:59 AM UTC during daylight saving time; 02:00:00 AM to 02:59:59 AM UTC during standard time).

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Ue only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-17T12:55:17Z

MichelFodjo: /* Asset Metadata Delivery Optimization */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

'''The first hour of the day'' used in the following description of the optimization refers to '''03:00:00 AM to 03:59:59 AM German local time''' (01:00:00 AM to 01:59:59 AM UTC during daylight saving time; 02:00:00 AM to 02:59:59 AM UTC during standard time).

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Ue only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-17T12:54:12Z

MichelFodjo: /* Asset Metadata Delivery Optimization */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

The first hour of the day used in the following description of the optimization refer to '''03:00:00 AM to 03:59:59 AM German local time''' (01:00:00 AM to 01:59:59 AM UTC during daylight saving time; 02:00:00 AM to 02:59:59 AM UTC during standard time).

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Ue only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-17T12:39:30Z

MichelFodjo: /* Optimization when the Asset Metadata File remains unchanged during the whole day per platform */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day ('''01:00:00 AM UTC to 01:59:59 AM UTC''' and it will be referenced in the manifest file for the following 23 hours of the day. The first hour of the day '''01:00:00 AM UTC to 01:59:59 AM UTC''' corresponds to the following '''german local time''':
* during daylight saving time
** 03:00:00 AM to 03:59:59 AM
* during standard time
** 02:00:00 AM to 02:59:59 AM

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Ue only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-17T12:38:37Z

MichelFodjo: /* Optimization when the Asset Metadata File remains unchanged during the whole day per platform */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day ('''01:00:00 AM UTC to 01:59:59 AM UTC''' and it will be referenced in the manifest file for the following 23 hours of the day. The first hour of the day '''01:00:00 AM UTC to 01:59:59 AM UTC''' corresponds to the following '''german local time'':
* during daylight saving time
** 03:00:00 AM to 03:59:59 AM
* during standard time
** 02:00:00 AM to 02:59:59 AM

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Ue only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-17T12:19:19Z

MichelFodjo: /* File Name (FileName) format for the Asset Metadata and Asset Viewing Files */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 viewership pipelines (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Ue only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

Germany Special Characters

2026-07-16T10:29:35Z

MichelFodjo: Created page with "{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}} Category:Digital '''Special characters''' are characters which are not URL safe and include the following: {| class="wikitable" |- ! Character !! Description |- | " " || Space |- | # || Pound |- | $ || Dollar |- | % || Percent |- | @ || 'At' symbol |- | ` || Grave Accent |- | \ || Backslash |- | : || Colon |- | ; || Semi-colon |- | < || 'Less than' symbol |..."

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

'''Special characters''' are characters which are not URL safe and include the following:

{| class="wikitable"
|-
! Character !! Description
|-
| " " || Space
|-
| # || Pound
|-
| $ || Dollar
|-
| % || Percent
|-
| @ || 'At' symbol
|-
| ` || Grave Accent
|-
| \ || Backslash
|-
| : || Colon
|-
| ; || Semi-colon
|-
| < || 'Less than' symbol
|-
| = || Equal
|-
| > || 'Greater than' symbol
|-
| ? || Question Mark
|-
| [ || Left Square Bracket
|-
| ] || Right Square Bracket
|-
| ^ || Caret
|-
| { || Left Curly Brace
|-
| <nowiki>|</nowiki> || Bar
|-
| } || Right Curly Brace
|-
| ~ || Tilde
|-
| “ || Left Double quote
|-
| ” || Right Double quote
|-
| ‘ || Left Single Quote
|-
| ’ || Right Single Quote
|-
| + || Plus
|-
| , || Comma
|}

DCR Germany Video S2S

2026-07-16T10:18:04Z

MichelFodjo: /* Description */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Ue only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-16T10:17:38Z

MichelFodjo: /* Description */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Ue only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-16T10:12:07Z

MichelFodjo: /* OTT, Mirroring, and Casting */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Ue only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S device casting example]]

{ // ...
"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.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

File:S2S casting example.png

2026-07-16T07:00:21Z

MichelFodjo: S2S device casting example

== Summary ==
S2S device casting example

DCR Germany Video S2S

2026-07-16T06:59:43Z

MichelFodjo: /* OTT, Mirroring, and Casting */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Ue only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:S2S_casting_example.png|S2S_casting_example.png]]

{ // ...
"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.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-15T13:27:16Z

MichelFodjo: /* Introduction */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Ue only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:France MM S2S casting example.png|France MM S2S casting example.png]]

{ // ...
"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.
* '''<pre style="color: red">NOTE:</pre> '''
** '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-15T13:21:17Z

MichelFodjo: /* Introduction */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Ue only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:France MM S2S casting example.png|France MM S2S casting example.png]]

{ // ...
"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.
* '''NOTE:''' '''If Nielsen does not receive the Audit pings, the viewing data cannot be enriched (with device details and country) and will not be included in the measurement data delivered to AGF.'''

'''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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-15T13:12:57Z

MichelFodjo: /* Introduction */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Ue only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:France MM S2S casting example.png|France MM S2S casting example.png]]

{ // ...
"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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-15T13:11:30Z

MichelFodjo: /* Streams */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Ue only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:France MM S2S casting example.png|France MM S2S casting example.png]]

{ // ...
"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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-15T13:10:35Z

MichelFodjo: /* Streams */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Ue only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:France MM S2S casting example.png|France MM S2S casting example.png]]

{ // ...
"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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-15T13:09:52Z

MichelFodjo: /* Introduction */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Ue only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:France MM S2S casting example.png|France MM S2S casting example.png]]

{ // ...
"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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-15T13:08:39Z

MichelFodjo: /* Android Platform : Example Metadata with "device_id" */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Ue only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:France MM S2S casting example.png|France MM S2S casting example.png]]

{ // ...
"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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-15T13:08:12Z

MichelFodjo: /* Example */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Ue only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}
]
}

</syntaxhighlight>

===== Android Platform : Example Metadata with "device_id" =====

====== "device_id" available ======
<syntaxhighlight lang="javascript">
{
"device_id": "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826"
}
</syntaxhighlight>

====== "device_id" not available ======
<syntaxhighlight lang="javascript">
{
"device_id": ""
}
</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:France MM S2S casting example.png|France MM S2S casting example.png]]

{ // ...
"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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-15T13:06:40Z

MichelFodjo: /* Description */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| subbrand || subbrand (vcid)
||

'''Ue only if the asset metadata file is optimized and delivered once for all platforms and subbrand is not included in the asset metadata file.'''

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)
||

|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}

</syntaxhighlight>

===== Android Platform : Example Metadata with "device_id" =====

====== "device_id" available ======
<syntaxhighlight lang="javascript">
{
"device_id": "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826"
}
</syntaxhighlight>

====== "device_id" not available ======
<syntaxhighlight lang="javascript">
{
"device_id": ""
}
</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:France MM S2S casting example.png|France MM S2S casting example.png]]

{ // ...
"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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>

DCR Germany Video S2S

2026-07-15T12:25:36Z

MichelFodjo: /* Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

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.

<pre style="color: orange"; font-weight: bold;>
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!
</pre>

__TOC__

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

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (AppID)''' || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Integration ID (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.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| 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 Nielsen Digital Content
Ratings (DCR) product.
* The end-user viewing data captured within an hour are delivered to Nielsen through:
** The Asset Metadata file
** The Asset Viewing file
* '''The Asset Metadata file should arrive before the Asset Viewing file for the same 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 its own unique asset id.

==SLA==
The 4 files to be delivered within the SLA are:
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

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

'''When SLA for receiving the 4 files 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.
'''<pre style="color: red">NOTE:</pre>'''
* <pre style="color: red">Any files that missed the SLA will not be processed and hence not included in the measurement data delivered to AGF.</pre>

==Accuracy of the Measurement==

====Send the viewing time (video player events) at least each 10 seconds to your backend====
Capture the 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 the viewing time to your backend 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 '''
<syntaxhighlight lang="javascript">
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
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered '''hourly''' 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 formats for '''Asset Metadata''' and '''Asset Viewing files''' 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 delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! 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'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| 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======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====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'''
{| class="wikitable"
|-
! 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 (dcr, etc).
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|-
| 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:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====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":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"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:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, "S2SV1.7.1" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| 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 [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose 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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======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

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

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

</code>
=====Asset Viewing Delivery Files=====
<code>
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

</code>

===Asset Metadata Delivery Optimization===

* '''Optimization per platform''' when the Asset Metadata File remains unchanged per platform during the whole day
* '''Optimization for all platforms''' when the Asset Metadata File remains unchanged for all platforms during the whole day

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 02 (02:00:00 AM UTC to 02:59:59 AM UTC), referencing to the Asset Metadata File for HOUR 01'''

=====Asset Metadata File for the hour 02:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 01):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052502_2022052503_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.1",
"start_time": "1653444000",
"end_time": "1653447599",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/02/_SUCCESS
</code>

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day (01:00:00 AM UTC to 01:59:59 AM UTC '''corresponding''' to 03:00:00 AM UTC to 03:59:59 AM german local time) and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 01 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/01/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 01:00:00 AM UTC to 01:59:59 AM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052501_2022052502.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.1",
"start_time": "1653440400",
"end_time": "1653443999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/01/_SUCCESS
</code>

== 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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SAssetMetaDataDCRV2.10" || ✓
|-
| 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.10",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || length || 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 || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Videoteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes", etc ||
|-
| nol_c18 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || Genre
||
* Valid from January 1, 2027
* The custom variable ‘Genre’ contains genre information. To be populated in consultation with AGF. For Ad, the field remains blank "".
||
|-s
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || Product ID
||
* Valid from January 1, 2027
* The custom variable ‘Product ID’ contains a unique ID across all formats (streaming and TV) that uniquely identifies a product (e.g. an individual episode of a series, a feature film) per provider. For ads, the field remains blank "".
||
|-
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== 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'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SViewingDataV1.7.1" || ✓
|-
| appid || The AppID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen. || 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=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.1",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Germany Special Characters|Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-style="background-color:#d0f6f8;"
| adsupportflag || user ad-supported subscription model ||

* "0" non-ad-supported subscription models
* "1" ad-supported subscription models

'''Note:'''

* For broadcasters without any ad-supported subscription models, please pass the value "0" or do not pass "adsupportflag" at all to Nielsen in the metadata
* If no value is passed to Nielsen for "adsupportflag", the default value for AGF is non-ad-supported subscription models

||
|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''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 || '''ONLY for''' '''android''' platform, DO NOT pass device_id for '''ios''', '''browser''' and '''ott''' platforms. Mobile Ad 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" - OPTIONAL if passed in the Audit Ping|| i.e "12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8" || ✓
|-
| xdua || Device HTTP raw User Agent string - OPTIONAL if passed in the Audit Ping|| Example: "Apple-iPhone1C2/801.293" || ✓
|-
| xff || IP address - OPTIONAL if passed in the Audit Ping|| 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"
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // 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"
}

</syntaxhighlight>

===== Android Platform : Example Metadata with "device_id" =====

====== "device_id" available ======
<syntaxhighlight lang="javascript">
{
"device_id": "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826"
}
</syntaxhighlight>

====== "device_id" not available ======
<syntaxhighlight lang="javascript">
{
"device_id": ""
}
</syntaxhighlight>

==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 the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:France MM S2S casting example.png|France MM S2S casting example.png]]

{ // ...
"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:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(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'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || The apid is a unique ID assigned to the player/site/app. This will be provided upon starting the integration by Nielsen.
|| 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 || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

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

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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;
}

</syntaxhighlight>