Entitlement and DRM

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 entitlement check and DRM.

Before starting

Ensure the DIVA Back Office instance you rely on is up and running.
Ask your video engineers team the <video id> and <settings URL>.

Ensure the settings file contains:

The entitlementCheck section:

"entitlementCheck": {
    "entitlementUrl": "<yourEntitlementBaseURL>/tokenize",
    "heartbeatUrl": "<yourEntitlementBaseURL>/heartbeat",
    "heartbeatPollingInterval": 180000,
    "heartbeatSeekInterval": 10000,
    "other": "{<sessionId>}|{<platform>}",
    "fairPlayCertificateUrl": "<yourFairPlayCertificateBaseURL>/fairplay.cer",
    "queryParams": ["VideoSourceName", "VideoId", "VideoKind"],
    "retries": 4,
    "data": {
        "sessionId": "{Run.SessionID}",
        "platform": "webTV custom/Amidala",
        "idfa": "{Run.idfa}",
        "p.adsParams.paln":"{diva_pal_nonce}"
    }
  }

Note: Consider other deprecated and replaced by data.

The videoPlatformsPriority section:

"videoPlatformsPriority": {
    "default": [
        {
            "type": "DASH"
            "sourceName": "Desktop-DASH",
            "drmType": "playready"
        },
        {
            "type": "DASH",
            "sourceName": "Desktop-DASH",
            "drmType": "widevine"
        },
        {
            "type": "HLS",
            "sourceName": "Desktop-V4",
            "drmType": "fairplay"
        }
    ],
    "chromecast": [
        {
            "type": "DASH",
            "sourceName": "Chromecast-DASH",
            "drmType": "widevine"
        }
    ]
}

Instantiation

DRM code

There's no code to add to the Basic instantiation code.

Entitlement code

Enrich the Basic instantiation code with the entitlement configuration:

entitlementUser: It returns the token that entitles a video player user to stream a specific video.
version: If valued, the entitlement payload uses data, otherwise other — Note: other is a legacy and deprecated field: use data

entitlementPayloadMap: Callback function that receives the entitlement payload as parameter and returns a Promise with the payload eventially modified. entitlementPayloadMap can change the entitlement payload before DIVA Player sends it to the entitlement service. entitlementPayloadMap input parameters are:

type: It can value token or heartbeat
- token: It indicates the entitlement initialization call.
- heartBeat: It indicates the entitlement check call.

payload: Created every time DIVA Player calls the entitlement service, if version is valued, it uses data, otherwise other. E.g.:

{
  "Type": 1, // 1 = 'token', 2 = 'heartbeat'
  "User": "<userID>", //user identifier
  "VideoId": "<videoID>",
  "VideoSource": "<video source>",
  "VideoKind": "replay", //possible values depend on the video production
  "AssetState": "3", //2 = 'live', 3 = 'VOD'
  "PlayerType": "<player type>",
  "VideoSourceFormat": "DASH",
  "VideoSourceName": "Desktop-DASH",
  "DRMType": "widevine",
  "AuthType": "Token",
  "ContentKeyData": "<content key data>",
  "SessionId": "<sessionID>",
  "PlaybackSessionId": "<PlaybackSessionId>",
  "Other": "{\"<sessionId>\"}|{\"<platform>\"}",
  "Data": "{\"sessionId\":\"<sessionID>\",\"platform\":\"webTV custom/Amidala\",\"idfa\":\"{Run.idfa}\",\"offsetFromLiveEdge\":\"0\",\"p.adsParams.paln\":\"{diva_pal_nonce}\"}",
  "Version": "1"
}

Note: If AssetState = "1" there's something wrong: "1" means 'scheduled', which is a not yet existing video that DIVA Player cannot manage.

Entitlement code sample

Write the entitlement configuration:

const token = "<entitlement token of the video player user>";

const entitlementPayloadMap: (entitlementType: 'token' | 'heartbeat', payload: any) => Promise<any> = (
  entitlementType,
  payload
) => {
  // Modify the payload
  payload.PlayerType = 'myPlayer'
  return Promise.resolve(payload);
};

const entitlementConfiguration = {
    entitlementUser: () => token,
    entitlementPayloadMap: entitlementPayloadMap,
    version: "1"
};

Finally, add the entitlementConfiguration to the DIVA Player instantiation.

Working sample code (.tsx)

import React from "react";
import { DivaWebBoAdapter } from "@deltatre-vxp/diva-sdk/diva-web-bo-adapter";
import "@deltatre-vxp/diva-sdk/diva-web-sdk/index.min.css";

const videoId = "<videoId";

const libs = {
  mux: "https://cdnjs.cloudflare.com/ajax/libs/mux.js/6.2.0/mux.min.js",
  shaka: "https://cdnjs.cloudflare.com/ajax/libs/shaka-player/4.11.2/shaka-player.compiled.js",
  hlsJs: "https://cdn.jsdelivr.net/npm/hls.js@1.5.7",
  googleIMA: false,
  googleDAI: false,
  googleCast: false,
  threeJs: false
};

const config = {
  videoId: videoId,
  libs: libs,
};

const token = "<entitlement token of the video player user>";

const entitlementPayloadMap: (entitlementType: 'token' | 'heartbeat', payload: any) => Promise<any> = (
  entitlementType,
  payload
) => {
  // Modify the payload
  payload.PlayerType = 'myPlayer'
  return Promise.resolve(payload);
};

const entitlementConfiguration = {
    entitlementUser: () => token,
    entitlementPayloadMap: entitlementPayloadMap,
    version: "1"
};

const props = {
  settingsUrl: "<Settings URL>",
  languageCode: "en-US",
  languageDictionary: "en-US",
  onDivaBoAdapterError: console.error,
  config: config,
  entitlementConfiguration: entitlementConfiguration

function App() {
  return (
    <DivaWebBoAdapter
      {
      ...props
      }
    />
  );
}

export default App;

Entitlement Calls Retries

The Entitlement Calls Retry feature is designed to reduce the frequency of error code 22, particularly in cases of network-related issues, by retrying failed API calls after a predefined waiting period. This mechanism enhances the reliability of entitlement checks, ensuring a smoother user experience, especially in environments with intermittent network failures.

Behaviour

Retries are initiated only when an API call returns an HTTP response in the 500-599 range (server error codes). All other error codes will cause the process to fail immediately, returning the specific error code without retrying.
The interval between retries follows a Fibonacci sequence starting from the second element: 1, 2, 3, 5, 8, 13, 21. This ensures increasing delays between retries, helping to manage the load on both the client and server. The maximum delay is capped at 21 seconds.
The retry mechanism applies to both token and heartbeat API calls, which are critical for entitlement validation. Network issues affecting either of these calls will trigger the retry process.
The maximum number of retry attempts before the system stops and returns a final failure (error code 23) is configurable based on the environment. This allows flexibility in adapting to varying network conditions.
The retry configuration for the Entitlement Provider can be customized via the Settings
entitlementCheck -> retries
By default, the retry limit is set to 4 retries, but this can be modified to suit the needs of different environments.
If all retry attempts are exhausted without success, the system will emit error code 23, indicating the final failure after reaching the configured retry limit.

What you learn​

Before starting​

Instantiation​

DRM code​

Entitlement code​

Entitlement code sample​

Working sample code (.tsx)​

Entitlement Calls Retries​

Behaviour​