Account, user, and device data

Summary

The client UI application will usually need to retrieve some account, user and device data, both for displaying information to the end user, and using the data to populate other API requests.

For example, it might be a requirement to display the account number somewhere in the UI.

User data: User data is usually only relevant when using an open device where signon is by user and device ID rather than just a hardware identifier.

Data Models

Context

When performing signon to the Service Platform as described in Authentication, a token is generated. This token contains key identification regarding the caller's account, user and device.

The client can retrieve additional information about their account, user and device by requesting their own context data from the SDP.

A device's context should also be supplied to the SDP when using certain APIs. This allows the client to change the context, for example, if they want to call an API based on another device's information (which belongs to the same account; this will be checked during authorisation).

Context object

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

Account

An account includes information about a customer account. It is not expected that a client needs any specific account data apart from the UID/number to function, as most of the parameters are only relevant to CRM/SMS systems.

Account parameters

Name	Type	Description	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.	Yes
`accountNumber`	String (max 20 chars)	The account number. Usually provided by the service provider.	Yes
`accountProfileUID`	Integer	The unique account profile identifier within the SDP. This profile is used to specify the maximum number of allowed devices, device activations, and concurrent OTT streams. Available from SMSDomain-1.3 and above.	No
`address1`	String (max 150 chars)	First line of address.	No
`address2`	String (max 150 chars)	Second line of address.	No
`city`	String	Address city name.	No
`country`	String (max 50 chars)	Address country.	No
`county`	String (max 100 chars)	Address county.	No
`creditLimit`	Double	The maximum spend per globally-specified credit interval, for example, a calendar month. If empty, the account will be able to make unlimited purchases.	No
`creditSpent`	Double	The credit spent so far in the current time period.	No
`creditSpentRS`	String	Not relevant to clients. Used by billing jobs. Available from SMSDomain-1.3 and above.	No
`firstName`	String	Account holder first name.	No
`lastname`	String (max 100 chars)	Account holder last name.	No
`locality`	String (max 100 chars)	Address locality, that is, area name.	No
`maxMPDeviceAllowed`	Integer	The number of open devices associated with the account cannot exceed this value, if set.	No
`maxUserAllowed`	Integer	The number of users associated with the account cannot exceed this value, if set.	No
`npvrProfile`	String (max 32 chars)	The network PVR profile used for this account. Available from SMSDomain-1.3 and above.	No
`password`	String (max 20 chars)	Not typically used.	No
`postcode`	String (max 10 chars)	Postcode or zipcode.	No
`ppvStatus`	Boolean	Boolean to indicate whether the account has access to PPV services. This field was known as `isPPVEnabled` in SMSDomain-1.2 and earlier.	No
`rolloutProfileUID`	Long	The identifier of the rollout profile that should be used for this account. A rollout profile indicates what software versions should be rolled out to an account's open devices. Available from SMSDomain-1.3 and above.	Yes
`status`	String	The account status. One of: `ACTIVE` `CANCELLED` `INACTIVE` `RESTRICTED` `SUSPENDED` Only accounts that are active or restricted will be able to sign on to the system, therefore the status is largely irrelevant to a client UI application. For details see: Account and STB Status.	Yes
`title`	String	Account holder title.	No
`UID`	Integer	Unique account identifier within the SDP. Can be used to query other APIs in the SDP, but not against any other modules or systems.	Yes

Device

A device contains information about a client device. There are two types of device that have type-specific parameters as well as the device parameters; Set Top Box and Media Player. Most fields are optional and will be populated depending on the solution architecture.

Device parameters

This data structure represents a generic device.

Note that a Media Player or Set Top Box is an instance of a Device, and that the Media Player data model and Set Top Box data model extend the Device data model.

