User Viewing History API

The API provides the ability to retrieve and delete viewing history for a given user and subprofile.

📘 See Reference: Post player events for more details on how to post player events.

Fetch viewing history

GET viewing history for a single asset

You can fetch the viewing history for a single asset. The result contains progress and completed history, if any.

curl -X GET \
'https://{tenant}.viewing-history.{domain}/api/v1/viewinghistory/{assetId}'\
-H "Accept: application/json" \
-H "Authorization: Bearer {jwtToken}" \
-H "X-Vimond-Subprofile: {subprofileToken}"

where tenant and domain are specific to a customer installation and assetId is the id of the asset which has a request for viewing history.

Request parameter

Request parameter	Description
skipOlderThan	Threshold offset to filter out old results. The value must be a valid ISO8061 period for example P1Y for skipping results older than 1 year. Default to P1M (1 month)

Response codes

Response Code	Description
200 Ok	Asset’ viewing history retrieved successfully
401 Unauthorised	Missing or invalid authentication token
404 Not Found	No viewing history found for the user (and subprofile) for this asset

Sample response

{
  "data": [
      {
        "assetId": "22",
        "totalTime": "PT1H30M20S",
        "categoryId": "57",
        "progress": {
             "position": "PT10S",
             "date": "2018-07-10T15:02:05.102Z",
             "updateTime": "2018-07-10T15:02:05.102Z"
         },
        "completed": {
             "dates": [
              "2018-07-10T15:03:28.385Z"
            ],
            "viewCount": 1,
            "updateTime": "2018-07-10T15:03:29.939Z"
         }
      }
  ]
}

Fetch the whole viewing history

The following endpoint allows to fetch the whole viewing history restricted for the user and subprofile making the request.

curl -X GET \
'https://{tenant}.viewing-history.{domain}/api/v1/viewinghistory/all'\
-H "Accept: application/json" \
-H "Authorization: Bearer {jwtToken}" \
-H "X-Vimond-Subprofile: {subprofileToken}"

where tenant and domain are specific to a customer installation and assetId is the id of the asset which has a request for viewing history.

Request parameters

Request Parameter	Description
skipOlderThan	Threshold offset to filter out old results. The value must be a valid ISO8061 period for example P1Y for skipping results older than 1 year. Default to P1M (1 month)
maxResults	Limit the number of results to return to the client. Default to 10

Response codes

Response Code	Description
200 Ok	Viewing history retrieved successfully
401 Unauthorised	Missing or invalid authentication token

Sample response

{
    "data": [
        {
            "assetId": "785",
            "totalTime": "PT1H15M30S",
            "categoryId": "999",
            "progress": {
                "position": "PT1H",
                "date": "2018-07-11T12:03:07.170Z",
                "updateTime": "2018-07-11T12:03:07.170Z"
            }
        },
        {
            "assetId": "12",
            "totalTime": "PT35M36S",
            "categoryId": "532",
            "progress": {
                "position": "PT20M",
                "date": "2018-07-11T12:03:50.639Z",
                "updateTime": "2018-07-11T12:03:50.639Z"
            }
        },
        {
            "assetId": "14",
            "totalTime": "PT2H10M20S",
            "categoryId": "999",
            "progress": {
                "position": "PT20S",
                "date": "2018-07-11T12:04:35.930Z",
                "updateTime": "2018-07-11T12:04:35.930Z"
            },
            "completed": {
                "dates": [
                    "2018-07-11T12:02:41.233Z"
                ],
                "viewCount": 1,
                "updateTime": "2018-07-11T12:02:43.491Z"
            }
        }
    ]
}

GET progress viewing history

The following endpoint allows to fetch the progress viewing history restricted for the user and subprofile making the request.

curl -X GET \
'https://{tenant}.viewing-history.{domain}/api/v1/viewinghistory/progress'\
-H "Accept: application/json" \
-H "Authorization: Bearer {jwtToken}" \
-H "X-Vimond-Subprofile: {subprofileToken}"

where tenant and domain are specific to a customer installation and assetId is the id of the asset which has a request for viewing history.

Request parameters

