Digital Measurement SEI Content Asset Metadata: Difference between revisions

From Engineering Client Portal

(Created page with "{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}} Category:Digital")
 
(Update to new version)
 
Line 1: Line 1:
{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}The Nielsen "Server-To-Server" method of collecting DCR data requires the distributor to make available each Asset (Episode) referenced in the DCR Viewing file in a separate metadata file (a.k.a metadata catalog).
 
== Naming Convention and Delivery Specification ==
Consolidated list of asset metadata catalog that is up to date for a particular hour needs to be provided in a single file following the naming convention specified below. The metadata needs to be in a json lines format, including a header line. A reasonable effort needs to be made to remove expired/inactive asset ids, to avoid size creep.
 
Nielsen will move files to indicate they are being processed.
 
'''S3 bucket naming convention:'''
useast1-nlsn-w-dig-sei-<partner_id>-feeds-<env>/<s3_prefix>/<s3_object>
'''S3 prefix naming convention:'''
<file_type>/yyyy/mm/dd/hh
'''S3 object naming convention:'''
<partner_id>_<file_type>_<int_id>[.gz|.bz2]
{| class="wikitable"
|'''partner_id'''
|'''Partner id provided by Nielsen (4 letter code or TICK symbol, a.k.a. publisher id) in human readable format.'''
|-
|env
|<nowiki>[ test | prod ]</nowiki>
|-
|int_id
|Integration id provided by Nielsen. Used to link different integration inputs, ex.  associate single audit ping integration with different viewsership pipelines (dar, dtvr, dcr, etc.)
|-
|file_type
|[ dcrassetmetadata ]
|-
|/yyyy/mm/dd/hh/
|year/month/day/hour (including leading zeros, starting from 00 hour )
 
ex.: 2023/02/12/05
|-
|<nowiki>[.gz|.bz2]</nowiki>
|Uncompressed json lines (no extension) -  splittable, ideal for medium size files, less than 5 GB, preferred for metadata. Optional compression formats supported:
 
* [.gz] - non splittable, requires multiple files, if data larger than 32 MB
* [.bz2]- splittable, preferred for larger files, above 256 MB (block size 256MB)  (in development)
|}
'''Example of a file for 10:00 EST to 11:00 AM EST:'''
useast1-nlsn-w-dig-sei-acme-feeds-prod/dcrassetmetadata/2022/06/12/10/
 
acme_dcrassetmetadata_a9ddf15ea054ea415718767ea6
 
= SLA =
The files must be delivered into the proper S3 bucket within 2 hours of the broadcast. For example, files from 1:00 AM to 1:15 AM must be delivered before 3:00 AM. The metadata file should be delivered to an S3 bucket before any Viewing file has been delivered. Please refer to the associated specifications for the SLAs of these other files.
 
