Skip to main content

Secure Playback

Create Platform Authorizer​

The PlatformCore or PlatformAuthorizer facilitates seamless interaction with all nexgen platform services with an industry standard security model. You should create one instance of platform authorizer and use it for one app session.

To create an instance of Platform Authorizer, you'll need a client Id, client secret, authorization endPoint, headers (optional), and a User Authorization Delegate. You'll receive the client Id and secret when you onboard onto the Quickplay platform. Your client app must implement and provide a user authorization delegate that delivers the UMS token required for authorization with platform services.

You'll receive the endPoints when you onboard onto the Quickplay platform.

// Platform Authorizer creation snippet
val platformAuthConfig = PlatformAuthConfig.Builder()
.id("clientID")
.secret("clientSecret")
.xClientId("Quickplay-main-androidmobile")
.tokenEndPointURL("https://sample.com")
.headers(
mapOf(
"X-Property-Id" to "string-value"
)
) // Optional custom request headers (Map<String, String>):
// Use this to inject backend-specific metadata or identifiers.
.build()

// Implement UserAuthorizationDelegate and use it to create PlatformAuthorizer
val platformAuthorizer = PlatformAuthorizer.Builder()
.withConfig(platformAuthConfig)
.userAuthorizationDelegate(userAuthDelegate)
.build(context)
note

You can create only one instance of PlatformAuthorizer at any point in time, and you should use this instance for the complete application session. You must dispose of the existing PlatformAuthorizer instance by calling platformAuthorizer.dispose() before creating a new one.

warning

Your application owns the responsibility of returning a valid user token through the userAuthorizationDelegate implementation. Whenever the user changes, you must refresh the user token accordingly.

Create PlatformClient​

PlatformClient provides platform-specific identifying information for a given device. We recommend using the DefaultDeviceInfoPlatformClient method to create an instance of PlatformClient. Using DefaultDeviceInfoPlatformClient populates all other relevant info (for example, Device model, Device manufacturer, Android version) automatically. If you want to override any of the default values, you can do so by passing the desired value to the method.

val deviceId = "myDeviceId"
val platformClient = DefaultDeviceInfoPlatformClient(deviceId)

You're required to persist the PlatformClient instance to identify the same device on subsequent sessions.

Create Content Authorizer​

The ContentAuthorization library assists with authorizing an asset for either playback or download. To create an instance of content authorizer, you'll need a platform authorizer, device registration endPoint, content authorization endPoint, and a client device.

The ContentAuthorizer expects a PlatformAsset, which represents a potential playable asset and the type of delivery for which authorization is requested. The delivery type can be streaming or download. Upon successful authorization, you'll obtain a PlaybackAsset, which you can use to play with the Quickplay Player.

// Content Authorizer creation
val contentAuthorizer = ContentAuthorizer.Builder(
platformTestHelper.context,
clientRegistrationEndPoint,
contentAuthorizationEndPoint
).platformClient(platformClient)
.build()
note

We recommend creating contentAuthorizer during app start and invoking ContentAuthorizer.ensureDeviceRegistration to ensure device registration before content authorization. If you don't do this, contentAuthorizer will automatically register the device before the first content authorization request. Performing device registration at app launch optimizes authorization response time during the first authorization request. There's no limit on contentAuthorizer instance creation, but we recommend using one instance for the complete application session.

warning

A contentAuthorizer is tied to a single device (PlatformClient) and user during its lifetime. Whenever the user changes or the deviceId changes (when you provided deviceId while constructing PlatformClient), you must re-register the device.

Authorize Playback​

The player library facilitates playback by content url and provides complete control for integrators.

You can construct a PlatformAsset with APIs from ContentAuthorizer by providing the following:

  • Content Id: Unique identifier of the content
  • Media Format: HLS | DASH | SmoothStream
  • DRM: Fairplay | Widevine
  • Catalog Type: movie | tvepisode | shortvideo | sportshow | sporthighlight | sportclip | sportevent | sportsliveevent | channel | event
  • Content Type: VOD | Live
// create asset
val platformAsset = PlatformAsset(
contentID,
MediaType.DASH,
consumptionType,
catalogType,
DrmType.WIDEVINE
)

You must authorize the created asset (either for streaming or download) with the Quickplay platform to obtain a ContentAuthorizationToken.

when (val result = contentAuthorizer.authorizePlayback(platformAsset, null)) {
is Result.Failure -> {
val error = result.value
// handle authorization error as required
}
is Result.Success -> {
val contentAuthorizationToken = result.value
// use ContentAuthorizationToken to build the player
// and to set up other functionalities as required
}
}

