Sweden SDK Metadata: Difference between revisions

From Engineering Client Portal

No edit summary
(→‎Ad Metadata: isprogrammatic is optional - per new change request from MMS/Mats)
 
(104 intermediate revisions by 4 users not shown)
Line 3: Line 3:


= Digital Metadata =
= Digital Metadata =
Digital Metadata can passed through key-values using the Nielsen reserved keys. The keys and values are listed by product below.  
Digital Metadata can pass through key values using the Nielsen reserved keys. The keys and values are listed by the product below.  
<br>
'''Section 1''' focuses on the content metadata
<br>
'''Section 2''' focuses on the Ad metadata.
<br><br>


== Digital Content Ratings (DCR) Metadata ==
'''Note:''' All metadata values should be passed as UTF-8 strings.<br>
=== Video Metadata ===
 
{{DCR Content Metadata}}
== Content Metadata==
<!--
==== Example Video Metadata Object ====
<syntaxhighlight lang="javascript">
var contentMetadataObject =
{ 
  type:          'content',
  assetid:        'VID-123456',
  program:        'The Big Bang Theory',
  title:          'The Pants Alternative S03E18',  //no abbreviations or shorthand
  length:         '1320',  //lengths in seconds
  airdate:        '2021-03-21T12:00:00Z',
  isfullepisode:  'y',
  adloadtype:    '2',
  segB:          'custom segment B', // optional
  segC:          'custom segment C', // optional
  crossId1:      'Standard Episode ID', // optional
  crossId2:      'Content Originator' //optional
};
</syntaxhighlight>


