Content entitlements

Content entitlements gate premium content per viewer. The SDK carries the viewer's identity to the content service, resolves each item against it, and reports the service's decision. Entitlement is enforced server-side: the SDK never decides who is entitled, it relays the decision.

The flow

1. Viewer token. The host supplies a token that identifies the viewer, either on init or later through setExternalUserToken. The SDK passes it to the content service unchanged and holds it in memory only, so it is supplied again on every launch. Until a token is set, any item that arrives without a playback URL is refused with the missing-token reason (externalUserTokenMissing on iOS, EXTERNAL_USER_TOKEN_MISSING on Android).
2. Resolve. When an item is about to play, the SDK asks the service to resolve it under the current token. An entitled item returns a playback URL and plays. A refused item returns a reason. A stream that has not started yet is checked too, so onContentRestricted can fire before the stream goes live.
3. Restriction event. The SDK raises onContentRestricted with the reason and which item was refused. The value the host returns says whether the host took care of the refusal, for example with its own paywall.

What happens to a refused item

Playback of a refused item does not start, whatever onContentRestricted returns. The SDK holds the item on screen (it does not skip it) and removes the controls and indicators that would promise playback.

• iOS: the SDK currently applies the treatment above whatever is returned. Return handledByApp when the host presents its own response, such as a paywall. Returning sdkShouldHandle, or leaving the handler unset, leaves the refusal to the SDK, which does not currently present its own restriction UI.
• Android: the return value is reserved for a later version, in which it will choose between the SDK's own presentation of the refused item (SDK_SHOULD_HANDLE) and the host's (HANDLED_BY_APP). For now the SDK applies the treatment above whatever is returned.

Token changes mid-session

Changing the token cancels any resolve still in flight and re-resolves the item currently on screen under the new token, so playback can start, or onContentRestricted fire again, without reopening the player. BlazeFetchedContentPolicy controls whether content already fetched is kept or evicted and refetched.

Content with no playable URL

When the entitlement feature is off, an item that arrives without a playable URL is omitted rather than shown as a dead item. Videos and Moments drop the individual item; a Story drops as a whole if any one of its pages has no playable URL, since a Story is played as a single unit. When the feature is on, such an item is kept and resolved as described above, since its URL was removed on purpose.

Per-platform reference

• iOS: setExternalUserToken in Methods and parameters; onContentRestricted, the reasons, and the related types in BlazePlayerSourceDelegate.
• Android: setExternalUserToken in Methods and parameters; onContentRestricted, the reasons, and the related types in BlazePlayerSourceDelegate.

Related

• Content delivery
• Delegates
• Stream tokenization