DTVR SEI Viewing
From Engineering Client Portal
This interface specification describes the file format that needs to be used to supply Nielsen with end-user viewing data captured by a “server-to-server” method for the Nielsen Digital TV Ratings (DTVR) product.
- The specification is defined using a JSON schema, with each file ideally containing all the viewing that has been captured within an hour.
- In the case of a stream that has one version with blackouts and one without, one with mobile and one non-mobile, each stream would have it’s own unique asset id.
- The audio file with related data should arrive before the viewing data file for the same hour.
SLA
The files must be delivered into the proper S3 bucket within 3 hours of the start of that viewing file interval. For example, files from 1:00 AM to 2:00 AM must be delivered before 4 AM.
File Naming Convention
File should be named with following convention: FileType_AppID _UTCStart_UTCEnd
File Type: DTVRViewingFile
AppID: app identifier
UTCStart (time in 32-bit unsigned int UTC in seconds from first second of audio captured)
UTCEnd (time in 32-bit unsigned int UTC in seconds from first second of audio captured)
Files should be placed in S3 buckets with the following folder structure:
[To be determined during design phase]
Nielsen will move files to another location as they are processed so processing status is apparent. Accuracy of measurement
These thresholds are currently under review during the Beta program period, and may change before data collected in this manner flows into Nielsen currency products.
The reported “wall clock” time of viewing needs to be within 25 seconds of the actual viewing
The reported content “reference” time needs to match the actual content that was played out with plus/minus 10 seconds (for clarity: start and end times can each be off by up to 10 seconds, so the combined under/over reporting for each individual viewing segment is no more than 20 seconds).
JSON Param Definition
Header Record
| Parameter | Description | Mandatory | Specified by | Format or Example |
| schemaversion | Json Schema Version | Yes | Nielsen | Example: S2SDTVRViewingV1.3 |
| apid | Server App ID | Yes | Nielsen | Example: A487421B-XXXX-YYYY-8343-E3BBB66E44F2 |
| type | Type of data | Yes | Client | Value: "content" |
| producttype | Product Type | Yes | Client | Value: "DTVR" |
| starttime | File Start Time | Yes | Client | Format: utc (time in 32-bit unsigned int UTC in seconds) |
| endtime | File End Time | Yes | Client | Format: utc (time in 32-bit unsigned int UTC in seconds) |
| recordcount | # of records in body of file | Yes | Client | Format: integer
Note: Multiple entries in position array still only count as a single record for the purposes of the file record count |
Header Record - Example:
{"schemaversion":"S2SDTVRViewingV1.3","apid":"A487421B-XXXX-YYYY-8343-E3BBB66E44F2","type":"content","producttype":"DTVR","starttime":"1473781507","endtime":"1473791507","recordcount":"14"}
Body
| Parameter | Description | Mandatory | Specified by | Format or Example | |
| apn | Client side App name | Yes | Client | Format: alphanumeric, Example: BestAppIOS | |
| apv | Client side App version | No | Client | Format: alphanumeric, Example: 1.3 | |
| sessionid | Unique id generated when player is instantiated | Yes | Client | Format: alphanumeric, Example: 16 char guid | |
| streamid | id for every new instance of an asset | Required if no sessionid | Client | Format: alphanumeric, Example: UTC or other random # | |
| sessionended | Session is known to have ended in this file | Yes | Client | Format: numeric,
Example: 1 (session will continue in next file), 2 (session closed) | |
| assetid | id for an asset
(could be TMS id) |
Yes | Client | Format: alphanumeric, Example: VID123456789 | |
| assetname | Video asset name
used for troubleshooting |
Yes | Client | Format: alphanumeric, Example: “A&E High Def East” or GraceNote channel mnemonic or call station letters | |
| origcontent | The origin of the content that is being played out | No | Client | Format : integer
0 – (assumed default if no value provided); content is being streamed from source other than user's device e.g. Cloud DVR, MVPD VoD Library, or Publisher live-feed 1 – content is being played out directly from user device e.g. local DVR | |
| picturemode | Picture in Picture Mode | No | Client | Format: integer – 0 (no PnP), 1 (PnP being used) | |
| secondscr | Second Screen Indicator. For Mirroring & Extended Screen via OTT device scenarios | No | Client | Format: alphanumeric, Example: MIR or OTT | |
| position | Array of contiguous content viewing | Yes | Client | Format:
[{ "referencestart":"utc", "referenceend":"utc", "playheadstart":"utc", "playheadend":"utc" "}] Additional Notes: * For viewing gaps less 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 | |
| { | referencestart | Wall clock reference start time | Yes | Client | Format: utc (time in 32-bit unsigned int UTC in seconds) |
| referenceend | Wall clock reference end time | Yes | Client | Format: utc (time in 32-bit unsigned int UTC in seconds) | |
| playheadstart | Content position start time | Yes | Client | Format: utc (time in 32-bit unsigned int UTC in seconds) | |
| } | playheadend | Content position end time | Yes | Client | Format: utc (time in 32-bit unsigned int UTC in seconds) |
| device_id | Mobile Ad ID (IDFA, ADID), Connected Device ID. Should not be the user ID.
If hashing required, SHA-256 is preferred |
Yes, for opted-in mobile devices where available | Client | A487421B-XXXX-YYYY-8343-E3BBB66E44F2 | |
| hem_sha256 | SHA-256 hashed email
Note: email normalization rules applied before hashing |
Strongly Preferred | Client | 55C06A30DAA5D5F382FDEB8C702EC57875CC9D91A7C78BB620053FD81DC4335C | |
| hem_md5 | MD5 hashed email
Note: email normalization rules applied before hashing |
Preferred | Client | 3E168605F46DFB596EB717b7C83ACBC0 | |
| hem_sha1 | SHA-1 hashed email
Note: email normalization rules applied before hashing |
Preferred | Client | 37B7410CD605DB6294318CDB174014F062F0E9C6 | |
| hem_other | Hashed email if hashing algorithm is unknown or not sha256, md5, or sha1 | Preferred | Client | 3E168605F46DFB596EB717b7C83ACBC0 | |
| luid | Living Unit ID - Experian Household ID | Yes, for CTV where available, or audit ping | Client | B0EOFEDgD | |
| xff | IP address | Yes | Client | Format: xxx.xxx.xxx.xxx or xxx.xxx.xxx.000
or 000.000.000.000 for opt-out | |
| xdua | Device User Agent | Desired | Client | Format: alphanumeric, Example: Apple-iPhone1C2/801.293 | |
| device_platform | Device Platform | Required if UA not shared | Client | Format: alphanumeric, Example DSK, MBL, OTT | |
| device_group | Device Group | Required if UA not shared | Client | Format: alphanumeric, Example PHN = phone, TAB = tablet, DSK = desktop, STV = Smart TV, UNWN = unknown | |
| os_group | OS Group | Required if UA not shared | Client | Format: alphanumeric, Example DROID, IOS, UNWN | |
Note: All parameters are case sensitive.
Body - Example:
{"apn":"BestAppiOS","apv":"1.1","sessionid":"123456789", "streamid":"123465435","sessionended":"1", "assetid":"vid345-67483","assetname":"ABC HD EAST","origcontent":"0","picturemode":"0","secondscr":"MIR","xff":"205.114.192.12","device_platform":"MBL","device_group":"PHN","os_group":"ios","xdua":"Apple-iPhone1C2/801.293","position":[{"referencestart":"utc","referenceend":"utc","playheadstart":"utc","playheadend":"utc"}