Age rating and content overlay

What you learn

You are instantiating DIVA Player in your Roku application and relying on DIVA Back Office as the video streaming source.

The goal of this article is to build the simplest Roku app to stream a video from the DIVA Back Office with Age Rating and Content Overlay.

Before starting

• Ensure the DIVA Back Office instance you rely on is up and running.

• Ask your video engineers team the <video id> and the related <settings URL>.

• Ensure the Settings file contains the contentRatingSetting and colours section:

  "contentRatingSetting": {
      "startTime": 2000 ' default 2000
      "durationTime": 5000, ' default 5000
  }
  "colours": {
      "contentRatingBar": "#F7BB55" 'default "#F7BB55"
  }

  Property	Description	Type	default
  startTime	delay in milliseconds for displaying the Age Rating and Content Overlay after hiding the Controls.	integer	5000
  durationTime	time in milliseconds for which it will be displayed the Age Rating and Content Overlay.	integer	2000
  contentRatingBar	line color of the Rating bar.	string	#F7BB55

• Ensure the VideoMetadata file contains the contentRating properties:

  "contentRating": {
      "icon": "https://url.com/icon.png", '120x80, 'Classification.images.icon' on Axis
      "classification": "Adults Only",  ' 'Classification.TextAdvisory' on Axis
      "contentDescription": "This program contains scenes of violence, fear, and strong language"
  }

  Property	Description	Type	default
  icon	url to icon for the Age Rating and Content Overlay. Requirements for the icon size 120x80. If the icon is a different size, then it will fit into that size (120x80)	string	""
  classification	text description of the Age Rating and Content Overlay. First line. No text length restrictions.	string	""
  contentDescription	text description of the Age Rating and Content Overlay. Second line. No text length restrictions.	string	""

  Note: The Age Rating and Content Overlay will be displayed if at least one of the above options is specified.

Instantiation

If the Age Rating and Content Overlay configuration is available in the VideoMetadata and Settings files, there's no code to add to the Basic instantiation code.

Otherwise, if you need to modify or add from scratch the Age Rating and Content Overlay configuration via code, the following steps show how:

1. Add the contentRating field to VideoMetadata response:

sub setupBOAdapterObservers()
    ...
    m.boAdapterNode.observeField("videoDataNode", "onBOAdapterVideoDataNodeHandler")
    ...
end sub

sub onBOAdapterVideoDataNodeHandler(evt as dynamic)
    data = evt.getData()

    addAgeRatingMetaDataTestData(data)

    ' Setup Diva Player Metadata
    m.dpUtilsNode.callFunc("setMetaData", data)
end sub

sub addAgeRatingMetaDataTestData(data as dynamic)
    data.addFields({
        "contentRating": {
            "icon": "https://url.com/icon.png", '120x80
            "classification": "Adults Only",  ' 'advisoryText' on Axis, default null
            "contentDescription": "This program contains scenes of violence, fear, and strong language", 'default null
        }
    })
end sub

2. Add the contentRatingSetting and color fields to Settings response:

sub setupBOAdapterObservers()
    ...
    m.boAdapterNode.observeField("settingsNode", "onSettingsHandler")
    ...
end sub

sub onSettingsHandler(evt as dynamic)
    data = evt.getData()

    addAgeRatingSettingsTestData(data)

    ' Setup Diva Player Settings
    m.dpUtilsNode.callFunc("setSettings", data)
end sub

sub addAgeRatingSettingsTestData(data as dynamic)
    data.addFields({
        "contentRatingSetting": {
            "durationTime": 5000, ' default 5000
            "startTime": 2000 ' default 2000
        }
        "colours": {
            "contentRatingBar": "#F7BB55" 'default "#F7BB55"
        }
    })
end sub

Behaviour

The Age Rating and Content Overlay is shown at the start of video playback, after the player controls are hidden. It will only display once at the beginning unless its appearance is interrupted (for example, by pausing the video or showing controls). In such cases, the overlay will be shown again when playback resumes and the controls are hidden.

When the overlay appears

The overlay is automatically displayed in the following scenarios:

• After the controls are hidden at the start of playback
• After an advertisement finishes (preroll or midroll)
• When the user seeks back to the beginning of the stream
• After resuming playback from pause, if the overlay was previously interrupted

When the overlay hides

The overlay is hidden immediately if:

• The user pauses the video
• The player controls are shown
• An advertisement starts playing

If any of these interruptions occur, the autoShow timer resets. The overlay will be displayed again when one of the appearance conditions above is met.

AutoHide behavior

The overlay automatically hides after a configurable period (default: 5 seconds).