Name	Description	Always available
`accountUID`	The unique account identifier within the SDP. This identifier is not known externally to the SDP, so should only be used for SDP API calls. Account number should be used for account identification wherever possible.	Yes
`description`	Description of the device if available.	No
`deviceClassifierUID`	Unique identifier of the device classifier within the SDP. Can be used to retrieve the device classifier from the Device Classifier Service.	No
`deviceEnabled`	`true` if the device is enabled, otherwise `false`. The device will not be able to use the service if this is false, so should be true.	Yes
`deviceType`	The device type. Should be one of: `STB` – Set Top Box `MP` – Media Player	Yes
`drmInstanceName`	The name of the DRM system.	No
`name`	Device name.	No
`physicalAddress`	The current IP address of the device, if available.	No
`profileID`	Can be used to retrieve device profile information from the Profile Service.	No
`UID`	Unique device identifier within the SDP. Can be used to query other APIs in the SDP but not any other modules or systems.	Yes

STB parameters

This data structure provides the fields that classify a Set Top Box device.

Note that a Set Top Box is an instance of a Device, and that the Set Top Box data model extends the Device data model.

Name	Type	Description	Always available
`banned`	Boolean	If true, then this device is banned from using the system due to improper operation. Other devices in the account might be OK, and the account may otherwise be in perfectly good standing.	Yes
`caSN`	String (max 256 chars)	The Conditional Access Serial Number of the device CA chipset. Can be changed by a firmware change, but this isn't common, so can be used as a device identifier for signon.	No
`drmInstanceName`	String (max 320 chars)	Indicates which DRM the STB uses. Available from SMSDomain-1.3 and above.	No
`drmDeviceID`	String (max 50 chars)	DRM device ID. Available from SMSDomain-1.3 and above.	No
`externalGroupUID`	String	External group identifier.	No
`ipAddress`	String (max 20 chars)	The current IP address of the STB, if known and available.	No
`macAddress`	String (max 20 chars)	The MAC address of the STB.	No
`network`	String (max 256 chars)	A network identifier.	No
`nUID`	String (max 256 chars)	Uniquely identifies the device within a NAGRA STB deployment. Cannot be changed as it is hardwired in the hardware.	No
`port`	Integer	The port used for IP communication with the STB if needed.	No
`provisionId`	String	An optional ID that may be used during provisioning.	No
`provisionPwd`	String (max 10 chars)	An optional password that may be used to authenticate the Set Top Box during provisioning.	No
`serialNumber`	String (max 100 chars)	STB serial number.	No
`smartcardID`	String (max 100 chars)	The smartcard number. If the device is cardbased – it requires a physical smartcard – then this value is hardcoded on the smartcard itself. For a cardless device, this value is generated by the SDP, and paired to the device during provisioning. Can be used to retrieve the full smartcard data from the Smartcard service.	No
`smartcardType`	String (max 11 chars)	The smartcard type. One of: `CARDBASED` `CARDLESS` `UNSPECIFIED`	No
`status`	String	Device status. One of: `ACTIVE` `CANCELLED` `INACTIVE` `RESTRICTED` `SUSPENDED` If the device is cancelled, inactive, or suspended, then an end-user application should not be able to use it to query the API. For details see Account and STB Status.	Yes
`version`	String	The version of the software currently running on the device.	No

Media Player parameters

This data structure provides the fields that classify a Media Player (open) device.

Note that a Media Player is an instance of a Device, and that the Media Player data model extends the Device data model.

Name	Type	Description	Always available
`drmClientId`	String	The DRM client identifier.	No
`mediaPlayerId`	String	The identifer of the open device. Usually created by the DRM system during device initialisation.	Yes

Smartcard

The smartcard entity contains additional information regarding the smartcard, or in the case of a cardless CAS system, the Virtual Unique Address (VUA). Its details are not required by client applications.

Smartcard parameters

