Video lists

Breaking change after version 5.13.x

Upgrade required

This 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.
You can find here the new implementation article.

What are the video lists?

For recommendations purpose, a video definition — the VideoMetadata — can come with a companion list of others videos that DIVA Player proposes together. These companion lists are the video lists.

Defining video lists

In the videoMetadata JSON file, add the videoLists array:

Check how to add the video lists array with the VideoMetadataMap in Web.

{
...,
"videoLists": [
    {
    ... first video list
    },
    {
    ... second video list
    },
    ...
],
...
}

Add as many elements to the array as there are videolists. The following fields define a videolist (i.e., an array item):

feedUrl (default: empty): The URL of the XML file that defines the videolist. When empty, the video list is not valid.
id (default: empty): The videolist identifier within analytic events.
highlightColor (default:"#ffff00"): The color highlighting the selected video on tablets (dark theme theme).
highlightColorLight (default:"#ffff00"): The color highlighting the selected video on smartphones (dark theme theme).
message (default: empty): The text that displays as a header within the video list (which is not the title of the tab).
messageNoVideo (default: empty): The text that displays when the video list is empty (it replaces message).
menu (default: empty): The name of the videolist that displays in the tab bar.
pollingInterval (default: 0): How often to poll the videolist URL for new data (milliseconds). "0" means that polling is disabled. Values between "0" and "1000" all result into a 1-second polling interval.
redirectOnClick (default: "false"): (HTML5 only) Whether the browser opens the video in a new page.
isRecommended (default: "false"): The first element with isRecommended: "true" displays in the top of End of Play view.
behaviour (default: "switch"): How DIVA Player behaves when selecting a new video in the videolist.
Possible behaviors are:

Value	Description
switch	The new selected video plays in place of the previous one.
multiview	The new selected video plays next to currently playing video.
pipview	The new selected video plays as a picture in picture (PiP).
multistreamSwitch	The new selected video plays in place of the previous one and synchronized with it.
multistreamMultiview	The new selected video plays next to currently playing video. The two videos play synchronized.
multistreamPipview	The new selected video plays as a picture in picture (PiP). The two videos play synchronized.
modal	(Android and iOS only) The new selected video plays in a modal window over the currently playing video.

videoMetadata with Video lists example

{
    "videoLists": [
        {
            "feedUrl": "https://myfeed.xml",
            "id": "SWITCH",
            "highlightColor": "0x00ff00",
            "highlightColorLight": "0x0000ff",
            "message": "Watch today's matches",
            "messageNoVideo": "No video available at the moment",
            "menu": "diva_switch",
            "pollingInterval": 0,
            "redirectOnClick": false,
            "isRecommended": false,
            "behaviour": "switch"
        },
        {
            "feedUrl": "https://myfeed.xml",
            "behaviour": "multistreamSwitch",
            "highlightColor": "0xE65100",
            "highlightColorLight": "0xff0000",
            "menu": "diva_multistream",
            "message": "Watch match from other cameras",
            "messageNoVideo": "No video available at the moment",
            "id": "MULTISTREAM"
        },
        {
            "feedUrl": "https://myfeed.xml",
            "behaviour": "modal",
            "highlightColor": "0xffffff",
            "highlightColorLight": "0x000000",
            "menu": "modal",
            "message": "Watch related videos",
            "messageNoVideo": "No video available at the moment"
        }
    ]
}

For each videoLists element, write the videolist XML definition file — whose path you put into the feedUrl field — which has the following structure:
```
<?xml version="1.0" encoding="UTF-8" ?>
<rss version = "2.0">
    <channel>
        <item>
            ...
        </item>
        <item>
            ...
        </item>
        ...
    </channel>
</rss>
```
Each item tag identifies a video within the videolist and it's defined by:
- id: DIVA Back Office video identifier
- title: The video title that displays on the thumbnail.
- description: The video description that displays as a tooltip when hovering over the thumbnail.
- link: URL of the page that hosts the video.
- videoThumbnail url: The URL of the thumbnail image.
- live: It's the video label's background color. It can be:
  - true: For a live video and blue label's background.
  - false: For a VOD video and red label background.
- label: Label displayed over the thumbnail without vocabulary translation.
- adbadge: Audio Description badge (Accessibility). It can be:
  - true: If the badge is present.
  - false: If the badge is NOT present.
- ccbadge: Closed Caption badge (Accessibility). It can be:
  - true: If the badge is present.
  - false: If the badge is NOT present.

Video list feed example

<?xml version="1.0" encoding="UTF-8" ?>
<rss version="2.0">
    <channel>
    <title>My Sport RSS Channel</title>
    <link>https://sport1/sitemaps/news.xml</link>
    <description>Latest News</description>
    <language>en-gb</language>
    <lastBuildDate>2014-04-04T07:56:00Z</lastBuildDate>
    <copyright>Copyright (C) Sport 1</copyright>
    <item>
        <id>500080_videolist</id>
        <title>Match 1</title>
        <description>Vod hls-v3</description>
        <link>https://my-video-page.html</link>
        <guid isPermaLink="false"/>
        <pubDate>2014-06-11T22:25:51Z</pubDate>
        <videoImage url=""/>
        <videoThumbnail url=""/>
        <live>false</live>
        <label>On Demand</label>
        <category>video</category>
        <cameraType>MULTICAM</cameraType>
        <cameras>TEAMB</cameras>
        <adbadge>true</adbadge>
        <ccBadge>false</ccBadge>
    </item>
    <item>
        <id>500080_v4_videolist</id>
        <title>Match 2</title>
        <description>Vod hls-v4 without data</description>
        <link>my-video-page2.html</link>
        <guid isPermaLink="false"/>
        <pubDate>2014-06-11T22:25:51Z</pubDate>
        <videoImage url=""/>
        <videoThumbnail url="https://my-video-thumbnail.jpg"/>
        <category>Video</category>
        <cameraType>MULTISTREAM</cameraType>
        <cameras>TEAMB</cameras>
        <adbadge>true</adbadge>
        <ccBadge>true</ccBadge>
    </item>
    </channel>
</rss>

Migration procedure

Key Changes

"videolists" → Media List
the videolists node represents a collection of media lists and must be transformed into a Media List array.
"XML feed (feedUrl)" → Media List
the channel node in the XML feed represents a collection of media items and must be transformed into a Media List object.
"item" inside "XML feed" → Media List Item
each item within the XML feed represents a single video entity and must be structured as a Media List Item within the Media List.

Migration Mapping

From "videoLists" to Media List

Old Field	New Field
`videoLists`	`mediaLists`

From "videoLists" item to Media List

Old Field	New Field
`id`	`listId` (must be generated if empty)
`feedUrl`	not needed anymore
`highlightColor`	not needed anymore
`highlightColorLight`	not needed anymore
`message`	`rowTitle`
`messageNoVideo`	`noItemsMessage`
`menu`	`menuLabel`
`behaviour`	`behaviour`
`pollingInterval`	`pollingInterval` backward compatibility only*
`redirectOnClick`	`redirectOnClick` backward compatibility only*
`isRecommended`	`isRecommended` backward compatibility only*
`template`	not needed anymore

*backward compatibility only: these fields are not used in the new format but are kept for backward compatibility.

-	New Field
-	`defaultItemType` = "video"
-	`defaultItemLayout` = "vertical"
-	`showInEndOfPlay` = false*

*showInEndOfPlay: if "true" it will add the current list in the End Of Play experience.

From XML feed "items" to Media List Items

Old Field	New Field
`id`	`itemId`
`title`	`title`
`description`	`caption`
`videoThumbnail`	`imageUrl`
`link`	not needed anymore
`guid`	not needed anymore
`pubDate`	not needed anymore
`category`	not needed anymore
`videoImage`	not needed anymore
`cameraType`	not needed anymore
`cameras`	not needed anymore

-	New Field
-	`imageFormat` = "tile"
-	`itemType` = "video"
-	`itemLayout` = "vertical"

Example: Transformation Process

Input - Original Video Metadata JSON (Old Format)

{
  "videoLists": [
    {
      "feedUrl": "https://example.com/feed.xml",
      "highlightColor": "#FF0000",
      "highlightColorLight": "#FF0000",
      "message": "Recommended Videos",
      "messageNoVideo": "No videos available",
      "menu": "Recommended",
      "behaviour": "multiview",
      "pollingInterval": 30000,
      "redirectOnClick": true,
      "isRecommended": true,
      "template": "default"
    }
  ]
}

Input - Original Video list RSS Feed XML (Old Format)

<rss version="2.0">
    <script src="chrome-extension://mfidniedemcgceagapgdekdbmanojomk/js/elephant.js"/>
    <channel>
        <title>Star Cricket RSS Channel</title>
        <link>https://www.starsports.com/sitemaps/news.xml</link>
        <description>Latest News</description>
        <language>en-gb</language>
        <lastBuildDate>2014-04-04T07:56:00Z</lastBuildDate>
        <copyright>Copyright (C) Star Cricket</copyright>
        <item>
            <id>live_videolist</id>
            <title>4. Bra Vs Ger - Live</title>
            <description>Live hls-v3 with ProgrmamDateTime shifted 20 min after</description>
            <link>custom-link</link>
            <guid isPermaLink="false"/>
            <pubDate>2014-06-11T22:25:51Z</pubDate>
            <videoImage url=""/>
            <videoThumbnail url="my-image.png"/>
            <live>true</live>
            <label>live</label>
            <category>video</category>
            <cameraType>MULTICAM</cameraType>
            <cameras>TEAMB</cameras>
        </item>
    </channel>
</rss>

Output - Converted Media List Format (New Format)

{
  "mediaLists": [
    {
      "listId": "mediaListId",
      "rowTitle": "Recommended Videos",
      "noItemsMessage": "No videos available",
      "menuLabel": "Recommended",
      "behaviour": "multiview",
      "pollingInterval": 30000,
      "redirectOnClick": true,
      "isRecommended": true,
      "defaultItemType": "video",
      "defaultItemLayout": "vertical",
      "defaulImageFormat": "tile",
      "items": [
        {
          "itemId": "live_videolist",
          "title": "4. Bra Vs Ger - Live",
          "caption": "Live hls-v3 with Program DateTime shifted 20 min after",
          "imageUrl": "my-image.png",
          "itemType": "video",
          "itemLayout": "vertical"
        }
      ]
    }
  ]
}

What are the video lists?​

Defining video lists​

Migration procedure​

Key Changes​

Migration Mapping​

Example: Transformation Process​