Customer SSM
To test this feature and view the example code, please see the Browsers and Connected TV SDK 5 Example Code Quick Start guide.
In nagra-ssp DRM mode, the CONNECT Player SDK supports Secure Session Management using the standard SSP API to perform session setup and management, and licence acquisition and renewal as necessary. In some system architectures, for example where an API gateway is used, use of these standard interfaces is not possible. The customer-ssm mode facilitates secure session management in such systems.
When using the SDK in customer-ssm mode, all session management, licence acquisition and renewal is handled by the client application. The SDK prompts the client application when these operations are required, using a pair of callbacks provided in the player configuration.
Configuring the player for customer SSM
Configuration of the player is described in the Browsers and Connected TV SDK 5 Integration Guide. For SSP with customer-ssm, configure the DRM as follows:
otvtoolkit: {
drm: {
system: "customer-ssm",
config: {
customerSsmCallback: {
getLicence: applicationLicenceAcquisitionFunction,
heartbeat: applicationHeartbeatRenewalFunction
},
// Optional: If the widevineServerCertificate is not set then two callbacks will be made for every widevine licence request
widevineServerCertificate: "base64 string containing the certificate"
}
}
}
getLicence callback
The SDK will call the getLicence
callback when a licence is first required, and periodically when it is required to be renewed. It will be necessary to perform a secure session setup before acquiring the licence for the first time.
function getLicence(keySystem, payload, requestType)
getLicence parameters
keySystem
will be identified using the DASH ContentProtection Scheme identifier as shown in the table below.payload
as passed from the browser CDM, and will be required for the licence acquisition.requestType
will indicate whether this is the first request for a licence, or whether the request is to renew an existing licence. It will have the value"license-request"
or"license-renewal"
.
Key System | Identifier |
---|---|
Widevine | edef8ba9-79d6-4ace-a3c8-27dcd51d21ed |
PlayReady | 9a04f079-9840-4286-ab92-e65be0885f95 |
FairPlay | 94CE86FB-07FF-4F43-ADB8-93D2FA968CA2 |
getLicence Return Value
The getLicence
callback will return a promise.
If the licence acquisition/renewal is unsuccessful, the promise should reject with an error message.
If successful the promise should resolve with the following parameter:
{
licence: licenceReturnedFromSsp
heartbeat: sessionRenewalPeriodInSeconds
}
Licence Format
PlayReady
The licence should be passed to the SDK (via the resolved promise) in the same format in which it is acquired from SSP, i.e. a text or XML string.
Widevine
The licence should be passed back to the SDK in binary format as a Uint8Array
. If the Application/JSON
API is used to renew the licence, it must be packaged as follows:
try {
var responseJSON = JSON.parse(xhr.response);
// Convert the licence to a Uint8Array to return to the SDK
var string = atob(responseJSON.license);
var buffer = new ArrayBuffer(string.length);
var array = new Uint8Array(buffer);
for (var i = 0, strLen = string.length; i < strLen; i++) {
array[i] = string.charCodeAt(i);
}
resolve(array);
} catch () {
reject("Unable to parse returned JSON licence");
}
Heartbeat callback
In systems where it is supported, the secure session will be enforced by a short duration licence which will require periodic renewal. For other systems, the application will need to use the heartbeat API on the SSM server. This callback will prompt the application to use this API. This callback has no parameters and no return value. If the callback fails then the application must take any necessary actions.