Name	Type	Description	Always available
`casInstanceId`	String (max 20 chars)	Identifies the CAS system that this smartcard belongs to.	Yes
`modificationDate`	dateTime	Date and time the smartcard was last modified.	No
`originId`	Integer	An identifier for the system which owns this smartcard. Identifiers up to 9999 are reserved for identifying systems pre-integrated with SDP. Operators can define their own meanings for values of 10000 and above.	No
`originKey`	String (max 20 chars)	The key or identifier that the system that owns this smartcard uses to identify it.	No
`smartcardID`	String (max 100 chars)	The smartcard number. If the device is cardbased – it requires a physical smartcard – then this value is hardcoded on the smartcard itself. For a cardless device, this value is generated by the SDP, and paired to the device during provisioning.	Yes
`status`	String	The status of the smartcard, one of: `AVAILABLE` – this smartcard is not allocated to an STB, so is available to be assigned. This status is only applicable in card-based systems. `UNAVAILABLE` – this smartcard is in use by an STB. `CANCELLED` – this smartcard has been cancelled and cannot be re-used.	Yes
`stbUid`	Long	Unique ID of the STB. Available from SMSDomain-1.3 and above.	No
`statusCode`	String	This returns the status of the smartcard. Allowed values are: `AVAILABLE`(A) `UNAVAILABLE`(U) `CANCELLED`(C) Available from SMSDomain-1.3 and above.	No

Access Point

An Access Point represents a logical grouping of Accounts that access the operator's service in the same manner. Access Points can be used to group Accounts by access method (for example, cable and IP clients), by geographical region, or by some other desirable sub-group of the subscriber base.

Typically, an Access Point is used to represent a geographical area or region, and in some cases also the edge of the network where Edge QAMs, Video servers, and other such equipment are located. When used to represent a region, the name of the access point is defined as the region name. This name should be used to filter content metadata to the region of the client device.

When used to represent the edge of the network, it can contain the addresses of the local servers such as video servers, which the client should connect to to obtain VOD. An Access Point can be associated with Device Groups that contain devices that represent the head-end devices that service that set of Accounts. This complex data representation is seldom used, however.

Access Point Object

Name	Type	Description	Localised	Always available
`creationDate`	Date	Access Point creation date.	No	Yes
`description`	String	Description.	No	No
`enabled`	Boolean	Access Point status. Should always be true otherwise signon will not function!	No	Yes
`exportID`	String	Identifier to use when exporting the data to a third party.	No	No
`modifiedDate`	Date	Last time the Access Point data was updated.	No	No
`name`	String	Usually the region name. If so, use this value as a region filter when communicating with metadata services.	No	Yes
`originID`	String	Source data system identifier.	No	No
`originKey`	String	Source data system key.	No	No
`publicAddrAPS`	String	Application server IP address. Clients can use this field to connect to a local application server.	No	No
`publicAddrSTS`	String	Streaming server IP address. The public IP address of the streaming video server.	No	No
`serviceProviderID`	String	Service Provider ID.	No	Yes
`uID`	Integer	SDP internal unique identifier for the access point.	No	Yes

Use Cases

The following sections describe three use cases.

Application initialisation

Once authentication is complete, it is usually necessary to retrieve some additional information about the device and its user, account, and access point to start the UI, as the information provided might be required to retrieve subscription data and content metadata. The key variables provided by the Context object should be persisted in memory for use with other requests.

Current context

To retrieve the current context for a device, send a GET request to:

CODE

https: //<server>:<port>/qsp/gateway/http/js/contextservice/getCurrentContext

Input

Parameter	Purpose	Type	Cardinality	Description	Required
`token`	token	string	1.1	Authentication token.	Yes

Output

The response is a Context object.

Data refresh

An application, especially one running on a Set Top Box, might be running for long periods of time without restarting. During that time, key data stored on the server might be updated. For example, the account status or the customer's subscription's might change. There is no mechanism for this information to be pushed to the device, therefore it is expected that the application periodically refreshes the data persisted in memory (for example, once an hour).

There are no additional APIs for data refresh; the same APIs should be used to retrieve the context and subscription data.

Retrieving access point details

To retrieve the access point for a device, send a GET request to:

CODE

https: //<server>:<port>/qsp/gateway/http/js/accesspointservice/getByUID

Input

Parameter	Purpose	Type	Cardinality	Description	Required
`arg0`	Access Point UID	string	1.1	Access Point UID (get it from Context).	Yes
`token`	token	string	1.1	Authentication token.	Yes

Output

The response is an Access Point object.

Summary

Data Models

Context

Account

Device

Smartcard

Access Point

Use Cases

Application initialisation

Current context

Input

Output

Data refresh

Retrieving access point details

Input

Output

See also