Using entitlement state messaging to update stored entitlement information

Overview

OpenTV Platform’s Rights Manager (RMG) service supports messaging to client applications when there are changes to entitlements for the account that the device belongs to. It sends these messages using Device Messaging Manager (DMM).

The device that the client app is running on must already be registered in OpenTV Platform via Firebase (FCM) or AWS IoT messaging platforms.

A registered client application can use these messages to update their account’s entitlement state in a more real-time fashion, reducing the need to make calls to refresh the client's view of the account’s entitlement state.

Message descriptions

Messages received by a client are sent via DMM using a topic-based exchange named nagra.events. Messages are distributed via a topic entitlement.*, which includes the events entitlement.created, entitlement.updated, and entitlement.deleted.

The payload received for created and updated events contains extensive product entitlement attributes to qualify the change, including but not limited to:

      properties: {
        "productId": {
          "type": "string"
        },
        "accountId": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "productType": {
          "type": "string"
        },

You can find a fuller set of attributes in the Rights Manager (RMG) API documentation – see the GET /v1/user/entitlements endpoint.

A deleted event contains just a reference to the entitlement that has been removed.

Usage guidelines

When integrating a client, there are a number of cases and conditions to bear in mind, as follows.

Distribution policy

Each entitlement state message that can be sent to clients provides incremental information about the state of a particular entitlement that has changed for an account. By default, changes for all entitlements are sent unless an entitlement is individually marked not to send a message.

Initial state on client application start up

When a client application starts for the first time or is reused after an extended period, it may be that it needs to call RMG to get all entitlements to prime its view of the account’s entitlement state when presenting content. In this case, the incremental entitlement messages are not a substitute for a full read to establish a baseline view of entitlements.

Maximise use of entitlement message payload

When an entitlement message is received, there may be sufficient information in the message payload to remove the need for a call to RMG to assess entitlement status. In this case, the client application updates its state and continues without additional OPF backend interaction.

Deferral/lazy update of events

Some types of entitlement may be “bulk” in nature, that is, lots of accounts have the same subscription, so client application actions requiring further calls to RMG should defer them as much as possible to the point where an instance of a client application needs to refresh. This will reduce call spikes into the head-end when a commonly used subscription is updated.