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 Contextobject 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.acquireSecureChallengeand 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 Featurein 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 Featurein 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.
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:
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:
