Playback of encrypted content

The following describes how to playback streams encrypted with native DRM systems (Widevine, PlayReady, TVKey or FairPlay). It assumes integration into an existing project; see the React Native SDK Integration Guide for details. To view this feature in a standalone project, see the readme in the examples.zip archive in the release files.

OTVPlayer source

To play encrypted content using OTVPlayer, in your React Native application's component, you need to:

• Import the OTVPlayer class.
• Specify an appropriate source property (including the drm and token properties) for the OTVPlayer Component.
• Add an OTVPlayer Component to your render tree.
• Call the OTVPlayer's play() method for an appropriate event (if the autoplay property is false).

Example code

…
import OTVPlayer from '@nagra/react-otvplayer'
…
const App: () => Node = () => {
    …
    this.otvplayer = {
        ref: OTVPlayer
    };
 
    // This is effectively an autoplay for when the media has loaded
    this._onLoad = (data = {}) => {
        this.otvplayer.ref.play();
    };
 
    this.events = {
        onLoad: this._onLoad.bind(this)
    };
 
	this.encryptedStream = {
		src: "https://stream.com/fairplay.m3u8",
		token: "t0ken",
		type: "application/x-mpegURL",
   		drm: {
			certificateUrl: "https://licenseservice.com/certificates",
			licenseURL: "https://licenseservice.com/licenses",
			type: "Fairplay"
		}
	}

    return (
        <OTVPlayer ref={otvplayer => this.otvplayer.ref = otvplayer}
            source={this.encryptedStream}
            style={[styles.player.container]}
            autoplay={true}
        >
        </OTVPlayer>
    );
    …
}
…

The main difference between this example and the clear playback is the definition of the source object passed to the OTVPlayer element. For encrypted content, the source alone is insufficient - a drm property with DRM type, a token, a licence URL, and a certificate URL for FairPlay must be given. For more information, see the OTVPlayer API documentation.

CONNECT DRM

CONNECT DRM is a NAGRA-provided DRM system available on certain Android TV devices (typically Android TV STBs provided by service providers). As it is not the native DRM system for Android, the application is required to override the defaults. This is done by explicitly setting the drm object within the source property.

Relating to the example code above, the source stream configuration is slightly modified to specify the DRM type as Connect. A certificate URL should also be provided for fetching the Operator Vault (OpVault). With SSP servers, the Certificate URL is https://<license-server-domain>/filedownload/v1/opvault.

:
:
    source={{
        src: "https://otvplayer.nagra.com/demo/content/ed_big_buck_bunny_1080p/big_buck_bunny.mpd",
        type: "application/dash+xml",
        token: "eyJraWQiOiIyOTI4NDgiLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ2ZXIiOiIxLjAiLCJ0eXAiOiJDb250ZW50QXV0aFoiLCJjb250ZW50UmlnaHRzIjpbeyJkZWZhdWx0S2NJZHMiOlsiYjEzZTQ1ZDAtMDMyNC00NmRkLTg0ZDUtM2IyZDY3OTJlYjM0Il0sImNvbnRlbnRJZCI6ImRhc2gtZGVtb19iaWdfYnVja19idW5ueSIsInN0b3JhYmxlIjp0cnVlLCJlbmNyeXB0aW9uTWV0aG9kIjoiUkFXX0FFU18xMjhfQ1RSX0NFTkMiLCJkZWZhdWx0VXNhZ2VSdWxlcyI6eyJtaW5MZXZlbCI6MCwiZGlnaXRhbE9ubHkiOmZhbHNlLCJ1bnByb3RlY3RlZERpZ2l0YWxPdXRwdXQiOnRydWV9fV19.3tc0D6EGRe7nkPVT9g1vaqyoWuviZKboQQlLtKtlSj0,eyJrY0lkcyI6WyJiMTNlNDVkMC0wMzI0LTQ2ZGQtODRkNS0zYjJkNjc5MmViMzQiXSwidHlwIjoiSldUIiwiZW5jIjoiQTEyOENCQy1IUzI1NiIsImFsZyI6ImRpciIsImtpZCI6IjI5Mjg0OCJ9..nJHHvkDRCWJt5poriL-whg.oXukvAclNVKVxSRz-hMU8Yj4Uju0DSSYAC3q9q7HX_WBlG1U6WG8S_K83JMBxwNfaFsT2EhdFF_KgeIe_2uZTFa3lapFcx2RAIKxv7atZIT3bm284rUX0_DQjRXDnZGh3h1Jiq6H6MnHt1DuxzvqmxnScJXlYXH9Y_mxokHfjAM.gIbpzdJXg-kli7UBc98bVA",
        drm: {
            certificateURL: "https://uex3xj0i-ov.anycast.nagra.com/filedownload/v1/opvault/",
            licenseURL: "https://uex3xj0i.anycast.nagra.com/UEX3XJ0I/prmls/contentlicenseservice/v1/licenses/",
            type: "Connect",
        }
    }}
:
:

Deferred setting of the content token

The above examples assume that when setting the source property of encrypted content, the content token necessary for acquiring the DRM licence is already known. Sometimes, when a user selects encrypted content to play, the application does not yet have a token for requesting a DRM licence. The application can fetch a token from the head-end and then set the source property, including the fetched token. However, this would add to the start-up/zapping time because the source would only be set after retrieving the token value.

The player provides the means to avoid this extra start-up time in the following way:

1. The user requests playback of an encrypted content. In parallel:
   • The application sends an asynchronous request for a content token from the head end.
   • The application sets up the player and provides it with the source property object, including the drm object, but with the token string set to null.
2. The player begins setting up the playback of the given stream (e.g. downloading the stream's manifest).
3. The requested content token is retrieved from the head-end, and the application passes the token string to the CONNECT Player.

The player now has all the information to continue with the playback.

The player will not attempt to begin playback until the token is pre-delivered when the source is set or deferred. When the token is required for fetching the licence, the player will wait up to five seconds for a deferred token or timeout with an error.

Example

The ssmAsyncContentToken example code emulates an application's requirement to request a token by setting up a timer and providing the token on its expiry. The currentSource can be set with or without the token and then sent to the player during construction.

...
if (this.state.initContentToken) {
    // Generate source with content token
    currentSource = { token: this.selectedStream.token, ...currentSource };
}
...
render() {
    return (
        <View style={[styles.player.container]}>
            <OTVPlayer
                ref={(otvplayer) => { this.otvplayer.ref = otvplayer }}
                source={this.streamSource()}
                style={[styles.player.container]}
                autoplay={true}
                onError={this._onError.bind(this)}
            />
            {this.renderBottomControls()}
        </View>
    );
}
...

When the token arrives (in the example code - when the dummy timer expires), the content token string is passed to the currentSource object through the streamSource() method:

...
// Generate source with content token
currentSource = { token: this.selectedStream.token, ...currentSource };
...

Error handling

An error will occur and be reported via the usual onError callback if a token is absent from the source object initially provided to the player and not provided within five seconds from the moment the player requires it to continue. The error code is 5022 (Content token error) of type DRM.