Step-by-Step: Delivery System API

This document provides a hands-on introduction to using the Delivery System API to create a repository (repo), and in the repo you will save and update a plugin.

Overview

Here are the steps you will perform:

  • Create a repo using the Delivery System API
  • Create a local folder for file storage
  • Create a plugin and copy it to the repo
  • Alter the player to use the new plugin
  • Alter the plugin and observe the player uses the altered plugin

Note: If you are an experienced Git user you will see some of the API calls perform equivalent functionality you can also do in Git. In fact, some of the file manipulation API calls simply perform Git commands.

Prerequisites

To start these step by step instructions, it is assumed you have completed the Step-by-Step: Player Management. By completing said activity you have defined the following environment variables in your command line system:

  • {account_id}
  • $EMAIL
  • {player_id}

Create repo

You will now use the Delivery System API to create a repo and copy files to that repo. Once the repo is created you can also use the API to list repos, show details of a repo, delete repos, etc., but in many workflows this is not necessary.

In a curl statement to create the new repo you will use an HTTP PUT method and include the name of the new repo in the URL. Execute this curl statement to create a repo named firstRepo.

        curl \
          --user $EMAIL \
          --request PUT \
          https://repos.api.brightcove.com/v1/accounts/{{account_id}}/repos/firstRepo

You will receive a response confirming repo creation. The response will show: the name and public URL to the repo.

  • name: Name of the repo
  • public_url: The public URL to the repo
  • repo_url: The repository URL
        {
          "name": "firstRepo",
          "public_url": "https://players.brightcove.net/1507807800001/firstRepo",
          "repo_url": "https://repos.api.brightcove.com/v1/accounts/1507807800001/repos/firstRepo"
          }

Create folder

Next you need to create a folder locally on your machine for storage of the files associated with your Brightcove Player. In a location of your choice create the folder and then move (cd) into that folder.

        mkdir firstRepo
          cd firstRepo

Create plugin

Now you will create a plugin in your folder to copy to the repo. Use the same plugin from the Step-by-Step: Player Management, except change the text displayed. Create the file, paste the text from below into the file, then save it. Use the same file name as used in the Step-by-Step: Player Management, first-plugin.js.

      videojs.registerPlugin('firstPlugin', function() {
        var player = this,
        overlay = document.createElement('p');
        overlay.className = 'vjs-overlay';
        overlay.innerHTML = "NEW TEXT!";
        player.el().appendChild(overlay);
        });

You will now copy the newly created plugin file to the repo. Use the following cURL statement to perform this task.

      curl \
        --user $EMAIL \
        --form contents=@first-plugin.js \
        --request PUT \
        https://repos.api.brightcove.com/v1/accounts/{{account_id}}/repos/firstRepo/files/first-plugin.js

After the copy, you should see a confirmation similar to the following:

      {
        "name": "first-plugin.js",
        "public_url": "https://players.brightcove.net/1507807800001/firstRepo/first-plugin.js"
        }

You can confirm the file was copied correctly by viewing its contents using the following cURL statement.

      curl
        https://players.brightcove.net/{{account_id}}/firstRepo/first-plugin.js

You can also view the file by browsing the public_url returned from the file copy.

Use new plugin

In the Step-by-Step: Player Management you used a curl statement to tell the player the location of the JavaScript code for the plugin, along with the CSS location and plugin name. You will do the same again, except this time the path to the plugin will use the new path found in the response from the file copy (shown in line 2 above in the copy response). Execute the following curl statement to point to the new plugin location.

        curl \
          --header "Content-Type: application/json" \
          --user $EMAIL \
          --request PATCH \
          --data '{
          "scripts": [
          "https://players.brightcove.net/{{account_id}}/firstRepo/first-plugin.js"
          ],
          "stylesheets": [
          "https://solutions.brightcove.com/bcls/video-js/new-player/first-plugin.css"
          ],
          "plugins": [{
          "name": "firstPlugin"
          }]
          }' \
          https://players.api.brightcove.com/v2/accounts/{{account_id}}/players/{{player_id}}/configuration

Use the returned preview_url to browse the player and you will see the new text from the plugin displayed. If you choose, you can also publish the player and get the published player URL.

Alter plugin

One of the strengths of using the new Brightcove player is the ease in updating players by making a single change to a plugin, and all players using that plugin will be updated. In this point in the steps you will make a small change to the plugin and see it in use without making any changes to the player itself.

Open the first-plugin.js file and update the text to read NEWer Text!

        overlay.innerHTML = "NEWer TEXT!";

Again copy the file to the repo.

        curl \
          --user $EMAIL \
          --form contents=@first-plugin.js \
          --request PUT \
          https://repos.api.brightcove.com/v1/accounts/{{account_id}}/repos/firstRepo/files/first-plugin.js

Browse the same preview_url from above again. Note: Because of browser caching you may need to close the browser tab, and browse again, or even clear the browser's cache to see the text updated.

Once you see the latest version of the plugin functioning, you can then publish your player.

Python sample

Below is some Python code for pushing files to the Delivery System - this code is offered as an example and is not supported by Brightcove.

# Repo Upload Test
        import requests

        # test values
        pub_id = "{{account_id}}"
        client_id = "{{client_id}}"
        client_secret = "{{client_secret}}"
        access_token_url = "https://oauth.brightcove.com/v4/access_token"
        file_name = "port_test.js"
        repo_name = "js"

        # create the access token
        def get_access_token():
        access_token = None
        r = requests.post(access_token_url, params="grant_type=client_credentials", auth=(client_id, client_secret),
        verify=True)
        if r.status_code == 200:
        access_token = r.json().get('access_token')
        # print(access_token)
        return access_token


        # Upload to Repo function
        # Returns response from API
        def upload_to_repo():
        access_token = get_access_token()
        headers = {'Authorization': 'Bearer ' + access_token}
        url =
        "https://repos.api.brightcove.com/v1/accounts/{pubid}/repos/{repname}/files/{filename}".format(pubid=pub_id,
        repname=repo_name,
        filename=file_name)
        file = {"contents": ("port-test.js", open('port-test.js', "rb"))}
        r = requests.request("PUT", url, headers=headers, files=file)
        response = r.json()
        return response


        # Upload to the repo
        result = upload_to_repo()
        print(result)