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 Customer Success 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
    • desktop-edge
    • fetchtv
    • ios-other
    • roku-7/8
    • smartphone-generic
    • tablet-android
    • tablet-kindle
    • roku-9
    • 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": [
        "{action_id}"
      ]
    }
  ],
  "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. Valid values:
  • akamai
  • cloudfront
  • fastly
  • jocdn
If you need to add a new value, contact customer support.
preferred_cdn_domain String Set the preferred CDN domain. This needs to match the hostname for your desired CDN.

For example: bcsomething-a.akamaized.net
video_codecs String Array of video codecs
audio_codecs String Array of audio codecs

API response for actions

Here is a sample response 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.