Digital Measurement Content Asset Metadata

Engineering Portal / Digital / US DCR & DTVR / Digital Measurement 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). 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.

Delivery Specifications

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.

S3 Bucket and Prefix Naming Convention

useast1-nlsn-w-dig-sei-<partnerid>-feeds-<env>/<filetype>/yyyy/mm/dd/hh/<object>

Name	Description
partnerid	Abbreviation provided by Nielsen for each provider or publisher
env	test or prod
filetype	dcrassetmetadata
split	a separate data split, can be by platform (ex.: ios, browser, android, ctv), by country (us, ca, jp, etc.), by publisher, by team, etc. or “all” (if data is provided in one split).
yyyy/mm/dd/hh	yyyy - year mm - month dd - date padded with 0 example 01, 02,..., 31 hh - hour padded with 0 example 00, 02,..., 23

S3 Bucket and Prefix Naming Convention

<partner_id>_<file_type>_<int_id>[.gz]

Name	Description
partnerid	Abbreviation provided by Nielsen for each provider or publisher
filetype	dcrassetmetadata
initid	integration id: unique identifier provided by Nielsen
[.gz]	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

Success File

Empty _SUCCESS file should be provided to indicate that data delivery for a particular hour and split is completed (even if there is no data for that particular hour and split).

Data delivery example for hour 10 (10:00:00 AM UTC to 10:59:59 PM UTC):

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

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

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.

Schema Parameter Definitions

Parameter		Description	Required	Format / Example
assetid		In-house id used for a video asset (TMS ID if available)	Yes	Format: alphanumeric, Example: VID123456789 AssetId needs to be unique at episode level
assetname		In-house video asset name, for troubleshooting	Yes	Format: alphanumeric Examples: TMS ID, EIDR ID or Episode title
programname		Name of the program	Yes	Format: alphanumeric, Max 25 char’s; no special characters Example: Nightly News
episodetitle		Title of the episode	Yes	Format: alphanumeric
episodelen		Total episode length	Yes	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	Format: integer – 0 (not full episode), 1 (full episode)
genre		Nielsen genre code	No	Format: alphanumeric Example: CV (comedy variety), N (news)
airdate		The date the episode was first made available on Traditional TV	No	Format: US ET:  YYYYMMDDHHMMSS Example: 19970716231256 For the US, the time should be specified as Eastern Timezone. Other countries will use a local timezone. 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	Optional	Format: alphanumeric  (max 2k) Example:https://www.myapp.com/video.html
gracenote_id		Gracenote TMS ID (If available) should be passed for all telecasted content.	Required if id3 not provided	Format: 14 character string. Normally leading with 2 alpha characters ('EP', 'MV', 'SH' or 'SP'), followed by 12 numbers. Example: SH009311820022
station_id		GraceNote station ID that identifies the station	Required if id3 not provided	Format: alphanumeric
program_name		Name of program	Required if id3 not provided	Format: alphanumeric, Max 25 characters; no special characters. Example: Nightly News See below for more specific guidance on Program Name.
network_affiliate		Network affiliation of a station	Required if id3 not provided	Format: alphanumeric Example: xyz
channel_id		ID of channel	Required if id3 not provided	Format: integer
channel_name		Name of channel	Required if id3 not provided	Format: alphanumeric
callsign		FCC assigned unique identifier for a transmitter station	Required if id3 not provided	Format: alphanumeric
dma		Designated Market Area where viewing occurred	Yes	501
ad_load_flag		linear or dynamic ad load	Yes	Format: integer; 0 = Default / Unknown 1 = linear ad load 2 = dynamic ad load
ad_support_flag		Intended method of monetizing the content	Yes	Format: integer; 0 = (no ads), 1 = (content is supported by ads) 2 = (not known) Note: set to "1" if content ad support was intended but did not occur
position		Array of contiguous content viewing. For viewing gaps < than 1 second, the gap can be smoothed over See below for additional details on position array parameters	Yes	Format: "position": [{  "referencestart":"[timestamp]",  "referenceend":"[timestamp]"  "playheadstart":"[playhead position]",  "playheadend":"[playhead position]" }]
{	referencestart	Wall clock reference start time	Yes	Format: Unix timestamp in 32-bit unsigned int in seconds Example: 1577858505
	referenceend	Wall clock reference end time	Yes	Format: Unix timestamp in 32-bit unsigned int in seconds Example: 1577858775
	playheadstart	Content position start time	Yes	Format: Unix timestamp in 32-bit unsigned int in seconds or integer indexed from 0 (typical for VOD) Example: 1577858515
}	playheadend	Content position end time	Yes	Format: Unix timestamp in 32-bit unsigned int in seconds or integer indexed from 0 (typical for VOD) Example: 1577858785
viewedads		Array of ads viewed by client. See below for additional details on position array parameters	Yes	Format: "viewedads": [ { "adpod":"0", "adposition":"0", "adid":"0", "isdarid":"0", "adstart":"utc", "adend":"utc", "advisible":"0", "adfocus":"0", "adaudio":"0" } ]
{	adpod	AdPod sequence number. Increment for each AdPod. If the same AdPod is played out twice (due to rewind), still increment the AdPod sequence to reflect the sequence the AdPods are played.	Yes	Format: Integer Example: 2
	adposition	Ad sequence number. Increment each time a new Ad is encountered. If the same Ad is played out twice (due to rewind), still increment the Ad sequence to reflect the sequence the Ads are played	Yes	Format: Integer Example: 1
	adid	The unique identifier for this Ad	No	Format: alphanumeric In-house AdId, Industry AdID, AdNetwork ID or DAR placement ID
	isdarid	Is the AdId being passed a Nielsen DAR placement ID	Required if AdID	Format: integer 0 = is NOT DAR ID; 1 = is a DAR ID
	adstart	Wall clock reference start time	Yes	Format: Unix timestamp in 32-bit unsigned int in seconds
}	adend	Wall clock reference end time	Yes	Format: Unix timestamp in 32-bit unsigned int in seconds
device_id		Mobile Ad ID (IDFA, ADID), Connected Device ID	Yes,if available	A487421B-XXXX-YYYY-8343-E3BBB66E44F2
hem_sha256		SHA-256 hashed email Note: email normalization rules applied before hashing	Strongly Preferred	55C06A30DAA5D5F382FDEB8C702EC57875CC9D91A7C78BB620053FD81DC…
luid		Living Unit ID - Experian Household ID	Yes, for CTV if available	B0EOFEDgD
uoo		User opt out flag for demographic measurement	Yes	Format: integer 0 = not opt-out 1 = opt-out
xdua		Device HTTP User Agent string	Yes	Format: alphanumeric, Example: Apple-iPhone1C2/801.293
xff		IP address	Yes	Format: xxx.xxx.xxx.xxx
psudo_id_sha256		Hashed Device User Agent string + IP address	No	421c76d77563afa1914846b010bd164f395bd34c2102e5e99e0cb9cf173…
The following 4 parameters become mandatory if Device User Agent String (UAS) is not available
device_platform		Device platform(mobile, desktop, connected device)	Required if no UAS	DSK, MBL, OTT
device_type		Device type for connected devices	Required if no UAS	AMN, APL, DVD, GGL, PSX, RKU, STB, STV, XBX
os_group		Operating system of mobile devices. All other device should be NA	Required if no UAS	IOS, DROID, NA
device_group		Type of device: phone, tablet, desktop, set top box (CTV or OTT), unknown	Required if no UAS	DSK, PHN, TAB, STV, DVD, PMP, OTHER, STB, XBX, PSX, AMN, APL, GGL, RKU, UNWN
The following 4 parameters become mandatory if IP Address is not available
robotic_flag		Flag indicating IAB bot rule if IP address present in IAB bot list	Required if no IP	Format: integer 0 = not bot, 1 = bot
zip_code		ZIP code where viewing occurred	Required if no IP	10001
country		Country ISO 3166 ALPHA-2	Required if no IP	US, CA, etc.

Note: All parameters are case sensitive.