Contact Support | System Status
Page Contents

    Implementing Delivery Rules

    In this topic, you will learn how to implement Brightcove's Delivery Rules, which enable you to customize how your media is delivered to meet your business objectives.

    Overview

    Publishers often need to modify the content characteristics of their media manifests for both technical and business reasons. To meet these needs, Brightcove has created a framework where rules can be applied that will modify the contents of the manifest returned from Dynamic Delivery.

    Delivery Rules are made up of conditions and actions.

    • Conditions - "If" conditions that trigger a certain action
    • Actions - "Then" parameters that define how the manifest is modified

    For more details about Delivery Rules, see the following:

    Account setup

    Contact your account manager to learn about pricing and enable this feature for your account.

    Applying rules

    The following flow diagram shows how delivery rules are applied.

    Delivery rules applied
    Delivery rules applied

    Conditions

    The "if" conditions, supported in the first phase include the following:

    • Explicit Request - A configuration ID is the id of an action that you have created. You will use this id to pass to the Playback API at runtime. This id is mapped to configuration values that allow underlying services to make decisions leveraged by the Playback API to return the appropriate response data.

    • Device Group - Device type as detected by user-agent parsing. The groups currently supported include:
      • android
      • appletv
      • chromecast
      • ipad
      • iphone
      • desktop-chrome
      • desktop-firefox
      • desktop-safari
      • fetchtv
      • ios-other
      • roku-7/8
      • smartphone-generic
      • tablet-android
      • tablet-kindle
      • unknown
       
    • Geography - Physical location of the requesting device:
      • Continent
      • Country

    Actions

    The actions, or "then" parameters, supported in the first phase include the following:

    • Media Delivery CDN - From the CDNs configured for use within a given Dynamic Delivery account, the CDN to use for delivery of media segments.

    • Rendition Characteristics - Filters based on characteristics of the underlying media renditions. These include:
      • Minimum video bitrate
      • Maximum video bitrate
      • Minimum video resolution
      • Maximum video resolution
      • Maximum number of audio renditions
      • Maximum number of video renditions
      • First video bitrate
      • Discontinuities

    Scope

    Actions can be applied at two levels:

    • Account - Actions that apply to all requests made to a specific customer's account
    • Specific Request - Actions that are invoked on a specific request

    Actions will be applied in the order listed above. Later actions will override earlier ones.

    Defining rules

    Use the Delivery Rules API to customize media delivery.

    Delivery Rules API

    The Delivery Rules API allows you to define conditions and actions to control your media delivery.

    The response from the Delivery Rules API contains a conditions array. This array allows you to create multiple if / then conditions where each then points to one or more action ids.

    Even though there are no methods to add or delete conditions, you can do this by updating the conditions array.

    Base URL

    The base URL for the API is:

    https://delivery-rules.api.brightcove.com

    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://delivery-rules.api.brightcove.com/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 Playback Rights API must be made from client credentials with the following permissions:

    • video-cloud/delivery-rules/read
    • video-cloud/delivery-rules/all

    Manage rules

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

    Get Delivery Rules

    Use the following GET request to fetch the latest version of Delivery Rules for an account.

    GET /accounts/{accountID}
    API Response

    Here is the response body. Notice that Delivery Rules contain a set of conditions and a set of actions.

    {
      "conditions": [
        {
          "name": "MyCondition1",
          "if": {
            "device_group": [
              "ipad"
            ],
            "request_country": [
              "string"
            ],
            "request_continent": [
              "AF"
            ]
          },
          "then": [
            "MyAction1"
          ]
        }
      ],
      "actions": [
        {
          "id": "44c91a1d-71f1-40b4-b9cf-3abcd12345",
          "properties": {
            "min_video_bitrate": 0,
            "max_video_bitrate": 0,
            "first_video_bitrate": 0,
            "min_video_resolution": "string",
            "max_video_resolution": "string",
            "max_video_renditions": 0,
            "max_audio_renditions": 0,
            "preferred_cdn_provider": "string",
            "preferred_cdn_domain": "string",
          "video_codecs": [
            "string"
          ],
          "audio_codecs": [
            "string"
          ]
        }
        }
      ]
    }

    Get Conditions

    Use the following GET request to fetch the conditions for an account.

    GET /accounts/{accountID}/conditions
    API response

    Here is the response body.

    [
      {
        "name": "MyCondition1",
        "if": {
          "device_group": [
            "ipad"
          ],
          "request_country": [
            "string"
          ],
          "request_continent": [
            "AF"
          ]
        },
        "then": [
          "44c91a1d-71f1-40b4-b9cf-3abcd12345"
        ]
      }
    ]

    Update Conditions

    Use the following PUT request to update the conditions for an account.

    PUT /accounts/{accountID}/conditions
      Content-Type: application/json
      Authorization: Bearer {access_token}
      Body: {conditions object}
    

    Request body for conditions

    Here is the request body for conditions. Notice that this is an array of condition objects.

    [
      {
        "name": "MyCondition1",
        "if": {
          "device_group": [
            "ipad"
          ],
          "request_country": [
            "string"
          ],
          "request_continent": [
            "AF"
          ]
        },
        "then": [
          "44c91a1d-71f1-40b4-b9cf-3abcd12345"
        ]
      }
    ]

    Here are the field details for conditions:

    Field Type Description
    name String Unique identifier for the condition
    device_group String Array of device types as detected by user-agent parsing
    request_country String Array of two letter country codes
    request_continent String Array of two letter continent codes
    then String Unique identifier for the associated action

    Create an action

    Use the following POST request to create actions for an account.

    POST /accounts/{accountID}/actions
      Content-Type: application/json
      Authorization: Bearer {access_token}
      Body: {actions object}
    

    Request body for actions

    Here is the request body for actions.

    {
        "properties": {
          "min_video_bitrate": 0,
          "max_video_bitrate": 0,
          "first_video_bitrate": 0,
          "min_video_resolution": "string",
          "max_video_resolution": "string",
          "max_video_renditions": 0,
          "max_audio_renditions": 0,
          "preferred_cdn_provider": "string",
          "preferred_cdn_domain": "string",
          "video_codecs": [
            "string"
          ],
          "audio_codecs": [
            "string"
          ]
      }
    }

    Here are the field details for actions:

    Field Type Description
    properties Object An object of defined properties for a specific action
    min_video_bitrate,
    max_video_bitrate
    Integer Set the minimum or maximum allowed video bitrate (kbps)
    first_video_bitrate Integer Set the bitrate for the first video (kbps)
    min_video_resolution,
    max_video_resolution
    String Set the minimum or maximum allowed video resolution (WxH)
    max_video_renditions Integer Set the maximum number of video renditions
    max_audio_renditions Integer Set the maximum number of audio renditions
    preferred_cdn_provider String Set the preferred CDN provider
    preferred_cdn_domain String Set the preferred CDN domain
    video_codecs String Array of video codecs
    audio_codecs String Array of audio codecs

    API response for actions

    Here is the request body for actions.

    {
        "id": "44c91a1d-71f1-40b4-b9cf-3abcd12345",
        "properties": {
          "min_video_bitrate": 0,
          "max_video_bitrate": 0,
          "first_video_bitrate": 0,
          "min_video_resolution": "string",
          "max_video_resolution": "string",
          "max_video_renditions": 0,
          "max_audio_renditions": 0,
          "preferred_cdn_provider": "string",
          "preferred_cdn_domain": "string",
          "video_codecs": [
           "string"
          ],
          "audio_codecs": [
           "string"
          ]
      }
    }

    In addition to the actions fields in the request, the API response includes the following generated field:

    Field Type Description
    id String A system generated unique identifier for the action. This is the actionID used in the update and delete methods.

    Get Actions

    Use the following GET request to fetch the actions for an account.

    GET /accounts/{accountID}/actions
    API Response

    See the API response for actions.

    Get an Action

    Use the following GET request to fetch a specific action for an account.

    GET /accounts/{accountID}/actions/{actionID}
    API Response

    See the API response for actions.

    Update an Action

    Use the following PUT request to update an action for an account.

    PUT /accounts/{accountID}/actions/{actionID}
      Content-Type: application/json
      Authorization: Bearer {access_token}
      Body: {actions object}
    
    API Request

    Here is a sample request body to update actions.

    {
      "id": "44c91a1d-71f1-40b4-b9cf-3edb94645943",
      "properties": {
       "custom_properties": {
        "generate_thumbnails": false,
        "hls_iframes": true
       }
      }
     }
    API Response

    Here is a sample response for updated actions.

    {
      "id": "44c91a1d-71f1-40b4-b9cf-3edb94645943",
      "properties": {
       "custom_properties": {
        "generate_thumbnails": false,
        "hls_iframes": true
       }
      }
     }

    Delete an Action

    Use the following DELETE request to remove an action for an account.

    DELETE /accounts/{accountID}/actions/{actionID}

    Limitations

    There are a few known limitations when using Delivery Rules:

    • Media Content - Delivery Rules will not work with Smooth or pMP4 videos.
    • Media Content - Delivery Rules will not work with live videos.
    • Audio Only - Delivery Rules with Server-Side Ads (SSAI) enabled require both video and audio content. This is an SSAI restriction.

    Page last updated on 13 Jul 2021