= JSON Param Definition =
'''Header Record:'''
{| class="wikitable"
|'''Parameter'''
|'''Description'''
|'''Mandatory'''
|'''Specified by'''
|'''Format or Example'''
|-
|schemaversion
|Json Schema Version
|Yes
|Nielsen
|Example: S2SAssetMetaDataDCRV2.0
|-
|mvpdid
|Server App ID
|Yes
|Nielsen
|Example: NLSN
|-
|creationtime
|File creation time
|Yes
|Client
|Format: utc (time in 32-bit unsigned int UTC in seconds)
|-
|recordcount
|# of records in body of file
|Yes
|Client
|Format: numeric
 
In this schema implementation this value is set to "1", as each file will only contain the metadata associated to a single asset
|}
'''Header JSON Schema:'''
{
 
   "$schema": "<nowiki>http://json-schema.org/draft-04/schema#</nowiki>",
 
   "type": "object",
 
   "properties": {
 
     "schemaversion": { "type": "string" },
 
     "mvpdid": { "type": "string" },
 
     "creationtime": { "type": "string" },
 
     "recordcount": { "type": "string" }
 
   },
 
   "required": [ "schemaversion", "appid", "creationtime", "recordcount" ]
 
}
'''Header Record - Example:'''
{"schemaversion":"S2SAssetMetaDataDCRV2.0","mvpdid":"NLSN","creationtime":"1473781507","recordcount":"1"}
 
 
'''Body Record:'''
{| class="wikitable"
|'''Parameter'''
|'''Description'''
|'''Mandatory'''
|'''Specified by'''
|'''Format or Example'''
|-
|assetid
|In-house asset id
|Yes
|Client
|Format: alphanumeric,
 
Example: VID123456789
 
AssetId needs to be unique at episode level
|-
|assetname
|In-house video asset name,
 
for troubleshooting
|Yes
|Client
|Format: alphanumeric
 
Examples: TMS ID, EIDR ID or Episode title
|-
|programname
|Name of the program
|Yes
|Client
|Format: alphanumeric, Max 25 char’s; no special characters
 
Example: Nightly News
 
See below for more specific guidance on Program Name
|-
|episodetitle
|Title of the episode
|Yes
|Client
|Format: alphanumeric,
 
Examples: News: “Prime Time News YYYY-MM-DD”
 
TV Show: “The Greatest American Hero S2E23”
 
Movie: “Movie Title”
 
See below for more specific guidance on Episode Title
|-
|episodelen
|Total episode length
|Yes
|Client
|Format: Integer (seconds)
 
Example: 3600
 
For continuous live stream or unknown duration use 24*60*60 (86400)
 
Can be updated with a replacement asset file when the live playout ends, and the exact duration becomes known
|-
|isfullepisode
|Full episode Flag
 
(indicates full episode or a clip)
|Yes
|Client
|Format: integer – 0 (not full episode), 1 (full episode)
|-
|genre
|Nielsen genre code
|No
|Client
|Format: alphanumeric
 
Example: CV (comedy variety), N (news)
 
Contact Nielsen Technical support for a list of current Genre codes
|-
|airdate
|The date the episode was first made available on Traditional TV
|No
|Client
|Format: US ET:  YYYYMMDDHHMMSS
 
Example: 19970716231256
 
For the US, the time should be specified as Eastern Timezone. Other countries will use a local timezone.
 
Used as default episode name if metadata not available
 
This value can be updated with a replacement asset file if the original air date changes
|-
|webpageurl
|Website Identifier, for diagnostics, can be turned off/on as needed
|No
|Client
|Format: alphanumeric  (max 2k)
 
Example:<nowiki>https://www.myapp.com/video.html</nowiki>
|-
|crossrefId1
|Content owner’s episode asset id. Used for secondary crediting
|No
|Client
|Format: alphanumeric
 
Example: TMS ID, EIDR ID or Episode title
 
Note: this field only needs to be populated by Distributors
|-
|crossrefId2
|Content owner. Used for secondary crediting
|Yes
|Client
|Format: alphabetical - Gracenote, channel mnemonic or Nielsen channel mnemonic
 
Example: AMC
 
Contact Nielsen for a list of current Nielsen channel codes
 
Note: this field only needs to be populated by Distributors
|}
Note: All parameters are case sensitive.
'''Body - Example:'''
{"assetid":"VID123456789", "assetname":"myassetname", "programname":"Nightly News","episodetitle":"Prime Time News S2E23", "episodelen":"2000", "isfullepisode":"true", "genre":"N", "airdate":"19970716231256", "webpageurl":"<nowiki>http://www.myapp.com/video.html</nowiki>", "crossrefId1":"myepisodeid", "crossrefId2":"networkxyz"}
 
=== Additional Guidance on Program & Episode Metadata ===
If the intention is that the DCR metadata also be used for TCR (Total Content Ratings). Then the DCR Program & Episode name should be identical to the Program & Episode name that is used in Traditional TV Ratings. It is recommended to use the metadata registered in Nielsen TV Names systems (myEVNTS/myVOD). If a Nielsen TV Names systems is not used, then you may use the Program & Episode name registered with a 3rd party television listing service such as GraceNote.
 
Nielsen recommends the following format for Episode name:
 
Format: Episode Title + Season # + Episode # (e.g.  Title S3E1).
 
Values:  A minimum of one of the values below should be provided:
 
* Episode Title: must be first value if provided
* Season #: must follow Episode Title if provided
* Episode #: must follow Season # if provided
 
