Contact Support | System Status
Page Contents

    Implementing Device Limits

    In this topic, you will learn how to enable device limits for video playback using Brightcove Playback Restrictions.

    Introduction

    With Brightcove Playback Restrictions, you can set device limits for video playback. Each user's device is registered with a unique id when a DRM license request is made. You control the number of devices per user.

    The device limit is checked and enforced with each license request. To use this restriction, you will pass a JSON Web Token (JWT) with the current user id uid to the Playback API.

    If you are new to this feature, see the Overview: Brightcove Playback Restrictions document.

    Device registration

    A device is registered with Brightcove when a valid playback request which includes a JSON Web Token (JWT) with uid and dlimit claims is received. From that moment, this device will occupy one slot.

    JWT claims

    For device limits, you can use the following claims along with the generally required claims:

    • uid:

      The user id of the end viewer. This field is required for device registration.

    • dlimit:

      For DRM content, the dlimit claim indicates how many devices a user can stream. Every device from each user requesting a stream is registered. Once the stream limit is reached, no more devices will be able to stream.

      The dlimit claim lets you control how many devices can be associated with the specified user uid. The value must be > 0.

      If the dlimit claim value is dropped in later requests, previously allowed devices will continue to operate.

      Example
      If the dlimit value is set to 3, the user can play on devices A, B, & C (all would be allowed). Trying to play on device D would be denied.
      If the dlimit value is changed to 1, the user can still play on all 3 devices A, B, & C, unless the devices are manually revoked by managing devices with the Devices API. To do this, see the Manage devices section.

    Implementation

    To use device limits, follow these steps:

    1. Create a JSON Web Token (JWT) with the generally required claims along with the uid and dlimit claims.

      Each user's device is registered with a unique id when a DRM license request is made.

    2. Manage user devices with the Devices API. This API allows you to get the devices for a user, delete devices and update the name for a device.

      When a device is registered, it is identified by id and nickname. The Devices API lets you edit the device nickname, making it easy to manage your list of devices.

    3. Configure your player to use the JSON Web Token (JWT) created in the previous step.

    Manage devices

    You can manage user devices with the Devices API.

    Devices API

    With the Devices API, you can get and delete user devices.

    Base URL

    The base URL for the API is:

    https://playback-auth.api.brightcove.com/v1

    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://playback-auth.api.brightcove.com/v1/accounts/{accountID}

    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 Devices API must be made from client credentials with the following permissions:

    • video-cloud/playback-auth/devices/read
    • video-cloud/playback-auth/devices/write

    API methods

    The Devices API supports the following requests. For details, see the Devices API Reference.

    Get all user devices

    GET /v1/accounts/{accountID}/users/{userID}/devices
    Response body

    The response body contains an array of devices, and should look similar to this:

    [
        {
            "id": "12e12345-11e1-1bd1-d123-1234567890",
            "created_at": 1612646018,
            "updated_at": 1612646018,
            "name": "my device1",
            "user_agent": "PlayReadyClient"
        },
        {
            "id": "WVCf123456789abcdefghijkl1234567890abcdefg",
            "created_at": 1612385697,
            "updated_at": 1612385697,
            "name": "my device2",
            "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:85.0) Gecko/20100101 Firefox/85.0"
        }
    ]

    Update device name

    The PATCH request lets you set a descriptive name for the device.

    PATCH  /v1/accounts/{accountID}/users/{userID}/devices/{deviceID}
      Content-Type: application/json
      Body: {devices object}
    Request body

    The request body contains the device name.

    {
        "name": "my device1"
    }

    Here are the field details:

    Field Type Description
    name String A descriptive nickname to help identify the device

    Delete all user devices

    DELETE /v1/accounts/{accountID}/users/{userID}/devices

    Delete a specific user device

    DELETE /v1/accounts/{accountID}/users/{userID}/devices/{deviceID}


    Page last updated on 03 May 2021