Skip to main content

Recommendations / Related

What you learn​

You're instantiating DIVA Player in your web front-end and relying on DIVA Back Office as the video streaming source.

The goal of this article is to build the simplest front-end to stream a video from the DIVA Back Office with, at the end, the activation of Recommendations in combination with end of play.

Before starting​

Instantiation​

Write the Basic instantiation code. There's no additional code to write, unless you need to overwrite the autoplay behavior that the VideoMetadata contains.

There are 2 ways to populate the Recommended content: Related and VideoLists(legacy).

Write the App() function to read the VideoMetadataMap as in the following example, and set the related property:

Set the related property:

  • null default value if not set and recommendations not shown
  • This is the only mandatory value to set to show recommendations(At least one related item with the itemId):
"related":{
  "items":[
     {
        "itemId":"<videoId>"
     }
  ]
}
  • These are the complete fields that can be set:
"related":{
  "items":[
     {
        "itemId":"<videoId>",
        "title":"<title>",
        "caption":"<caption>",
        "imgUrl":"<imgUrl>",
        "ccBadge":true,
        "adBadge":true
     },
     {
        "itemId":"<videoId>",
        "title":"<title>",
        "caption":"<caption>",
        "imgUrl":"<imgUrl>",
        "ccBadge":false,
        "adBadge":false
     }
  ]
}

Recommendations by Video lists​

See videoLists.

Recommendations Autoplay configuration​

Set the countdownToAutoplay property:

  • 10000 default value if not set
  • 0 to set no autoplay
  • A positive integer that specifies the number of milliseconds before Related first item start automatically(Without user interaction). (eg: with 10000 the UpNext video starts automatically after 10 seconds).
"behaviour": {
    "endOfPlay": {
        "countdownToAutoplay":10000 //milliseconds, default 10000, 0 or negative means disabled
    },
}

Set the timeToDisableAutoplay property in the settings file:

  • 5400000 default value if not set

  • A positive integer that specifies the number of milliseconds of user interaction before Autoplay to be disabled. (eg: with 5400000 the Chain Autoplay is disabled after 90 minutes of user not interactions.

"general": {
    "timeToDisableAutoplay": 5400000, //milliseconds, default 5400000
},

Customize the click behaviour​

The default behaviour once we click on the item is switch (play the clicked video).  If the integrators need to override the click behaviour they can set the callback on Diva config by adding:

val divaListener: DivaListener = object : DivaListener {

    override fun onRelatedClick(itemId: String): Boolean {
        /*
        * This method is called when a related item is clicked.
        * @param itemId The id of the related item that was clicked.
        * @return True if the click event was handled, false otherwise.
        * The implementation is optional.
         */
        return true
    }
}
  • rowTitleKey Is the translation key which is used for title of Related row, the key should be set in the App dictionary file.
  • timeToDisableAutoplay Can not be overwriting on App side, it can be set only in the settings file(If is not set default value is applied).
  • countdownToAutoplay Can be overwriting on App side in the following way:
  • related Can be overwriting on App side in the following way:
private fun videoMetadataMapper(videoMetadata: VideoMetadata): VideoMetadata {
    val endOfPlay = videoMetadata.behaviour?.endOfPlay?.copy(countdownToAutoplay = BigDecimal(20000))
    val relatedItems = Related(rowTitle = rowTitleKey, imageFormat = Related.ImageFormat.tile,
                        items = listOf(RelatedItem(itemId = videoId, title = title, caption = caption, imgUrl = imgUrl),
                                     RelatedItem(itemId = videoId, title = title, caption = caption, imgUrl = imgUrl)))
    return videoMetadata.copy(
        behaviour = videoMetadata.behaviour?.copy(endOfPlay = endOfPlay)
        related = relatedItems
    )
}
  • countdownToAutoplay Can be overwriting on App side in the following way:
  • upNext Can be overwriting on App side in the following way:
private fun videoMetadataMapper(videoMetadata: VideoMetadata): VideoMetadata {
    val endOfPlay = videoMetadata.behaviour?.endOfPlay?.copy(countdownToAutoplay = BigDecimal(20000))
    val upNext = UpNext(itemId = videoId, title = title, caption = caption, imgUrl = imgUrl)

    return videoMetadata.copy(
        behaviour = videoMetadata.behaviour?.copy(endOfPlay = endOfPlay)
        upNext = upNext
    )
}

Behaviour​

  • Recommendations list will be shown only when the Squeeze Back feature is triggered or at the end of playback (if Squeeze Back is not enabled), when no Up Next is present .
  • Recommendations list will be shown on the bottom, including video information on each video and countdown to autoplay on first related item.
  • When casting to Chromecast, Recommendations is disabled on the receiver device, meaning the Recommendations prompt and countdown will not be shown on the receiver.

Countdown Activation​

  • The countdown timer will display the remaining seconds as per the design specifications. If no countdown value is set, the timer will not appear.
  • When the countdown finishes, the first video in Recommendations list will automatically start unless the user interacts with the Endboard.

Countdown Cancellation​

  • If the user interacts with the Endboard, the countdown timer is canceled, and the automatic transition to the first video in Recommendations list is halted. The specific interactions that cancel the countdown vary by platform:
    • AndroidTV: Any focus change on the interface.
    • Mobile: Any interaction outside the "Next Episode" tile will stop the countdown.

Countdown to Up-Next​

  • When the countdown finishes without user interaction, the first video in Recommendations list will automatically load using the supplied video ID and begin playback.
  • When the user selects some item from the Recommendations list by clicking or tapping on it, the video will launch immediately, overriding the countdown.

Autoplay Limitations​

  • To prevent continuous autoplay during inactive sessions, a Recommendations timeout will be applied:
    • A session-based timer will track user inactivity. If the user does not interact with the device for a specified period, autoplay will be paused.
    • Any user interaction with the device (e.g., pressing buttons, moving the cursor, or tapping on the screen) will reset the inactivity timer, allowing autoplay to continue.

Dictionary​

Ensure the dictionary file contains the relevant keys.

Analytics events​

Find here the available analytics events for the Recommendations / Related.