Getting Playback Position from XDR API

In this topic, you will learn the how to retrieve the viewer's playback position from the Cross-Device Resume (XDR) API.

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.

Send viewer id - Brightcove player

Requirements

The following requirements are needed for the Viewer ID Tracking:

  • Brightcove Player v7.18.0 or newer

First, you need to set the user identifier to store that user's viewing activity.

Brightcove Player

If you are using Brightcove Player, follow these steps:

  1. Even though viewer data is sent to Brightcove analytics automatically, you need to set the user identifier. To do this, use the user() method. For example: 

    myPlayer.bcAnalytics.client.user('viewer id');

    On your websites that host Brightcove Player, you can use an authentication gateway or some identity management solution to keep track of viewers. Use this viewer id as the viewer identifier to pass to Brightcove analytics.

  2. It is important to set the viewer id before any source is set on the player. It should be called immediately after initializing the player. 

    <video-js
  id="myPlayerID"
  data-account="1752604059001"
  data-player="hyQW6GByl"
  data-embed="default"
  controls=""
  data-video-id="6156696074001"
  data-playlist-id=""
  data-application-id=""
  width="640" height="360"></video-js>
<script src="https://players.brightcove.net/1752604059001/hyQW6GByl_default/index.min.js"></script>

<script>
  videojs.getPlayer('myPlayerID').ready(function() {
    var myPlayer = this;

    // Set the viewer id for Brightcove analytics
    myPlayer.bcAnalytics.client.user('viewer id');
  });
</script>
  3. When the user() method is used, the value is not hashed and will be sent in the clear with all subsequent beacons.

    Note that the player_init event will not include the user field in this case, but all video_* events should include it.

Custom player

If you are building a custom implementation that does not use Brightcove Player, add the user parameter to your Data Collection API requests. For details, see the Overview: Data Collection API v2 document.

You can use an authentication gateway or an identity management solution to track viewers on the sites that host your player. Use this viewer ID as the viewer identifier to pass to Brightcove analytics.

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/{{account_id}}

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/{{account_id}}/playheads/{viewer_id}/{{video_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: