Content acquisition

Summary

Once a user has decided to purchase a product, the client application must send a purchase request to the OpenTV Platform. Assuming that the purchase is authorised, the subscription then authorises any internal or external requests to enable playback to commence. For example, for an Open Device this could be the authorisation of a DRM license to be delivered to the device.

The SDP handles all purchase requests and maintains the subscription information.

See Subscription data for details on retrieving and using the subscription data.

Data models

Context

The context model is used to provide the SDP with details on the device, user and account making the purchase request. See Account, User and Device data for details on how to retrieve it. It can be altered by the UI application if required, for example, to purchase the content for a different device than the one currently used.

Context data model

Name	Type	Description	Localised	Always available
`accessPointUid`	Integer	The unique Access Point identifier within the SDP. Can be used to request the full Access Point details from the SDP using the Access Point service. An Access Point provides details on the location the device resides in and how it should connect to the platform.	No	Yes
`accountNumber`	String	The account number. Usually provided by the service provider.	No	Yes
`accountOriginId`	Integer	In cases where the account number needs to be defined within the SDP for some reason, this field can be used to identify the system providing the account origin key information, if present.	No	No
`accountOriginKey`	String	In cases where the account number needs to be defined within the SDP for some reason, this field can be used to define the original account number as provided by the service provider. Rarely used.	No	No
`accountUid`	Integer	The unique account identifier within the SDP. This identifier is not known externally to the SDP, so it should only be used for SDP API calls. Account number should be used for account identification wherever possible.	No	Yes
`casn`	String	The Conditional Access Serial Number of the device CA chipset. Only applicable to set top boxes. It can be changed by a firmware change, but this is not common, so it can be used as a device identifier for signon.	No	No
`challengeId`	String	The solution to a recent challenge obtained from the `challengeAggregateService`, where required. This field is used in NAGRA Media PRM deployments that use challenges to provide additional security around purchasing and licensing. It only needs to be set when providing a `Context` object to an API that requires this additional security, such as those on `bocPurchaseService`. The same challenge ID may be used multiple times until it expires, normally in the order of 30 seconds after issue. Once a challenge ID expires, you must to obtain a new challenge using `challengeAggregateService.acquireSecureChallenge` and refresh this field with the decrypted challenge ID.	No	No
`deviceOriginId`	Integer	The identifier of the external system that provisioned the device. Only used if `deviceOriginKey` is present.	No	No
`deviceOriginKey`	String	The external identifier of the device. Not typically used, as external systems usually also identify devices by hardware identifiers such as CASN.	No	No
`deviceProfileUid`	Integer	Unique device profile identifier. Can be used to retrieve device profile information from the Profile service.	No	No
`deviceType`	String	The device type. Must be one of: `STB` – set top box `MP` – media player	No	Yes
`deviceUid`	Integer	Can be used to retrieve the full device information from the Device service.	No	Yes
`drmInstanceId`	String	The ID of the DRM system the client wishes to use. Typically not needed, as the DRM system is usually determined by the content itself.	No	No
`featureNameList`	List of strings	A list of the `name` of each Feature in the `DeviceProfile` associated with the request. If the client does not supply a value for this field, it is derived from the `featureUidList` where possible.	No	No
`featureUidList`	List of longs	A list of the `uid` of each Feature in the `DeviceProfile` associated with the request. If the client does not supply a value for this field, it is derived from the `deviceProfileUid` where possible.	No	No
`mediaPlayerId`	String	The identifer of the open device. Only applicable to open devices. Usually created by the DRM system during device initialisation.	No	No
`smartcardId`	String	The `smartcardId` of the device's smartcard, if there is one.	No	No
`userUid`	Integer	The user's unique identifier within the SDP.	No	Yes

8 reads

Offer specification

An OfferSpecification model allows the client application to specify any identifiers that it knows about a product to complete the purchase.

Offer specification data model

Name	Type	Description	Localized	Always available
`polgrpOriginId`	Integer	The `originId` of the Entity (that is, the identifier used by SDP for the system that owns the object).	No	*
`polgrpOriginKey`	String	The `originKey` of the Entity (that is, the identifier used for the object by the system that owns it).	No	*
`polgrpCasId`	String	Id of the policy group provided by CAS.	No	*
`polgrpCasInstanceId`	String	Id of the CAS instance for the policy group.	No	*
`polgrpUid`	Long	Unique Id of the policy group.	No	*
`offerId`	String	Offer id of the policy group.	No	Yes

* One of the following must be available:

polygrpUid
polgrpOriginId and polgrpOriginKey
polgrpCasId and polgrpCasInstanceId

Use cases

The use cases involve the bocPurchaseService and challengeAggregateService. This service provides APIs for purchase transactions, retrieval of payment methods, retrieval of purchase tokens, and challenge acquisition. The various use cases for this service are described below.

Get pay options for account

Fetch the payment options that are available to the specified Account.