The ContentAuthorizationToken has content metadata such as content url, license url, licenseToken, mediaFormat, and drmType. You can use the asset with the Quickplay Player library for playback or download.

Control pre-roll in playback authorization​

Set PlatformAsset.disablePreroll to true when requesting playback authorization with pre-roll disabled. The property defaults to false.

val playbackAsset = platformAsset.copy(disablePreroll = true)

val result = contentAuthorizer.authorizePlayback(
platformAsset = playbackAsset,
headers = null
)

The SDK copies this flag into ContentAuthorizationRequest and sends it as the string "true" or "false" under the JSON key disablePreroll. If you construct a request with ContentAuthorizationRequest.Builder, use disablePreroll(true) to set the flag.

Read audio and player preferences​

The successful playback authorization response exposes two optional properties on ContentAuthorizationToken.

PropertyKotlin typeDescription
upfrontAudioBoolean?Indicates whether to show an audio language prompt before playback. Returned for multi-audio titles when the user has no saved audio language.
preferencePlayerPreference?Player settings saved by the user in setting-cloud. Null when no settings are returned or for single-audio titles.

Both properties default to null when absent from the response. Check upfrontAudio == true to decide whether to show the audio picker before starting playback.

// Read these values from the token returned in Result.Success.
val shouldPromptForAudio = contentAuthorizationToken.upfrontAudio == true
val savedPreference = contentAuthorizationToken.preference

val savedAudioLanguage = savedPreference?.audio?.lang
val savedAudioKind = savedPreference?.audio?.kind
val subtitlesEnabled = savedPreference?.subtitle?.enabled
val savedSubtitleLanguage = savedPreference?.subtitle?.lang
val savedSubtitleType = savedPreference?.subtitle?.type
val savedVideoQuality = savedPreference?.video?.quality

Your app uses shouldPromptForAudio to decide whether to present a language picker and when to start playback. Use the saved values to initialize the app's playback choices.

Preference fields​

PlayerPreference and its nested models are in com.quickplay.vstb7.platform.model. All fields are optional and default to null.

PropertyKotlin typeDescription
PlayerPreference.audioAudioPreference?Saved audio settings.
PlayerPreference.subtitleSubtitlePreference?Saved subtitle settings.
PlayerPreference.videoVideoPreference?Saved video settings.
AudioPreference.langString?Saved audio language, matched to the title's languages ignoring case.
AudioPreference.kindString?Audio track kind, for example "main".
SubtitlePreference.enabledBoolean?Whether subtitles are enabled or disabled.
SubtitlePreference.langString?Saved subtitle language.
SubtitlePreference.typeString?Subtitle track type, for example "sdh". The response JSON key is ty.
VideoPreference.qualityString?Saved video quality label, for example "HD".

For example, a response containing saved preferences can include this fragment.

{
"upfrontAudio": null,
"preference": {
"audio": { "lang": "eng", "kind": "main" },
"subtitle": { "enabled": true, "lang": "eng", "ty": "sdh" },
"video": { "quality": "HD" }
}
}

Apply the saved choices​

Once audio tracks are available, apply the saved language through the SDK player instance.

import com.quickplay.vstb7.player.AudioLanguageInfo

savedAudioLanguage?.let { language ->
player.setPreferredAudioLanguage(AudioLanguageInfo(languageCode = language))
}

Use AudioPreference.kind to choose the corresponding audio role when your app supports role-based selection. For subtitles, use enabled to decide whether to enable them, then match the saved language and type to the available tracks. Map video quality labels such as "HD" to the resolution and bitrate range your app offers.

See Track Selection for selecting audio and subtitle tracks, and Get available resolutions for reading and applying video bitrate ranges.

Start Playback​

You can create a Player instance by supplying player builder properties like contentURL, mediaType, drmScheme to the PlayerBuilder class.

const val DEFAULT_CLIENT_AGENT = "FLClientAgent"

val player = PlayerBuilder()
.mediaURL(contentURL)
.mediaType(mediaType)
.drmScheme(drmScheme)
.drmLicenseURL(licenseURL ?: "")
.userAgent(DEFAULT_CLIENT_AGENT)
.playbackProperties(PlaybackProperties(
preferredMinBufferDurationMs = DEFAULT_MIN_BUFFR_DURATION))
.build(getApplication())

player.play()