Directed Migration

The page you are looking for doesn't live here anymore -- redirecting you to in 3 seconds.

In this topic, you will learn how to use the Directed Migration Framework to specify a Brightcove Player to be loaded instead of one or more Smart Players.

Overview

To use Directed Migration, you still must create a new Brightcove Player that has the customizations and plugins that match the behavior you want using the new APIs and plugins of the Brightcove Player. Directed Migration then allows you to load that new player in place of a Smart Player without making changes to the existing HTML page.

Using Directed Migration still requires careful consideration of the following topics:

  • Making sure appropriate renditions are available
  • Specifying and including 3rd-party and custom plugins
  • Testing with custom layouts

These issues are described in more detail in the Smart Player to Brightcove Player Migration Guide.

Directed Migration does not yet work with playlists. Also any interaction with the Smart Player API in your page will no longer function once the player is replaced.

Make sure to set the enable_mapping flag to false by default initially so you can test all your new customizations and plugins and make sure the new player behaves correctly in your site. Once you are satisfied that the mapped player works appropriately, you can set enable_mapping to true in the Directed Migration configuration file (named mappings.json) so all viewers will see it without a query parameter.

At a high level, to setup directed migration you will need to perform the following tasks:

  • Get prepared: There may be some technologies you need to understand, like cURL and JSON, before starting the process.
  • Enable basic authentication: Using basic authentication when setting up directed migration will greatly simplify the process. You can disable basic authentication after setting up directed migration if you so choose.
  • Gather required information: You will need identifiers for both the Smart Player and Brightcove Player used in the mapping.
  • Create mappings file: This is a specially formatted file that contains the information Brightcove will use to substitute a Brightcove Player for a Smart Player.
  • Publish mapping file: Places the file in a specific location on a Brightcove server.
  • Test: Of course, you will want to be sure that the mapping file is working correctly.

The steps in this document show a standard mapping. More options for mappings are shown in the Mapping options section of the document.

Get prepared

Setting up directed migration uses cURL statements in the terminal/command prompt. You will also work with files in JSON format. The following documents provide introductions to these technologies if you are not familiar with them (note that the links will open in new tabs/windows):

Enable basic authentication

The process for setting up directed migration will be much easier if you turn on basic authentication for the Player Management API.

To do this, follow these steps:

  1. Enter Studio.
  2. Select Admin > Player Settings
    select player settings
  3. If not already checked, click the checkbox for Enable Basic username and password authentication for access to the Player Management and Delivery System APIs.
    enable basic authentication
  4. Click Save.

Gather required information

You will need the Smart Player playerKey and the Brightcove Player ID.

To get the Smart Player information, examine the player code on your HTML page and copy the value for the playerKey. From the example shown below, the value to copy is AQ~~,AAABXxBZKsE~,AdU2xXeQoKBP-8tgJnkJv-czgxbjn_aR.

<!--
By use of this code snippet, I agree to the Brightcove Publisher T and C
found at https://accounts.brightcove.com/en/terms-and-conditions/.
-->

<script language="JavaScript" type="text/javascript" src="http://admin.brightcove.com/js/BrightcoveExperiences.js"></script>

<object id="myExperience3495887198001" class="BrightcoveExperience">
  <param name="bgcolor" value="#FFFFFF" />
  <param name="width" value="480" />
  <param name="height" value="270" />
  <param name="playerID" value="4861899758001" />
  <param name="playerKey" value="AQ~~,AAABXxBZKsE~,AdU2xXeQoKBP-8tgJnkJv-czgxbjn_aR" />
  <param name="isVid" value="true" />
  <param name="isUI" value="true" />
  <param name="dynamicStreaming" value="true" />

  <param name="@videoPlayer" value="3495887198001" />
</object>

<!--
This script tag will cause the Brightcove Players defined above it to be created as soon
as the line is read by the browser. If you wish to have the player instantiated only after
the rest of the HTML is processed and the page load is complete, remove the line.
-->
<script type="text/javascript">brightcove.createExperiences();</script>

<!-- End of Brightcove Player -->

Next you need the ID for the Brightcove Player you are going to substitute for the Smart Player. After you create the player you can get the ID from Studio. The player's ID is highlighted in the red box in the screenshot. From the example shown below, the value to copy is B13X2Aix.

get ID

Create mappings

You will create a file that sets up mappings between the Smart Player and Brightcove Player. The format of the file is JSON. The general format of the file is as follows:

{
  "actual_smart_player_playerKey":
  {
    "player_id": "actual_brightcove_player_ID"
  }
}

An actual mapping file, using the data gathered above, is as follows:

{
  "AQ~~,AAABXxBZKsE~,AdU2xXeQoKBP-8tgJnkJv-czgxbjn_aR":
    {
      "player_id": "B13X2Aix"
    }
}

If you have multiple mappings, the JSON would be formatted as follows:

{
  "AQ~~,AAABXxBZKsE~,AdU2xXeQoKBP-8tgJnkJv-czgxbjn_aR":
    {
      "player_id": "B13X2Aix"
    },
  "AQ~~,AAABXxBZKsE~,AdU2xXeQoKBoZQCUzYoB75P1OJYzHA13":
    {
      "player_id": "S1MStQ6x"
    }
}

Now that you know the format, go ahead and use an editor to create your JSON mappings. Although not required, it is probably a good idea and save the file as mappings.json for later reference. The location of where you save the file does not matter.

Publish mapping file

Now you will use cURL to publish the mappings you created. When you publish the mappings, they are saved in a location that Brightcove can use to do the appropriate substitutions. The following steps guide you through the process.

  1. Open Terminal (or a command prompt).
  2. Create environment variables for your email and account number. Follow the examples:
    export EMAIL=myname@mycompany.com
    
    export ACCOUNT_ID=1111222233334
  3. Update your account's repository to contain a migration repo. You will be prompted for your Brightcove password when running this cURL command.
    curl \
      --user $EMAIL \
      --request PUT \
      https://repos.api.brightcove.com/v1/accounts/$ACCOUNT_ID/repos/migration
  4. Check to be sure your response is similar to the following (of course your account number will be used):
    {
      "name": "migration",
      "public_url": "http://players.brightcove.net/1507807800001/migration",
      "repo_url": "https://repos.api.brightcove.com/v1/accounts/1507807800001/repos/migration"
    }
  5. Create a cURL statement similar to the following that places the contents of your mappings.json file in the migration repo. The JSON that defines your mappings is placed inside the single quotes in the --form contents='' line of your cURL statement. Note that the path for the file is files/mappings.json.
    curl \
      --user $EMAIL \
      --form contents='{
        "AQ~~,AAABXxBZKsE~,AdU2xXeQoKBP-8tgJnkJv-czgxbjn_aR":
          {
            "player_id": "B13X2Aix"
          },
        "AQ~~,AAABXxBZKsE~,AdU2xXeQoKBoZQCUzYoB75P1OJYzHA13":
          {
            "player_id": "S1MStQ6x"
          }
      }' \
      --request PUT \
      https://repos.api.brightcove.com/v1/accounts/$ACCOUNT_ID/repos/migration/files/mappings.json
  6. Check to be sure your response is similar to the following:
    {
      "name": "mappings.json",
      "public_url": "http://players.brightcove.net/1507807800001/migration/mappings.json"
    }
  7. Confirm the file was moved correctly.
    curl http://players.brightcove.net/$ACCOUNT_ID/migration/mappings.json
  8. You should see the content of your mappings.json file displayed. If this is not your initial upload, caching issues may delay seeing your change. See the NOTE under the Test section below for details.

Test

Testing is simple because you don't have to change anything, which is the whole reason behind directed migration. Simply browse your page that contains a Smart Player which you have mapped to a Brightcove Player and see the new player.

Smart Player

smart player

Brightcove Player

Brightcove Player

Mapping options

There are some situations where a more complex mappings must be created. They are detailed here.

enable_mapping

You can set up your mapping(s) in disabled mode. This allows the directed migration to be in place, but the Smart Player to be displayed unless you include enableMapping=true in your page URL request. This way you can test in place before all users see the change.

{
  "AQ~~,AAAAdgygTQk~,askjqjthqgdasj":
    {
      "player_id": "A43G3gs3",
      "enable_mapping": false
    }
}

smart_player_id

In early years of the Smart Player, the Javascript embed did not initially include a player key, although eventually all players did get a playerKey. You can specify a smart_player_id in the mapping. The smart_player_id is not required and only used if you find it helpful in tracking the mappings.

{
  "AQ~~,AAAAdgygTQk~,askjqjthqgdasj":
    {
      "smart_player_id": "123123123",
      "player_id": "A43G3gs3"
    }
}

Related Topics