Request Parameter	Description
skipOlderThan	Threshold offset to filter out old results. The value must be a valid ISO8061 period for example P1Y for skipping results older than 1 year. Default to P1M (1 month)
maxResults	Limit the number of results to return to the client. Default to 10

Response codes

Response Code	Description
200 Ok	Progress viewing history retrieved successfully
401 Unauthorised	Missing or invalid authentication token

Sample response

{
    "data": [
        {
            "assetId": "785",
            "totalTime": "PT1H15M30S",
            "categoryId": "999",
            "progress": {
                "position": "PT1H",
                "date": "2018-07-11T12:03:07.170Z",
                "updateTime": "2018-07-11T12:03:07.170Z"
            }
        },
        {
            "assetId": "12",
            "totalTime": "PT35M36S",
            "categoryId": "532",
            "progress": {
                "position": "PT20M",
                "date": "2018-07-11T12:03:50.639Z",
                "updateTime": "2018-07-11T12:03:50.639Z"
            }
        },
        {
            "assetId": "14",
            "totalTime": "PT2H10M20S",
            "categoryId": "999",
            "progress": {
                "position": "PT20S",
                "date": "2018-07-11T12:04:35.930Z",
                "updateTime": "2018-07-11T12:04:35.930Z"
            }
        }
    ]
}

GET completed viewing history

The following endpoint allows to fetch the completed viewing history restricted for the user and subprofile making the request.

curl -X GET \
'https://{tenant}.viewing-history.{domain}/api/v1/viewinghistory/completed'\
-H "Accept: application/json" \
-H "Authorization: Bearer {jwtToken}" \
-H "X-Vimond-Subprofile: {subprofileToken}"

where tenant and domain are specific to a customer installation and assetId is the id of the asset which has a request for viewing history.

Request parameters

Request parameter	Description
skipOlderThan	Threshold offset to filter out old results. The value must be a valid ISO8061 period for example P1Y for skipping results older than 1 year. Default to P1M (1 month)
maxResults	Limit the number of results to return to the client. Default to 10

Response codes

Response code	Description
200 Ok	Completed viewing history retrieved successfully
401 Unauthorised	Missing or invalid authentication token

Sample response

{
    "data": [
        {
            "assetId": "14",
            "totalTime": "PT2H10M20S",
            "categoryId": "999",
            "completed": {
                "dates": [
                    "2018-07-11T12:02:41.233Z"
                ],
                "viewCount": 1,
                "updateTime": "2018-07-11T12:02:43.491Z"
            }
        }
    ]
}

📘 Restrict user viewing history to a category

The previous endpoints can be modified to restrict the results to a specific category. The endpoints are:

• /api/v1/viewinghistory/all/{categoryId}
• /api/v1/viewinghistory/progress/{categoryId}
• /api/v1/viewinghistory/completed/{categoryId}

Delete viewing history

DELETE viewing history for a single asset

The following endpoint allows to delete an asset viewing history restricted for the user and subprofile making the request. The endpoint deletes both progress and completed viewing history

curl -X DELETE \
'https://{tenant}.viewing-history.{domain}/api/v1/viewinghistory/{assetId}'\
-H "Authorization: Bearer {jwtToken}" \
-H "X-Vimond-Subprofile: {subprofileToken}"

where tenant and domain are specific to a customer installation and assetId is the id of the asset which has a request for viewing history.

Response codes

Response Code	Description
202 Accepted	The server accepted the deletion request and it is going to execute it
401 Unauthorised	Missing or invalid authentication token

DELETE whole viewing history

The following endpoint allows to delete the whole viewing history restricted for the user and subprofile making the request. The endpoint deletes both progress and completed viewing history

curl -X DELETE \
'https://{tenant}.viewing-history.{domain}/api/v1/viewinghistory'\
-H "Authorization: Bearer {jwtToken}" \
-H "X-Vimond-Subprofile: {subprofileToken}"

where tenant and domain are specific to a customer installation and assetId is the id of the asset which has a request for viewing history.

Response codes

Response Code	Description
202 Accepted	The server accepted the deletion request and it is going to execute it
401 Unauthorised	Missing or invalid authentication token