Skip to main content
Skip table of contents

Client reporting

Summary

Client reporting covers any type of data sent from the client device to the server for reporting purposes. This can include the following:

User activity, for example:

  • Watched a VOD content.
  • Watched a channel for X minutes.
  • Searched for keyword X.
  • Recorded a content item.
  • Created a series recording.

Error reporting, for example:

  • Playback failed.
  • Application failed to properly load.
  • External content failed to download.

Session metrics, for example:

  • Signon time.
  • Uptime.
  • Software version.
  • Session length.

The OpenTV Platform does not enforce any specific reporting to be used. It must be agreed when defining the solution architecture what information should be supplied by the client application (and how often), and how it should be reported to the service provider. The OpenTV Platform's role is to simply collect the data sent to it in a format that is easily reported.

Two services exist in the OpenTV Platform that have somewhat overlapping responsibilities. The SDP's Content Consumption service enables a client to report actions associated with content consumption. For example, content playback attempts, success and failure. This can then be reported by the SDP to the service provider via a CSV report.  

The Content Discovery Gateway (acting as a proxy to the User Activity Vault) can be used to report any client actions. Currently, the CDG supports integration with recommendation engines so that consumption activity can be reported to the recommendation engine to improve the recommendations.

Data models

Data models returned in response to activity requests

The data models that are returned in response to activity requests from CDG are JSON objects as follow:

Activity data model

This is a JSON object with the following fields:

Name
Type
Description
Always present
accountIdStringThe ID of the account making the report of an action.Yes
deviceIdStringThe ID of the device from which the report action originated.No
idStringThe universally unique ID of the action.No
keyStringThe key of the action, for example, the contentId of a watch action.Yes
metadataMap [String,String]

A map of additional useful metadata, for example,

{"channel":"bbc one","programme":"eastenders"}.

No
nameStringThe category of the report action, for example, watch, recordActivity, or rate.No
timestampISO dateThe timestamp of the action. If none was provided, now() is used.No
userIdStringThe ID of the user that belongs to the given account, who is reporting the action.No
valueStringThe value of the action, for example, WATCH FULL or WATCH PARTIAL.Yes

Example

JS 
{
    "id":"6fb9f0e0-967e-11e4-8196-f7b9520b3e0c",
    "accountId":"234521354",
    "userId":"",
    "deviceId":"abc345"
    "name":"rating",
    "key":"LYS24680",
    "value":"WATCH FULL",
    "timestamp":"2015-01-07T15:04:11Z",
    "metadata":{"Title":"Spinal Tap"}
}

11 reads

Data models used in user activity requests

The data models used in user activity requests to CDG are JSON objects as detailed below:

User Activity Request data model

This is a JSON object with the following fields:

Name
Type
Description
Required
contentIdStringThe content ID that was the subject of the activity.Yes
dataTypeString

The type of content. One of:

  • btv
  • vod
Yes
deviceTypeString

The type of device. One of:

  • settopbox
  • mediaplayer
Yes
timestampISO dateThe time of the activity.No (defaults to system time)

Example

JS 
{
    "dataType":"vod",
    "deviceType":"SetTopBox",
    "contentId":"TDLA0100000088341751",
    "timestamp":"2014-07-25T12:20:02.000Z"
}

11 reads

Delete Activity Request data model

This is a JSON object with the following fields:

Name
Type
Description
Required
deviceTypeString

The type of device. One of:

  • settopbox
  • mediaplayer
Yes

Example

JS 
{
    "deviceType":"settopbox",
}

Use cases

Report account activity to CDG

Account activities are reported to CDG by submitting a HTTP POST request to an appropriate URL using the following parameters:

Account Activity Submit parameters

These are the HTTP query parameters available when reporting account activity to CDG

Name
Parameter Type
Data Type
Description
Required
tokenHeaderStringThe authentication token of the user.Y
accountIdPathStringThe accountId of the requester.Y

BodyUserActivityRequest (JSON payload)The activity details.Y

When reporting at account level the account number and activity type are submitted as part of the URL.

In the example below, the client is reporting that account ACC1234 has performed activity WATCH on VOD content LYS2468:

CODE 
POST http://contentdiscovery/v1/useractivity/WATCH/account/ACC1234
Content-Type: application/json
 
{"dataType":"vod","deviceType":"SetTopBox","contentId":"LYS2468","timestamp":"2014-07-25T12:20:02.000Z"}

Report user activity to CDG

User activities are reported to CDG by submitting a HTTP POST request to an appropriate URL using the following parameters:

User Activity Submit parameters

hese are the HTTP query parameters available when reporting user activity to CDG.