=== Ad Metadata ===
The Ad Metadata (if applicable) should be passed for each individual ad.
{| class="wikitable"
{| class="wikitable"
|-
|-
! Keys !! Description !! Values !! Required
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
|-
| type || type of Ad || <code>'preroll'</code>,  <code>'midroll'</code>,  <code>'postroll'</code> <br> <code>'ad'</code>  - If specific type can not be identified.|| ✓
| type ||  || type of asset || "content" || ✓
|-
|-
| assetid || unique ID assigned to Ad || custom <br>(no [[Special Characters]]) || ✓
| userid || || the user login ID. Used by MMS reach model. ''The uploaded value needs to be hashed with SHA512''. This is the user login ID on player. We prefer a numeric value. (please '''do not''' use user email address)|| "fbd1a7a7d672a5fcf5cf5c55d8d9d0abbe3a4e0fa..." || required if login feature
|}


==== Example Ad Object ====
<syntaxhighlight lang="javascript">
var adMetadataObject =
{ 
  type:    'preroll',
  assetid: 'AD-1'
};
</syntaxhighlight>
=== Static Metadata ===
{| class="wikitable"
|-
|-
! Key !! Description !! Data Type !! Value !! Required?
| assetid || Content ID, mms_tid || unique ID assigned to an asset within the same media house. (max: 20 characters).<br><br> In addition to this metadata for content needs to be reported to MMS via TitleService. Contact online@mms.se for more information. ||
<small>For VoD use internal format. [https://engineeringportal.nielsen.com/docs/Special_Characters No special characters]</small><br>
<small>For content on simulcast channels, this has a standard format: simulcast_channelnumber ('''Example''' for Channel TV4, the expected value is: simulcast_29).<br></small>
<small>A complete list of channel reference libraries with channel numbers is on the  [https://mms.se/for-vara-kunder/teknisk-dokumentation-tv/referensbandade-kanaler/ MMS homepage] tab "referensbandade kanaler".</small>
|| ✓ <br>
|-
| length || Clip Length, ns_st_cl || length of content in seconds || Length of content in seconds.
* <small>for VoD, video length</small>
* <small>for event-Live stream, the planned length.</small>
* <small>for simulcast and 24/7 live stream, 86400</small>
|| ✓
|-
| clientpassparam || MMS Values, mms_values || pass-through parameters || For clients that provide DAI (dynamic ad insertion) service, this has a standard format: origcode=channelnumber.
<small>'''Example:''' origcode=29
See the complete list of channel reference library with the channel number on [https://mms.se/for-vara-kunder/teknisk-dokumentation-tv/referensbandade-kanaler/ MMS homepage] tab "referensbandade kanaler".</small> <br> <small>Please use string, JSON format is not accepted. </small><br>
<small>Length limit: 250 characters. A longer string may be truncated due to URL length limitation.</small>
|| required for clients that have DAI service (Telia, Telenor, Allente, Comhem, Boxer, Sappa, Discovery, Cmore)
|-
| program || Program Name, ns_st_pr || program name || '''custom''' '''example:''' leif-och-billy <br>
<small>Leave blank for simulcast. <br>'''Please restrain from using special characters like "/" or ";"'''</small>
|| ✓
|-
|-
| type || asset type || fixed || <code>'static'</code> || Yes
| title || Episode Name, ns_st_ep || episode name || '''custom''' '''example:''' en-ny-tjej-i-byn <br>
<small>Leave blank for simulcast. <br>'''Please restrain from using special characters like "/" or ";"'''</small>
|| ✓
|-
|-
| assetid || Unique ID for each article || dynamic || custom <br>(no [[Special Characters]]) || Yes
| playlisttitle || Title Playlist, ns_st_pl || playlist reference as a string || string value with playlist name for '''example:''' barn ||  
|-
|-
| section || section of each site (e.g. section value should be first level in page URL: website.com/section). Limit to 25 unique values || dynamic || custom <br>(no [[Special Characters]]) || Yes
| ispremiumcontent || MMS Premium, mms_premium || identify premium level via yes or no || "yes" or "no"  || ✓
|-
|-
| segA || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
| isautoplay || Auto Start, mms_auto || identify if autoplay is enabled on the video || "yes" or "no"  || ✓
|-
|-
| segB || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
| plugv || Player Version, ns_st_mv || player version. increment by 1 for each new version. || alphanumeric '''example:''' 1.0.1 || ✓
|-
|-
| segC || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
| playerv || Mediaplayer, ns_st_mp || player identifier || alphanumeric '''example:''' HTML5, JW Player, Sonic  || ✓
|}
|}


The values passed through the Nielsen keys will determine the breakouts that are seen in reporting. The custom segments (A, B & C) will roll into the sub-brand. To not use custom segments A, B and C, do not pass any value in these keys.


==== Example Static Metadata Object ====
 
 
 
 
Example of metadata object for content:
 
<syntaxhighlight lang="javascript">
<syntaxhighlight lang="javascript">
var contentMetadataObject =
var contentMetadataObject = {
{
   type: "content",
   type: 'static',  
  userid: "fbd1a7a7d672a5fcf5cf5c55d8d9d0abbe3a4e0fa…",  
   assetid: 'HHF887465-9486', // *DYNAMIC METADATA*: unique ID for each article **REQUIRED**
   assetid: "simulcast_29",
   section: 'SPORTS', // *DYNAMIC METADATA*: section of site **REQUIRED**
  length: "3359", //seconds
   segA: 'HD Videos', // *DYNAMIC METADATA*: custom segment
  clientpassparam: "origcode=29",
   segB: '', // *DYNAMIC METADATA*: custom segment
   program: "leif-och-billy",
   segC: ''  // *DYNAMIC METADATA*: custom segment
  title: "en-ny-tjej-i-byn",
   playlisttitle: "barn",
  ispremiumcontent: "yes",
   isautoplay: "yes",
  plugv: "1.0.1",
   playerv: "Sonic"
};
};
</syntaxhighlight>
</syntaxhighlight>


== Digital TV Ratings (DTVR) Metadata ==
== Ad Metadata==
=== Content Metadata ===
 
{| class="wikitable"
{| class="wikitable"
|-
|-
! Key !! Description !! Values !! Required
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required  
|-
|-
| type || type of asset || "content" || ✓
| type || Ad Type, ns_st_ad || type of ad || "preroll", "midroll", "postroll", "ad" if specific ad type cannot be identified. || ✓
|-
|-
| adModel || linear vs dynamic ad model || * 1) - Linear – matches TV ad load * 2) Dynamic – Dynamic Ad Insertion (DAI)    || ✓
| assetid || Film Code, mms_customadid || custom Ad ID || Film code/Copy code.
|-
<small>'''Custom examples''': S1MYME202B, 51TRER1001, H1KYLE3032, E1UMBR1001</small>
|}
====Example Content Object====
<syntaxhighlight lang="javascript"> var contentMetadataObject =
{ 
  type: 'content',
  adModel: '1'
};
</syntaxhighlight>
==== Custom Variables Extension ====
If you are looking for additional reporting options, reach out to us. We have a [[Custom Variables Extension]] and can work with you to obtain your desired reporting.
 


<small>In case of no Film Code is available, use the string "empty".</small>


 
<small>For programmatic ads that you are sending "programmatic" as Film Code today, use "programmatic_{current UTC time in epoch form}".</small>
{| class="wikitable"
|| ✓
|-
! Key
! Description
! style="width: 14%;" | Values
! style="width: 12%;" | Required for Audio/Video?
! style="width: 12%;" | Required for Static (page)?
! Reported for
|-
| clientid || Brand value is automatically populated through the App ID provided. The value passed here will override the default value. (e.g. Multiple brands in App) || custom || Optional || Optional || Audio / Video and Static Measurement
|-
| subbrand || VCID value is automatically populated through the App ID provided. This value passed here will override the default value. (e.g. Multiple Sub-brands in App) || custom || Optional || Optional || Audio / Video and Static Measurement
|-
| type ||
Type of measurement:
*audio / video – "content"
*page – "static"
*ad – "preroll", "midroll" or "postroll"
|| "content", "static" || Mandatory || Mandatory ||
|-
| assetid || ID assigned to content. '''Must be unique and consistent''' across all content at the episode level, as well as across platforms (e.g. iOS and Android use the same ID). || custom<br>(no [[Special Characters]]) || Mandatory || Not Required ||
|-
| section || Section of site || custom || Not Required || Mandatory ||
|-
| isfullepisode || Full episode flag ||
*"y" or "lf" - full episode
*"n" or "sf" - short form
|| Mandatory || Not Required ||
|-
| program || Program name || custom || Mandatory || Not Required || Audio / Video Measurement
|-
| title || Episode title || custom || Mandatory || Not Required || Audio / Video Measurement
|-
| length || Length of content in seconds for VOD. 0 may be used for Live content if the exact content length is not known.  || custom || Mandatory || Not Required ||
|-
| segA || Segment A (this is not available for audio / video Measurement reporting as the episode title is reported) || custom || Not Required || Not Required || Static Measurement
|-
| segB || Segment B || custom || Not Required || Not Required || Audio / Video and Static Measurement
|-
| segC || Segment C || custom || Not Required || Not Required || Audio / Video and Static Measurement
|-
| crossId1 || Standard episode ID. Gracenote/TMS ID should be used when available. Must be unique per episode. || custom || Optional || Not Required ||
|-
| crossId2 || Content originator (required only for distributors) || custom || Optional || Not Required ||
|-
| airdate || Original (local) air date and time (Eastern Time for US) || YYYYMMDD HH24:MI:SS || Mandatory || Not Required ||
|-
|-
| pipmode ||
| length || Clip Length, ns_st_cl || length of ad in seconds || Length of ad in seconds. || ✓
Current state of picture-in-picture (PIP) mode on device.
*"true" if audio / video measurement is displayed in PIP mode
*"false" if audio / video measurement is displayed in regular mode
|| "true", "false" || Optional || Not Required || Audio / Video Measurement
|-
|-
| adloadtype ||
| isprogrammatic || Programmatic, mms_programmatic || identify if the ad is bought prommatic. || "yes" or "no" ||  
Type of ad load:
#Linear - matches TV ad load
#Dynamic - Dynamic Ad Insertion (DAI)
|| "1" - Linear
"2" - Dynamic
|| Mandatory for DCR || Not Required || DCR
|-
|-
| adModel ||
| adplatformorigin || MMS Origin, mms_origin || identify where an ad is originated. It is used when isprogrammatic=yes or isthirdpartyad=yes. || custom '''examples:''' Smartclip, YuMe
Type of ad model:
||  
#Linear - matches TV ad load
#Dynamic - Dynamic Ad Insertion (DAI)
|| "1" - Linear
"2" - Dynamic
|| Mandatory for DTVR || Not Required || DTVR
|-
|-
| progen || Genre (required only for non-TV originated content). See [[DCR OTT Genre List]] for acceptable values. || e.g. DD for Daytime Drama || Required for non-TV content || Not Required
| adidx || Position in Break, ns_st_an || placement in ad break. It is passed by ad servers. || Custom with the following format:
|}
<small>{ad placement}/{total number of ads in an ad break}</small><br>
 
'''clientid & subbrand (vcid)'''
By default, clientid and subbrand are setup in Nielsen backend configuration to capture brand and sub-brand information. The fields get populated from backend for a registered client appid. But if an app contains multiple brands and sub-brands and client is willing to give credit to another brand or sub-brand then :
*Client app developer can override the clientid and subbrand (brand and sub-brand info.) in [[loadMetadata]] call to get a proper measurement for a desired brand and sub-brand.
**If no clientid and subbrand are specified in CMS of a content and an ad, default values reported in the Configuration will be reported.
**If clientid and subbrand are specified in CMS of the content or ad, the most recent clientid and subbrand will be reported in subsequent pings. To report with a different clientid and subbrand, include the new values for the keys in their subsequent [[loadMetadata]] call.
'''Picture-in-picture (PIP) mode'''
Once the app detects PIP mode, call [[loadMetadata]] with the same set of assetids, values and with one additional parameter "pipmode": "true". Once PIP mode is disabled in the device, call [[loadMetadata]] again with "pipmode":"false".
 
==== Custom Variables Extension ====
Contact Nielsen Technical Account Manager (TAM) to configure any custom variables, as needed for implementing the application.


See [[Custom Variables Extension]] for more information.
<small>'''Example:''' 2/5, the second ad in an ad break with 5 ads.</small>
 
|| ✓
==== Advertisement Metadata ====
{| class="wikitable"
|-
! Key !! Description !! Values !! Required for Audio / Video? !! Required for Static (page)
|-
| type || Type of ad || "preroll"
"midroll"
"postroll"
|| Mandatory || Not Required
|-
| assetid || An ID assigned to the advertisement. Can be an internal ID, an ID provided by the ad server, or a randomly generated ID. Must be unique across all ads || custom || Mandatory || Not Required
|-
|-
| title || Title of the advertisement || "MyAdName" || Mandatory || Not Required
| ad_campaign || MMS Ad campaign ID, campaign_id || campaign ID of an Ad || custom string value containing in general letters and digits  ||  
|}
|}


=== Passing Metadata ===
Example of metadata object for Ad:
The required metadata can be passed as key values through the loadMetadata method. The sample code below shows a metadata objects for various assets.
'''Audio / Video Measurement Asset'''
Type should be "content"
<syntaxhighlight lang="json">    {
      "type": "content",
      "assetName": "myassetName",
      "length": "300.0",
      "title": "myTitle",
      "program": "myProgram",
      "censuscategory": "myCensusCategory",
      "assetid": "myAssetId",
      "channelName": "myChannel",
      "adloadtype": "2",
      "segB": "segmentB",
      "segC": "segmentC",
      "isfullepisode":"y",
      "crossId1": "Reference11",
      "crossId2": "Reference22",
      "airdate": "20161013 20:00:00"
    }</syntaxhighlight>


'''Static (Page) Measurement Asset'''
<syntaxhighlight lang="javascript">
Type should be "static"
var prerollMetadataObject = {
<syntaxhighlight lang="json">   {
  type: "preroll",
      "type": "static",
  assetid: "E1UMBR1001",  
      "assetid": "static123",
  length: "30", //seconds
      "section": "siteSection",
  isprogrammatic: "yes",
      "segA": "segmentA",
  adplatformorigin: "YuMe",
      "segB": "segmentB",
  adidx: "1/5"
      "segC": "segmentC"
};
    }</syntaxhighlight>
</syntaxhighlight>
 
'''For any of the ad types'''
<syntaxhighlight lang="json">    {
        "type": "midroll",
        "length": "30.0",
        "assetid": "myMidrollAssetId",
        "adloadtype": "2",
        "tv": "true",
        "dataSrc": "cms"
    }</syntaxhighlight>
<blockquote>'''Note''': In case the individual ad details are not available, send ad pod (presence) details through the <code>loadMetadata</code> and playhead position through <code>setPlayheadPosition</code>.</blockquote>
 
'''loadMetadata'''
The object can then be passed when calling [[loadMetadata]].
<syntaxhighlight lang="java">    loadMetadata(jsonMetadataObject);</syntaxhighlight>
 
-->

Latest revision as of 08:47, 2 July 2024

Engineering Portal / Digital / International DCR / Sweden SDK Metadata

Digital Metadata

Digital Metadata can pass through key values using the Nielsen reserved keys. The keys and values are listed by the product below.
Section 1 focuses on the content metadata
Section 2 focuses on the Ad metadata.

Note: All metadata values should be passed as UTF-8 strings.

Content Metadata

Nielsen Key MMS Attribute Name, MMS Field Name Description Values Required
type type of asset "content" ✓
userid the user login ID. Used by MMS reach model. The uploaded value needs to be hashed with SHA512. This is the user login ID on player. We prefer a numeric value. (please do not use user email address) "fbd1a7a7d672a5fcf5cf5c55d8d9d0abbe3a4e0fa..." required if login feature
assetid Content ID, mms_tid unique ID assigned to an asset within the same media house. (max: 20 characters).

In addition to this metadata for content needs to be reported to MMS via TitleService. Contact online@mms.se for more information.

For VoD use internal format. No special characters
For content on simulcast channels, this has a standard format: simulcast_channelnumber (Example for Channel TV4, the expected value is: simulcast_29).
 A complete list of channel reference libraries with channel numbers is on the MMS homepage tab "referensbandade kanaler".

✓
length Clip Length, ns_st_cl length of content in seconds Length of content in seconds.
  • for VoD, video length
  • for event-Live stream, the planned length.
  • for simulcast and 24/7 live stream, 86400
 ✓
clientpassparam MMS Values, mms_values pass-through parameters For clients that provide DAI (dynamic ad insertion) service, this has a standard format: origcode=channelnumber.

Example: origcode=29 See the complete list of channel reference library with the channel number on MMS homepage tab "referensbandade kanaler".
Please use string, JSON format is not accepted.
Length limit: 250 characters. A longer string may be truncated due to URL length limitation.

required for clients that have DAI service (Telia, Telenor, Allente, Comhem, Boxer, Sappa, Discovery, Cmore)
program Program Name, ns_st_pr program name custom example: leif-och-billy

Leave blank for simulcast.
Please restrain from using special characters like "/" or ";"

✓
title Episode Name, ns_st_ep episode name custom example: en-ny-tjej-i-byn

Leave blank for simulcast.
Please restrain from using special characters like "/" or ";"

✓
playlisttitle Title Playlist, ns_st_pl playlist reference as a string string value with playlist name for example: barn
ispremiumcontent MMS Premium, mms_premium identify premium level via yes or no "yes" or "no" ✓
isautoplay Auto Start, mms_auto identify if autoplay is enabled on the video "yes" or "no" ✓
plugv Player Version, ns_st_mv player version. increment by 1 for each new version. alphanumeric example: 1.0.1 ✓
playerv Mediaplayer, ns_st_mp player identifier alphanumeric example: HTML5, JW Player, Sonic ✓




Example of metadata object for content: 

var contentMetadataObject = {
  type: "content", 
  userid: "fbd1a7a7d672a5fcf5cf5c55d8d9d0abbe3a4e0fa…", 
  assetid: "simulcast_29",
  length: "3359", //seconds
  clientpassparam: "origcode=29",
  program: "leif-och-billy",
  title: "en-ny-tjej-i-byn",
  playlisttitle: "barn",
  ispremiumcontent: "yes",
  isautoplay: "yes",
  plugv: "1.0.1",
  playerv: "Sonic"
};

Ad Metadata

Nielsen Key MMS Attribute Name, MMS Field Name Description Values Required
type Ad Type, ns_st_ad type of ad "preroll", "midroll", "postroll", "ad" if specific ad type cannot be identified. ✓
assetid Film Code, mms_customadid custom Ad ID Film code/Copy code.

Custom examples: S1MYME202B, 51TRER1001, H1KYLE3032, E1UMBR1001

In case of no Film Code is available, use the string "empty".

For programmatic ads that you are sending "programmatic" as Film Code today, use "programmatic_{current UTC time in epoch form}".

✓
length Clip Length, ns_st_cl length of ad in seconds Length of ad in seconds. ✓
isprogrammatic Programmatic, mms_programmatic identify if the ad is bought prommatic. "yes" or "no"
adplatformorigin MMS Origin, mms_origin identify where an ad is originated. It is used when isprogrammatic=yes or isthirdpartyad=yes. custom examples: Smartclip, YuMe
adidx Position in Break, ns_st_an placement in ad break. It is passed by ad servers. Custom with the following format:

{ad placement}/{total number of ads in an ad break}

Example: 2/5, the second ad in an ad break with 5 ads.

✓
ad_campaign MMS Ad campaign ID, campaign_id campaign ID of an Ad custom string value containing in general letters and digits

Example of metadata object for Ad: 

var prerollMetadataObject = {
  type: "preroll",
  assetid: "E1UMBR1001", 
  length: "30", //seconds
  isprogrammatic: "yes",
  adplatformorigin: "YuMe",
  adidx: "1/5"
};
Retrieved from "https://engineeringportal.nielsen.com/w/index.php?title=Sweden_SDK_Metadata&oldid=6851"