Device type profiling

This page was never published on the Drupal site.

This page explains how to work with the device type profiling feature that is described here.

Object model

The following class diagram shows the main objects that participate in the device type profiling feature.

The objects are as follows:

Device

This is the existing object that represents a device in SDP. It has been modified to include the DeviceInformation reported by the device. This means that a list of device features is available for device reporting.

DeviceProfile

A DeviceProfile is a container for:

A set of features.
The actual device type assigned to this DeviceProfile.

When a client device is assigned a given type, this is implemented by linking the Device object with the related DeviceProfile.

SDP is delivered with a default DeviceProfile with a single defined feature ({"OTT"}) and one DeviceType ("OTT").

A DeviceProfile can only be deleted if it is not referenced by any Device.

DeviceTypeList

This is the actual type of device. It is not a single value but a list, as MediaLive supports different device types for each target metadata type (OTT, BTV, nPVR).

The default DeviceTypeList is {"VOD": [ "OTT"], "BTV": [ "OTT"], "nPVR": ["OTT”] }.

DeviceInformation

This object is a list of key-value pairs that represent the features that characterise a device. It includes hardware features (manufacturer, CPUs, screen size and resolution, etc.) as well as software features (OS name and version, streaming capabilities, etc.).

The client application retrieves this information from the device platform where it is running (the MediaLive Secure Player includes an API to retrieve this information) and reports it to the MediaLive back-end as part of the initialise device workflow (in the form of a JSON string).

The parameter names and values are matched against a set of rules defined by the operator (see DeviceClassifier object below). This object, therefore, encapsulates a contract – existing parameter names cannot be changed or re-shuffled under a different structure otherwise existing rules could be broken.

Device Information data model

This is a JSON object with the following fields:

Object	Group	Parameter	Classifier	Type	Example values for desktop	Example values for Android	Example values for iOS
`device`	`hardware`	`type`	Mandatory	String	`desktop`	`handheld`	`handheld`
		`model`	Best effort	String	`Latitude 8600`	`Xperia T`	`iPad 4`
		`manufacturer`	Best effort	String	`Dell`	`Sony`	`Apple`
	`OS`	`type`	Mandatory	String	`Windows`	`Android`	`iOS`
		`version`	Mandatory	String	`XP`	`4.4.3`	`7.0`
	`CPU`	`cores`	Best effort	Integer	`2`	`2`	`2`
		`frequency`	Best effort, GHz	Float	`1.4`	`1.0`	`1.4`
		`neon`	Best effort	Boolean	`true`	`false`	`false`
	`GPU`	`cores`	Best effort	Integer	`2`	`1`	`1`
		`frequency`	Best effort, GHz	Float	`2.8`	`1.5`	`1.2`
	`screen`	`width`	Mandatory, pixels	Integer	`1920`	`2560`	`1080`
		`height`	Mandatory, pixels	Integer	`1200`	`1440`	`1920`
		`density`	Mandatory, dpi	Integer	`135`	`577`	`401`
`secureplayer`	`streamings`	`type`	Mandatory	String	`HLS`	`HLS`	`HLS`
	`codecs`	`type`	Mandatory	String	`H.264`	`H.264`	`H.264`
	`DRMs`	`type`	Mandatory	String	`PRM`	`PRM`	`PRM`

Example:

CODE

{ 
   "device":{ 
      "CPU":{ 
         "cores":4,
         "frequency":2.693000078201294
      },
      "GPU":{ 
         "cores":0,
         "frequency":0,
         "model":"Intel(R) HD Graphics Family"
      },
      "OS":{ 
         "type":"Windows",
         "version":"Windows 7 Enterprise"
      },
      "hardware":{ 
         "manufacturer":"Dell Inc.",
         "model":"Latitude E7440",
         "type":"Desktop"
      },
      "screen":{ 
         "density":0,
         "height":1200,
         "width":1920
      }
   },
   "securePlayer":{ 
      "DRMs":[ 
         "PRM"
      ],
      "codecs":[ 
         "H264"
      ],
      "streamings":[ 
         "HLS"
      ]
   }
}

DeviceClassifier

DeviceClassifier defines the way a device will be classified into a given type. This is done by defining a set of rules that is matched against the DeviceInformation reported by the device.

When all the rules in a DeviceClassifier match, the client device is assigned the DeviceProfile linked with that particular DeviceClassifier object.

If multiple DeviceClassifier objects match a device, the one with highest priority is used.

Old client apps that do not report DeviceInformation are classified based on the playerType, which is matched against DeviceClassifier's deviceKey (pre- ML2.8 behaviour).

Rules

A DeviceClassifier can contain one or more rules. If more that one rule is present, logical AND will be applied.

A rule is comprised of an operator, a key, and a value:

The key must match one of the parameter names in the DeviceInformation object.
The value is taken from the DeviceInformation object.
Supported operators are:
- Equal to – $eq
- Not equal to – $ne
- Less than – $lt
- Less than or equal to – $le
- Greater than – $gt
- Greater than or equal to – $ge
- Contains – $contains
- Does not contain – $not contains

Sample rules

Rule	Meaning
`[{operator:"$le",key:"screen.height",value:"1920"}]`	The screen height is 1920 pixels or less.
`[{operator:"$gt",key:"screen.width",value:"1080"}]`	The screen width is greater than 1080 pixels.
`[{operator:"$le",key:"screen.height",value:"1920"},` `{operator:"$gt",key:"screen.width",value:"1080"}]`	Combination of the two previous rules.
`[{"operator":"$eq","key":"OS.type","value":"iPhone OS"}]`	The device is an iOS device.

A special instance is the default DeviceClassifier that is delivered with SDP. It contains no rules. If the reported DeviceInformation does not match any of the existing DeviceClassifier objects, this default one is used.

The default DeviceClassifier is linked to the default DeviceProfile.

AccountProfile

Operators can use AccountProfile to define account templates and apply them to multiple accounts, which saves the effort of replicating the same data across every single account.

An AccountProfile can include:

Zero or more DeviceClassifierLimits, and therefore (indirectly) zero or more DeviceClassifier objects.
A global maximum number of active devices.
The total number of active devices across all the DeviceClasifierLimits cannot exceed this number.

DeviceClassifierLimit

A DeviceClassifierLimit is associated a with particular AccountProfile, and provides a single limit value for a particular DeviceClassifier.

Examples

The following diagram illustrates an example with two DeviceClassifier objects (one for iOS devices and one for Android devices), both linked to a common DeviceProfile ("OTT" device type). The AccountProfile applies limits of three Android devices, two iOS devices, and a maximum of four open devices in total. In addition, there are cable devices (DVB-C STBs) that are not limited.

SDP behavior and default configuration

MDS behavior and default configuration

MDS configuration

The MDS must be pre-configured with a list of device types. This is by ingesting an XML file that contains the device type definitions, as follows.

MDS device type definition

<DeviceProfile id="OTT" features="OTT"/>

where:

The value of the id attribute ("OTT" here) must match the "Name" in the SDP DeviceProfile object, and
The features must match the features defined in SDP for that DeviceProfile instance.

This file must be loaded in MDS before ingesting any CMS export file. For this reason this is called a "pre-ingest" file in MDS documentation.

After that, every time MDS ingests a new file from CMS, it assigns the DeviceProfile id in the file to each content version ("technical" in MDS API terms), where the set of features of the DeviceProfile is a super-set of the features of the content version.

Similarly, if a product definition in the CMS export file includes a list of features (through the "Platform" object), the MDS assigns it the list of DeviceProfiles whose features are a super-set of that of the product.

Filtering content and products

The client application can choose to filter by device type on the content, on the products, or on both.

Sample requests

Filter content by device type:

http://ott.nagra.com/latest/metadata/delivery/CMS4X/vod/editorials?filter={"technical.deviceType":"TABLET_CLEAR", "isVisible":true, "isValid":true}&fields=["technical.deviceType", "product.deviceType"]

Filter channels by device type:

http://ott.nagra.com/latest/metadata/delivery/CMS4X/btv/services?filter={"technical.deviceType":{"$in":["DASH"]}}&sort=[[%22Title%22,1]]&fields=[]

Filter products by device type:

http://ott.nagra.com/latest/metadata/delivery/CMS4X/vod/editorials?filter={"product.deviceType":"TABLET_CLEAR", "isVisible":true, "isValid":true}&fields=["technical.deviceType", "product.deviceType"]

Filter both content and products by device type:

http://ott.nagra.com/latest/metadata/delivery/CMS4X/vod/editorials?filter={"deviceType":"TABLET_CLEAR", "isVisible":true, "isValid":true}&fields=["technical.deviceType", "product.deviceType"]

Adding new device types to MDS

To add a new device type to MDS:

Define it in a pre-ingest file as shown above. Then copy it into the MDS ingest folder.
Then perform a full CMS export to force the MDS to re-categorise all content and products for the new device type.

Front-end interfaces

The following interfaces are exposed by SDP towards connecting devices (directly or via M-DRM callback).

Device initialisation

For both indirect and direct device initialisation modes, the existing APIs have been extended with one additional parameter. This is of type string and carries the DeviceInformation JSON object as defined above.

For indirect initialisation, use SDP's NMPS service initializeDevice (playerVersion, playerType, opaqueData, deviceInformation).
For direct initialisation, use SDP's MdrmService isDeviceAuthorised (mediaPlayerId, mediaPlayerType, deviceInformation).

Context Service

SDP's ContextService.getCurrentContext response has been extended to include the list of device types assigned by SDP to the device as part of the Context object.

Back-office interfaces

The following interfaces are exposed by SDP towards external SMS/CRM systems for device type provisioning.

Create a DeviceProfile

URL

http://<SDP_IP_port>/ws-gateway/gateway/ws/profileservice

Sample request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:prof="http://quative.tv/ProfileServiceNamespace">
   <soapenv:Header/>
   <soapenv:Body>
     <prof:create>
         <model>
            <originID></originID>
            <originKey></originKey>
            <serviceProviderID>1</serviceProviderID>  <!-- hardcoded value -->
            <enabled>1</enabled>
            <name>HLS</name>
            <type>DVC</type>
         </model>
      </prof:create>
   </soapenv:Body>
</soapenv:Envelope>

Delete a DeviceProfile

URL

http://<SDP_IP_port>/ws-gateway/gateway/ws/profileservice

Sample request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:prof="http://quative.tv/ProfileServiceNamespace">
   <soapenv:Header/>
   <soapenv:Body>
     <prof:delete>
         <model>
            <serviceProviderID>1</serviceProviderID>  <!-- hardcoded value -->
            <profileUID>75</profileUID>
         </model>
      </prof:delete>
   </soapenv:Body>
</soapenv:Envelope>

Add DeviceTypeList to a DeviceProfile

URL

http://<SDP_IP_port>/ws-gateway/gateway/ws/profileservice

Sample request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:prof="http://quative.tv/ProfileServiceNamespace">
   <soapenv:Header/>
   <soapenv:Body>
      <prof:addDeviceTypeToDvcProf>
         <profileUID>75</profileUID>
         <deviceTypeList>{"VOD":["CABLE"],"BTV":["CABLE"],"nPVR":["CABLE”]}</deviceTypeList>
      </prof:addDeviceTypeToDvcProf>
   </soapenv:Body>
</soapenv:Envelope>

Remove DeviceTypeList from a DeviceProfile

URL

http://<SDP_IP_port>/ws-gateway/gateway/ws/profileservice

Sample request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:prof="http://quative.tv/ProfileServiceNamespace">
   <soapenv:Header/>
   <soapenv:Body>
      <prof:removeDeviceTypeFromDvcProf>
         <profileUID>75</profileUID>
      </prof:removeDeviceTypeFromDvcProf>
   </soapenv:Body>
</soapenv:Envelope>

Add a Feature to a DeviceProfile

URL

http://<SDP_IP_port>/ws-gateway/gateway/ws/profileservice

Sample request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:prof="http://quative.tv/ProfileServiceNamespace">
   <soapenv:Header/>
   <soapenv:Body>
      <prof:addFeatureToDProf>
         <profileUID>75</profileUID>
         <featureUID>23</featureUID>
      </prof:addFeatureToDProf>
   </soapenv:Body>
</soapenv:Envelope>

Remove a Feature from a DeviceProfile

URL

http://<SDP_IP_port>/ws-gateway/gateway/ws/profileservice

Sample request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:prof="http://quative.tv/ProfileServiceNamespace">
   <soapenv:Header/>
   <soapenv:Body>
      <prof:removeFeatureToDProf>
         <profileUID>75</profileUID>
         <featureUID>23</featureUID>
      </prof:removeFeatureToDProf>
   </soapenv:Body>
</soapenv:Envelope>

Create a DeviceClassifier

URL

http://<SDP_IP_port>/ws-gateway/gateway/ws/deviceclassifierservice

Sample request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dev="http://quative.tv/DeviceClassifierServiceNamespace">
   <soapenv:Header/>
   <soapenv:Body>
      <dev:create>
         <model>
            <originKey>Win32</originKey>
            <deviceKey>Win32</deviceKey>
            <matchingOrder>20</matchingOrder>
            <name>Win32</name>
            <os>Win32</os>
         </model>
      </dev:create>
   </soapenv:Body>
</soapenv:Envelope>

Update a DeviceClassifier with rules

URL

http://<SDP_IP_port>/ws-gateway/gateway/ws/deviceclassifierservice

Sample request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dev="http://quative.tv/DeviceClassifierServiceNamespace">
   <soapenv:Header/>
   <soapenv:Body>
      <dev:update>
         <model>
            <modifiedDate>2015-05-20T14:42:50Z</modifiedDate>
            <originKey>Win32</originKey>
            <UID>2</UID>
            <deviceKey>Win32</deviceKey>
            <matchingOrder>20</matchingOrder>
            <name>Win32</name>
            <os>Win32</os>
            <rules>[{"operator":"$eq","key":"OS.type","value":"Windows"}]</rules>
            <profileID>51</profileID>
         </model>
      </dev:update>
   </soapenv:Body>
</soapenv:Envelope>

Delete a DeviceClassifier

URL

http://<SDP_IP_port>/ws-gateway/gateway/ws/deviceclassifierservice

Sample request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dev="http://quative.tv/DeviceClassifierServiceNamespace">
   <soapenv:Header/>
   <soapenv:Body>
      <dev:delete>
         <model>
            <UID>2</UID>
         </model>
      </dev:delete>
   </soapenv:Body>
</soapenv:Envelope>

Get the list of DeviceClassifier instances

URL

http://<SDP_IP_port>/ws-gateway/gateway/ws/deviceclassifierservice

Sample request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dev="http://quative.tv/DeviceClassifierServiceNamespace">
   <soapenv:Header/>
   <soapenv:Body>
      <dev:getList/>
   </soapenv:Body>
</soapenv:Envelope>

Create an AccountProfile

URL

http://<SDP_IP_port>/ws-gateway/gateway/ws/accountprofileservice

Sample request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:acc="http://quative.tv/AccountProfileServiceNamespace">
   <soapenv:Header/>
   <soapenv:Body>
      <acc:createAccountProfile>
         <enabled>true</enabled>
         <maxDevEnabled>true</maxDevEnabled>
         <maxDevAllowed>12</maxDevAllowed>
         <maxDevActivationEnabled>true</maxDevActivationEnabled>
         <maxDevActivationAllowed>3</maxDevActivationAllowed>
         <maxDevActivationWindow>24</maxDevActivationWindow>
         <maxSessionEnabled>true</maxSessionEnabled>
         <maxSessionAllowed>5</maxSessionAllowed>
 
         <!--Zero or more repetitions:-->         
         <deviceClassifierLimits>
            <accountProfileUid>1</accountProfileUid>
            <deviceClassifierUid>...</deviceClassifierUid>
            <maxDeviceClassifierLimit>4</maxDeviceClassifierLimit>
         </deviceClassifierLimits>
           
      </acc:createAccountProfile>
   </soapenv:Body>
</soapenv:Envelope>

Delete an AccountProfile

URL

http://<SDP_IP_port>/ws-gateway/gateway/ws/accountprofileservice

Sample request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dev="http://quative.tv/AccountProfileServiceNamespace">
   <soapenv:Header/>
   <soapenv:Body>
      <acc:deleteAccountProfile>
         <model>
            <apuid>23</apuid>
         </model>
      </acc:deleteAccountProfile>
   </soapenv:Body>
</soapenv:Envelope>

Update an AccountProfile with DeviceClassifierLimits

URL

http://<SDP_IP_port>/ws-gateway/gateway/ws/accountprofileservice

Sample request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:acc="http://quative.tv/AccountProfileServiceNamespace">
   <soapenv:Header/>
   <soapenv:Body>
      <acc:updateAccountProfile>
         <apuid>1</apuid>
         <enabled>true</enabled>
         <maxDevEnabled>true</maxDevEnabled>
         <maxDevAllowed>12</maxDevAllowed>
         <maxDevActivationEnabled>true</maxDevActivationEnabled>
         <maxDevActivationAllowed>3</maxDevActivationAllowed>
         <maxDevActivationWindow>24</maxDevActivationWindow>
         <maxSessionEnabled>true</maxSessionEnabled>
         <maxSessionAllowed>5</maxSessionAllowed>
 
         <!--Zero or more repetitions:--> 
         <deviceClassifierLimits>
            <deviceClassifierUid>2</deviceClassifierUid>
            <maxDeviceClassifierLimit>4</maxDeviceClassifierLimit>
         </deviceClassifierLimits>
         <deviceClassifierLimits>
            <deviceClassifierUid>4</deviceClassifierUid>
            <maxDeviceClassifierLimit>4</maxDeviceClassifierLimit>
         </deviceClassifierLimits>
         <deviceClassifierLimits>
            <deviceClassifierUid>6</deviceClassifierUid>
            <maxDeviceClassifierLimit>4</maxDeviceClassifierLimit>
         </deviceClassifierLimits>
           
      </acc:updateAccountProfile>
   </soapenv:Body>
</soapenv:Envelope>

Limitations and Constraints

Configuration is not centralised. The operator must define the device types twice: once in SDP and once in MDS.
MDS metadata delivery APIs – filtering of products by device type is only available for VOD products. This will be extended to live products in ML2.11.