Name
Parameter Type
Data Type
Description
Required
tokenHeaderStringThe authentication token of the user.Y
accountIdPathStringThe accountId of the requester.Y
userIdPathStringThe user belonging to the requester's account.Y

BodyUserActivityRequest (JSON payload)The activity details.Y

When reporting at user level the account number, user ID, and activity type are submitted as part of the URL.

In the example below, the client is reporting that user USR9876 belonging to account ACC1234 has performed activity WATCH on VOD content LYS2468:

CODE 
POST http://contentdiscovery/v1/useractivity/WATCH/account/ACC1234/user/USR9876
Content-Type: application/json
 
{"dataType":"vod","deviceType":"SetTopBox","contentId":"LYS2468","timestamp":"2014-07-25T12:20:02.000Z"}

Retrieve account activity from CDG

Account activities are requested from CDG by submitting a HTTP GET request to an appropriate URL using the following parameters:

Account Activity Request parameters

These are the HTTP query parameters available when requesting account activity from CDG.

Name
Parameter Type
Data Type
Description
Required
tokenHeaderStringthe authentication token of the userY
accountIdPathStringthe accountId of the requesterY

When querying at account level the account number and activity type are submitted as part of the URL.

In the example below, the client is requesting all WATCH activities recorded for account ACC1234:

CODE 
GET http://contentdiscovery/v1/useractivity/WATCH/account/ACC1234

Response example:


CODE 
 {"activities":[
        {"id":"6fb9f0e0-967e-11e4-8196-f7b9520b3e0c","accountId":"234521354","userId":"USR2468","name":"WATCH","key":"LYS2345","value":"234521354","timestamp":"2015-01-07T15:04:11Z","metadata":{"Title":"Spinal Tap"}},
        {"id":"ce88bf90-9686-11e4-8196-f7b9520b3e0c","accountId":"234521354","userId":"USR2468","name":"WATCH","key":"LYS2346","value":"234521354","timestamp":"2015-01-07T16:04:06Z","metadata":{"Title":"Goodfellas"}},
        {"id":"f27f2380-9686-11e4-8196-f7b9520b3e0c","accountId":"234521354","userId":"USR1234","name":"WATCH","key":"LYS2347","value":"234521354","timestamp":"2015-01-07T16:05:06Z","metadata":{"Title":"Star Wars"}}
    ],
"totalRecords":3}

Retrieve user activity from CDG

User activities are requested from CDG by submitting a HTTP GET request to an appropriate URL using the following parameters:

User Activity Request parameters

These are the HTTP query parameters available when requesting user activity from CDG.

Name
Parameter Type
Data Type
Description
Required
tokenHeaderStringThe authentication token of the user.Y
accountIdPathStringThe accountId of the requester.Y
userIdPathStringThe user belonging to the requester's account.Y

When querying at user level the account number, user ID, and activity type are submitted as part of the URL.

In the example below, the client is requesting all WATCH activities recorded for user USR2468 that belongs to account ACC1234:

CODE 
GET http://contentdiscovery/v1/useractivity/WATCH/account/ACC1234/user/USR2468

Response example:


CODE 
  {"activities":[
        {"id":"6fb9f0e0-967e-11e4-8196-f7b9520b3e0c","accountId":"234521354","userId":"USR2468","name":"WATCH","key":"LYS2345","value":"234521354","timestamp":"2015-01-07T15:04:11Z","metadata":{"Title":"Spinal Tap"}},
        {"id":"ce88bf90-9686-11e4-8196-f7b9520b3e0c","accountId":"234521354","userId":"USR2468","name":"WATCH","key":"LYS2346","value":"234521354","timestamp":"2015-01-07T16:04:06Z","metadata":{"Title":"Goodfellas"}}
    ],
"totalRecords":2}

Delete account activity from CDG

To delete account activity an HTTP DELETE request must be submitted to an appropriate URL using the following parameters:

Delete Account/User Activity Parameters

These are the HTTP query parameters available when deleting activity from CDG.

Name
Parameter Type
Data Type
Description
Required
tokenheaderStringThe authentication token of the user.Y 
accountIdPathStringThe accountId of the requester.Y 
userIdPathStringThe user belonging to the requester's account.Y (for user-based deletes)
deleteActivityRequestDeleteActivityRequestString (JSON)Details of the delete request.Y 

When querying at account level the account number is submitted as part of the URL.

In the example below the client is requesting that all activities recorded by account ACC1234 be deleted:

CODE 
DELETE http://contentdiscovery/v1/useractivity/account/ACC1234?deleteActivityRequest={"deviceType":"MediaPLayer"}

See also

The full SDP API documentation.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close