All payment options supported by the Account's Service Provider are returned. The return objects include details of any credentials SDP holds for the Account.

If a payment option requires credentials but these are missing, the payment method cannot currently be used. The Account holder must contact the operator or payment provider to set up their credentials before they can use this payment option.

CODE

http://<server>:<port>/hue-gateway/gateway/http/js/bocPurchaseService/getPaymentOptionsForAccount

This API returns a list of PaymentProviderDetails, which contains the payment options available.

GET parameters

Name	Type	Description	Mandatory
`pContext`	Context	`Context` data model.	Y
`pAccountUid`	Long	The `uid` of the Account that is making the purchase.	Y

Purchase impulse or subscription product post-paid for account or smartcard

Subscribe to a Policy Group for postpaid scenario.

Different types of products, such as impulse or subscription, can be purchased using this API. The purchase can be linked either to the account or to the smartcard only by setting values in the parameter PurchaseFor.

CODE

http://<server>:<port>/hue-gateway/gateway/http/js/bocPurchaseService/purchasePolicy

This API on success returns a list of the uid of each Acquired Content List created as a result of the purchase.

GET parameters

Name	Type	Description	Mandatory
`pContext`	Context data model	A Context object with information about the client making the purchase.	Y
`pOffer`	Offer Specification data model	An OfferSpecification object containing information that identifies the Policy Group to be purchased.	Y
`pPurchaseFor`	PurchaseFor	Whether to provide access across the whole Account or just to a single smart card. Value must be one of `ACCOUNT` or `SMARTCARD`.	Y

Purchase impulse or subscription product at no cost account or smartcard

Subscribe to a Policy Group that is available at no cost. This method bypasses the normal payment processing, but verifies that the specified Policy Group has zero price. If the Policy Group must be paid for, an error is returned.

Different types of products, such as impulse or subscription, can be purchased using this API. The purchase can be linked either to the account or to the smartcard only by setting values in the parameter PurchaseFor.

CODE

http://<server>:<port>/hue-gateway/gateway/http/js/bocPurchaseService/acquireZeroPricedPolicy

This API on success returns a list of the uid of each Acquired Content List created as a result of the purchase.

GET parameters

Name	Type	Description	Mandatory
`pContext`	Context data model	A Context object with information about the client making the purchase.	Y
`pOffer`	Offer Specification data model	An OfferSpecification object containing information that identifies the Policy Group to be purchased.	Y
`pPurchaseFor`	PurchaseFor	Whether to provide access across the whole Account or just to a single smart card. One of `ACCOUNT` or `SMARTCARD`.	Y

Purchase product post paid for account with challenge

This use case involves retrieving the challenge using the challenge aggregateService and using this challenge to purchase a product.

Get challenge using challengeAggregateService

The challenge received can only be decrypted by the device's encryption hardware. The license server identifies Set Top Boxes and Media Players using their caSN, derived from the information provided during signon.

A client that does not provide device information when it signed on cannot use this API. This also applies to clients that sign on anonymously.

Media Players that initially signed on without providing device information can update their status using signonService.updateTokenWithMediaPlayer, supplying their mediaPlayerId. SDP responds with a new token that should be used in subsequent requests.

CODE

http://<server>:<port>/hue-gateway/gateway/http/js/challengeAggregateService/acquireSecureChallenge

There are no input parameters for this API.

This API returns an encrypted or signed challenge, suitably encoded, of type String.

Purchase product with Challenge

Using the challenge received in Purchase impulse or subscription product post paid for account or smartcard, this challenge can be used until its expiry.

Purchase impulse product for account and pay with card or e-wallet

Subscribe to a Policy Group and process payment using the details supplied. The payment can be made through various means such as a card or e-wallet.

CODE

http://<server>:<port>/hue-gateway/gateway/http/js/bocPurchaseService/purchasePolicyAndPay

The response is a list of the uid of each Acquired Content List created as a result of the purchase.

GET parameters

Name	Type	Description	Mandatory
`pContext`	Context data model	A Context object with information about the client making the purchase.	Y
`pOffer`	Offer Specification data model	An OfferSpecification object containing information that identifies the Policy Group to be purchased.	Y
`pPurchaseFor`	PurchaseFor	Whether to provide access across the whole Account or just to a single smart card. Value can be one of `ACCOUNT` OR `SMARTCARD`.	Y
`pPaydetails`	PaymentDetails	A PaymentDetails object specifying how this purchase will be paid for. The required fields of this object depend on the payment type (for example, card or e-wallet) that has been chosen.

Data models

Context

Offer specification

Use cases

Get pay options for account

Purchase impulse or subscription product post-paid for account or smartcard

Purchase impulse or subscription product at no cost account or smartcard

Purchase product post paid for account with challenge

Get challenge using challengeAggregateService

Purchase product with Challenge

Purchase impulse product for account and pay with card or e-wallet

See also