Subscription data

Summary

A UI application will need to retrieve the user's subscription data to display the appropriate UI elements depending on content subscription state. For example, when browsing content subscribed content can be flagged as such with a "Subscribed" logo or text, and when selected subscribed content should give the option of Play/Watch rather than Purchase. It might also be necessary to display a list of subscribed products in a list for the customer's information.

Subscription data is held in the NAGRA SDP when it is deployed, as one of its primary functions is as a purchase manager.

Data models

The primary data model for subscription data is the Acquired Content List (ACL).

Acquired Content List (ACL)

Each Acquired Content List is a subscription to a single product. Any product can be associated to any number of BTV channels, events or VOD content (typically not a combination however). The ACL item contains details on the product subscription creation, start and end of validity, subscription type, and a link to the product itself.

ACL entries are generated internally by the SDP when a purchase is completed. Likewise, the ACL is managed for validity by the SDP. Once the ACL expires, its status changes to unsubscribed. Therefore, a client need only retrieve ACL data, there is no need to manage it.

A client must periodically update the list even when no client-side purchases are made, because subscriptions could also be managed by the operator. There is currently no notification mechanism to notify the client of ACL changes; a periodic retrieval mechanism must be used to keep the client up to date. Therefore, the general advice is to retrieve the ACL on application startup, every hour after that, and after a purchase is successful.

Acquired Content List

Name	Type	Description	Localised	Always available
`accountUID`	Long	The UID of the account that acquired the content.	No	Yes
`aclExpiryDate`	Date	Expiration date inserted in the license.	No	No
`consumptionWindowSecs`	Integer	The length of the Consumption Interval of the purchased Base Price, in seconds. If this field is present, the purchased Policy Group is using relative licensing.	No	No
`deviceUID`	Long	The UID of the STB or media player that acquired the content, if known.	No	No
`expiryDate`	Date	The date the content acquired will stop being available to the user.	No	Yes
`licenseExpiryDurationSecs`	Integer	The expiry duration of Licenses granted under the purchased Policy Group. For absolute VOD (either TVOD or SVOD), this is set to the global VOD license duration configured at the time of purchase. For relative, transactional VOD, this is set to the length of the Expiry Interval of the purchased Base Price. For relative, subscription VOD, this is set to the global relative SVOD license duration configured at the time of purchase.	No	Yes
`originID`	String	The identifier used by SDP for the system that owns the object.	No	No
`originKey`	String	The identifier used for the object by the system that owns it.	No	Yes
`policyGroupUID`	Long	The UID of the purchased PolicyGroup (product).	No	Yes
`productType`	String	The CAS product type for the item.	No	Yes
`purchasedItemType`	String	The type of the purchased item. An Acquired Content List ItemType value. Can be one of: `AST` `AGR` `CAT` `PKG` `PLG` `SUB`	No	Yes
`purchasedItemUID`	Long	The UID of the purchased item.	No	Yes
`uID`	Long	The SDP internal UID for this entity.	No	Yes
`userUID`	Long	The UID of the user that acquired the content.	No	No
`validFrom`	Date	The date the content acquired becomes available to the user.	No	Yes
`viewingNumber`	Integer	The maximum number of times viewers can watch the content, where this restriction applies to the product type. For on-demand content, this is the `viewingNumber` of the purchased Asset.	No	No

10 reads

Example response of Acquired Content List

CODE

{ 
    "UID" : 342,
    "accountUid" : 48, 
    "purchasedItemUID" : , 
    "purchasedItemType" : "AST",
    "productType" : "SVOD",
    "policyGroupUID" : 12 ,
    "userUID" : 21,
    "deviceUID" : 23,
    "expiryDate" : "12-12-2014",
    "aclExpiryDate": "12-12-2014",
    "validFrom" : "12-11-2014",
    "consumptionWindowSecs" : 123123,
    "licenseExpiryDurationSecs" : 12312,
    "viewingNumber" : 12
    "originID" : "1"
    "originKey" : "abc"
 }

Use cases

The ACL should be retrieved from the SDP via the SDP Adaptor. The SDP adaptor is needed because the SDP does not store the external ids of the products in the ACL. The SDP Adaptor injects the product external id into the response on the fly. The external product id is required because this is the identifier used by other services such as the MDS and CDG.

The response contains a value for purchasedItemOriginKey, which is the product ID. This id can then be used with the MDS to retrieve further information about the product, or identify associated content.

Retrieving the ACL for an account

Typically, periodically retrieving the ACL for the account is sufficient. This returns all current entitlements to the account.

CODE

http://server:port/adaptor/hue-gateway/gateway/http/js/acquiredContentListService/getByAccountUID

GET parameters

Name	Type	Description	Mandatory	Example

`arg0`	long	Account UID.	Y	123
`arg1`	string	Status by date.	Y	CURRENT
`locale`	string	Locale.	Y	en_gb
`token`	string	SDP authentication token.	Y

By requesting a status of "CURRENT", only currently valid subscriptions are returned. The Account UID is the UID, that is, the SDP internal identifier, not the "number". This can be found by retrieving the account or context details.

Retrieving the ACL for an account and smartcard

When ACL is needed to be specifically retrieved for a smartcard in that account, the following API should be used.

CODE

http://<server>:<port>/adaptor/hue-gateway/gateway/http/js/acquiredContentListService/getByItemAndAccountUIDSmartCard

GET parameters

Name	Type	Description	Mandatory	Example

`arg0`	long	Account UID.	Y	123
`arg1`	long	purchasedItemUID.	Y	217
`arg2`	string	purchasedItemType.	Y	AST
`arg3`	long	profileUID.	Y	12
`arg4`	string	smartcardID.	Y	3422
`locale`	string	Locale.	Y	en_gb
`token`	string	SDP authentication token.	Y

This returns a list of Acquired Content List objects that is associated with the account and the smartcard.

Data models

Acquired Content List (ACL)

Use cases

Retrieving the ACL for an account

Retrieving the ACL for an account and smartcard

See also