Overview
Cross-device resume lets viewers start watching a video on one device, and at a later time, continue watching the video where they left off on a different device.
Because the Cross-Device Resume (XDR) API cannot be called from your client-side apps, you will need to create a server-side proxy to make the call and return the playback position value.
Getting playback position
You can get the viewer playback position with the Cross-Device Resume (XDR) API.
Cross-Device Resume (XDR) API
With the Cross-Device Resume API, you can get all the playhead positions for a specific viewer, or all the playheads for a specific viewer and video.
Base URL
The base URL for the API is:
https://data.brightcove.com/v1/xdr
Account path
In all cases, requests will be made for a specific Video Cloud Account. So, you will always add the term accounts followed by your account id to the base URL:
https://data.brightcove.com/v1/xdr/accounts/
Authorization
An access token for requests is required and must be present in the Authorization header:
Authorization: Bearer {access_token}
The access token is a temporary OAuth2 access token that must be obtained from the Brightcove OAuth service. For details on how to obtain client credentials and use them to retrieve access tokens, see the Brightcove OAuth Overview.
Permissions
Requests to the Cross-Device Resume API must be made from client credentials with the following permissions:
-
video-cloud/xdr/read
Note that these permissions are not yet available in the Studio Admin UI. Until they are, you can use this Brightcove Learning Services app to create your client credentials. Just be sure to check the video-cloud/xdr/read
box when you create the credentials (you can check as many other boxes as you like).
API methods
The Cross-Device Resume API supports the following requests. For details, see the Cross-Device Resume (XDR) API Reference.
Get viewer playheads
This request gets all of the playheads for a viewer.
GET /accounts/{accountID}/playheads/{viewer_id}
Response body
The response body contains an array of videos and playheads. It should look similar to this:
{
"account_id": "1752604059001",
"viewer_id": "viewer001",
"items": [
{
"timestamp": 1589548991563000,
"video_id": "6152436480001",
"playhead_seconds": 17
},
{
"timestamp": 1589548858719000,
"video_id": "6152440604001",
"playhead_seconds": 3
}
],
"size": 2
}
Get viewer video playheads
This request gets all of the playheads for a viewer and a specific video.
GET /accounts//playheads/{viewer_id}/
Response body
If you specify one video ID, the response body will contain one item object. When you specify more than one video ID, than the items
array will contain multiple item objects. It should look similar to this:
{
"account_id": "1752604059001",
"viewer_id": "viewer001",
"items": [
{
"timestamp": 1589896539910000,
"video_id": "6156696074001",
"playhead_seconds": 39
}
],
"size": 1
}
Using a server-side proxy
A proxy is a server-side application that acts as in intermediary between your client-side application and the REST API. Here are some helpful links:
- For concepts, see Learning Guide: Using the REST APIs
- For a web player sample that calls a server-side proxy to get the playhead from the XDR API, see the Cross-Device Resume sample on github (this repo also contains a copy of the sample proxy written in PHP).