Media lists

Breaking change after version 5.13.x

Upgrade required

The previous implementation is deprecated and will be maintained only until version 5.13.x. After that, it will no longer be supported. Upgrade now to ensure continued compatibility.

What is a media list?

The Media List is a collection of media items (which can be either videos or audio files) typically displayed in a carousel format, arranged in a single row. This layout allows for a compact and interactive presentation, enabling users to browse through the items horizontally. Each media item within the list adheres to the Media List Item structure, ensuring consistency and modularity.

How to define a media list

1. In the videoMetadata JSON file, add the mediaLists array:

   {
   ...,
   "mediaLists": [
       {
       ... first media list
       },
       {
       ... second media list
       },
       ...
   ],
   ...
   }

2. Add as many elements to the array as there are media lists. The following fields define a media list (i.e., an array item):

   {
       "listId":"1234567",
       "rowTitle":"diva_list_title",
       "defaultImageFormat":"squared",//optional. default 'tile'
       "defaultItemType" : "audio",
       "defaultItemLayout" : "vertical",//optional. default 'vertical'
       "items": [
         //Media list items list
       ]
   },

• listId: The media list identifier within analytic events.
• rowTitle: The title of the media list.
• defaultImageFormat (default: tile): The format of the image inside the media list. It can be:
  • square: The image is square.
  • tile: The image is tile (landscape).
• defaultItemType (default: video): The default type of the item inside the media list. It can be:
  • video: The media list contains video streams.
  • upnext: The media list contains video streams of type "upnext" (they have a specific behaviour and their own analytics).
  • related: The media list contains video streams of type "related" (they have a specific behaviour and their own analytics).
  • audio: The media list contains music and podcasts.
  • podcast: The media list contains podcasts.
  • music: The media list contains music.
• defaultItemLayout (default: empty): The default layout of the item inside the media list. It can be:
  • horizontal: The media list item is displayed horizontally by default.
  • vertical: The media list item is displayed vertically by default.
• items: list of media list item.

NOTE

• The defaultImageFormat, defaultItemType and defaultItemLayout parameters are used to define the imageFormat, itemTypeand theitemLayout` for all elements within a list. This operation applies universally to all items, either populating the itemType field if it is empty or overwriting it if a value is already present.
  

Media list item

The Media List Item is the fundamental component of a list. Each Media List Item typically includes a small set of information, such as:

• Image: A visual representation (e.g., thumbnail or icon).
• Title: The main text or heading associated with the item.
• Description: A brief explanation or additional context for the item.
• Type: A label or category that specifies the item's nature.

All individual components within a list, regardless of their source or the behaviour they will exhibit, are classified as Media List Items. This ensures a consistent structure and styling across various list elements, simplifying implementation and customization.

Each item has the following fields:

• itemId: The item identifier within analytic events. It will be used to play the item as videoId.
• title: The title of the item.
• caption: (default: null) The subtext or description associated with the item. Can be null
• imageUrl: The URL of the image associated with the item. In case of null or empty, the default image is displayed.
• imageFormat: (default: tile) The format of the image. It can be:
  • square: The image is square.
  • tile: The image is tile (landscape).
• itemType: The type of the item. It can be:
  • audio: The item is an audio. (default value)
  • podcast: The item is a podcast episode.
  • music: The item is a music song.
• itemLayout: The layout of the item. It can be:
  • horizontal: The item is displayed horizontally. (default for responsive portrait)
  • vertical: The item is displayed vertically. (default for desktop, TVs and tablet landscape)
• ccBadge: (default: false) If true, a closed caption badge is displayed.
• adBadge: (default: false) If true, an audio description badge is displayed.
• ccBadge: (default: false) If true, a closed caption badge is displayed.
• explicitBadge: (default: false) If true, an explicit badge is displayed.

{
    "itemId": "1234567",
    "title": "diva_list_item_title",
    "caption": "diva_list_item_caption",
    "imageUrl": "diva_list_item_image_url",
    "itemType": "audio",
    "itemLayout": "horizontal",
    "ccBadge": false,
    "adBadge": false,
    "explicitBadge": false
}

Item layout

• vertical (default for desktop, TVs and tablet landscape) from top to bottom: image, title, caption

  

• horizontal (default for responsive portrait) from left to right: image, title, caption

  

Migration procedure

Please refer to the platform features pages for instructions on migrating to the new media lists data format.