NOTE: It is recommended to pass all three values if available.
 
Identifiers:
 
* Season: 'Season', 'S'
* Episode: 'Episode', 'E', 'Ep'
* Not case sensitive
 
Delimiters:
 
* Supported delimiters: ' ' (space), ':', '.'
* Delimiters are optional
 
Characters:
 
* 40 character limit
* No special characters
 
You may reference the examples below to determine if you are passing a valid episode name:
 
* Valid: 'Title S2E9', 'Title S.2 EP.9', 'Title Episode:9'
* Invalid (with reason):
** 'Title S-2 E-9' '-' is not a supported delimiter
** 'Title Episode9 Season2' Season # must precede Episode #
** 'Title  SE2  EP9' 'SE' is not a  valid  identifier
 
[[Category:Digital]]
[[Category:Digital]]

Latest revision as of 17:30, 5 June 2024

Engineering Portal / Digital / Digital Measurement SEI Content Asset Metadata
The Nielsen "Server-To-Server" method of collecting DCR data requires the distributor to make available each Asset (Episode) referenced in the DCR Viewing file in a separate metadata file (a.k.a metadata catalog).

Naming Convention and Delivery Specification

Consolidated list of asset metadata catalog that is up to date for a particular hour needs to be provided in a single file following the naming convention specified below. The metadata needs to be in a json lines format, including a header line. A reasonable effort needs to be made to remove expired/inactive asset ids, to avoid size creep.

Nielsen will move files to indicate they are being processed.

S3 bucket naming convention:

useast1-nlsn-w-dig-sei-<partner_id>-feeds-<env>/<s3_prefix>/<s3_object>

S3 prefix naming convention:

<file_type>/yyyy/mm/dd/hh

S3 object naming convention:

<partner_id>_<file_type>_<int_id>[.gz|.bz2]
partner_id Partner id provided by Nielsen (4 letter code or TICK symbol, a.k.a. publisher id) in human readable format.
env [ test | prod ]
int_id Integration id provided by Nielsen. Used to link different integration inputs, ex.  associate single audit ping integration with different viewsership pipelines (dar, dtvr, dcr, etc.)
file_type [ dcrassetmetadata ]
/yyyy/mm/dd/hh/ year/month/day/hour (including leading zeros, starting from 00 hour )

ex.: 2023/02/12/05

[.gz|.bz2] Uncompressed json lines (no extension) -  splittable, ideal for medium size files, less than 5 GB, preferred for metadata. Optional compression formats supported:
  • [.gz] - non splittable, requires multiple files, if data larger than 32 MB
  • [.bz2]- splittable, preferred for larger files, above 256 MB (block size 256MB) (in development)

Example of a file for 10:00 EST to 11:00 AM EST:

useast1-nlsn-w-dig-sei-acme-feeds-prod/dcrassetmetadata/2022/06/12/10/
acme_dcrassetmetadata_a9ddf15ea054ea415718767ea6

SLA

The files must be delivered into the proper S3 bucket within 2 hours of the broadcast. For example, files from 1:00 AM to 1:15 AM must be delivered before 3:00 AM. The metadata file should be delivered to an S3 bucket before any Viewing file has been delivered. Please refer to the associated specifications for the SLAs of these other files.

JSON Param Definition

Header Record:

Parameter Description Mandatory Specified by Format or Example
schemaversion Json Schema Version Yes Nielsen Example: S2SAssetMetaDataDCRV2.0
mvpdid Server App ID Yes Nielsen Example: NLSN
creationtime File creation time Yes Client Format: utc (time in 32-bit unsigned int UTC in seconds)
recordcount # of records in body of file Yes Client Format: numeric

In this schema implementation this value is set to "1", as each file will only contain the metadata associated to a single asset

Header JSON Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "schemaversion": { "type": "string" },
    "mvpdid": { "type": "string" },
    "creationtime": { "type": "string" },
    "recordcount": { "type": "string" }
  },
  "required": [ "schemaversion", "appid", "creationtime", "recordcount" ]
}

Header Record - Example:

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


Body Record:

Parameter Description Mandatory Specified by Format or Example
assetid In-house asset id Yes Client Format: alphanumeric,

Example: VID123456789

AssetId needs to be unique at episode level

assetname In-house video asset name,

for troubleshooting

Yes Client Format: alphanumeric

Examples: TMS ID, EIDR ID or Episode title

programname Name of the program Yes Client Format: alphanumeric, Max 25 char’s; no special characters

Example: Nightly News

See below for more specific guidance on Program Name

episodetitle Title of the episode Yes Client Format: alphanumeric,

Examples: News: “Prime Time News YYYY-MM-DD”

TV Show: “The Greatest American Hero S2E23”

Movie: “Movie Title”

See below for more specific guidance on Episode Title

episodelen Total episode length Yes Client Format: Integer (seconds)

Example: 3600

For continuous live stream or unknown duration use 24*60*60 (86400)

Can be updated with a replacement asset file when the live playout ends, and the exact duration becomes known

isfullepisode Full episode Flag

(indicates full episode or a clip)

Yes Client Format: integer – 0 (not full episode), 1 (full episode)
genre Nielsen genre code No Client Format: alphanumeric

Example: CV (comedy variety), N (news)

Contact Nielsen Technical support for a list of current Genre codes

airdate The date the episode was first made available on Traditional TV No Client Format: US ET:  YYYYMMDDHHMMSS

Example: 19970716231256

For the US, the time should be specified as Eastern Timezone. Other countries will use a local timezone.

Used as default episode name if metadata not available

This value can be updated with a replacement asset file if the original air date changes

webpageurl Website Identifier, for diagnostics, can be turned off/on as needed No Client Format: alphanumeric  (max 2k)

Example:https://www.myapp.com/video.html

crossrefId1 Content owner’s episode asset id. Used for secondary crediting No Client Format: alphanumeric

Example: TMS ID, EIDR ID or Episode title

Note: this field only needs to be populated by Distributors

crossrefId2 Content owner. Used for secondary crediting Yes Client Format: alphabetical - Gracenote, channel mnemonic or Nielsen channel mnemonic

Example: AMC

Contact Nielsen for a list of current Nielsen channel codes

Note: this field only needs to be populated by Distributors

Note: All parameters are case sensitive. Body - Example:

{"assetid":"VID123456789", "assetname":"myassetname", "programname":"Nightly News","episodetitle":"Prime Time News S2E23", "episodelen":"2000", "isfullepisode":"true", "genre":"N", "airdate":"19970716231256", "webpageurl":"http://www.myapp.com/video.html", "crossrefId1":"myepisodeid", "crossrefId2":"networkxyz"}

Additional Guidance on Program & Episode Metadata

If the intention is that the DCR metadata also be used for TCR (Total Content Ratings). Then the DCR Program & Episode name should be identical to the Program & Episode name that is used in Traditional TV Ratings. It is recommended to use the metadata registered in Nielsen TV Names systems (myEVNTS/myVOD). If a Nielsen TV Names systems is not used, then you may use the Program & Episode name registered with a 3rd party television listing service such as GraceNote.

Nielsen recommends the following format for Episode name:

Format: Episode Title + Season # + Episode # (e.g.  Title S3E1).

Values:  A minimum of one of the values below should be provided:

  • Episode Title: must be first value if provided
  • Season #: must follow Episode Title if provided
  • Episode #: must follow Season # if provided

NOTE: It is recommended to pass all three values if available.

Identifiers:

  • Season: 'Season', 'S'
  • Episode: 'Episode', 'E', 'Ep'
  • Not case sensitive

Delimiters:

  • Supported delimiters: ' ' (space), ':', '.'
  • Delimiters are optional

Characters:

  • 40 character limit
  • No special characters

You may reference the examples below to determine if you are passing a valid episode name:

  • Valid: 'Title S2E9', 'Title S.2 EP.9', 'Title Episode:9'
  • Invalid (with reason):
    • 'Title S-2 E-9' '-' is not a supported delimiter
    • 'Title Episode9 Season2' Season # must precede Episode #
    • 'Title  SE2  EP9' 'SE' is not a  valid  identifier