AMP Using an External Video

In this topic, you will learn how Accelerated Mobile Pages (AMP) can be used with Brightcove Player and an external, non-Video Cloud video.

Overview

Accelerated Mobile Pages is a Google project that aims to enable "the creation of websites and ads that are consistently fast, beautiful and high-performing across devices and distribution platforms." You can use Brightcove Player with AMP because the project includes an amp-brightcove component which allows publishers to embed Brightcove Players within AMP HTML documents. This example uses a custom plugin that accepts a URL to an external (non-video cloud) video passed to it via the amp-brightcove component using the custom data-param-video-url attribute.

Sample

The following is a sample AMP HTML page that includes a Brightcove Player. The player functions normally, so the HTML is the interesting part of this sample. The HTML code is examined later in this document.

See the Pen AMP-Brightcove Player-External Video by Brightcove Learning Services (@rcrooks1969) on CodePen.

Resources from AMP

The AMP project developed a special amp-brightcove component that displays the Brightcove Player. The component is detailed in the amp-brightcove document.

AMP provides an example amp-brightcove implementation with details in the following documents:

Player configuration

Brightcove supplies a plugin to enhance the use of AMP with Brightcove Player. The plugin adds support for AMP's video interface API which enables some advanced features:

  • Integration with amp-analytics: Allows tracking of views to third party analytics against the AMP page domain.
  • Integration with amp-bind: Playback can be controlled by other elements in the AMP page.

Players without the plugin still work in AMP, but without that functionality.

Plugin installation

As with all Brightcove Player plugins, you need the plugin's name and URL to the plugin's JavaScript, which are provided here (no CSS file is necessary for this plugin's use):

Plugin name

  ampSupport

JavaScript URL

  //players.brightcove.net/videojs-amp-support/1/videojs-amp-support.js

HTML page code examination

The HTML page code from the CodePen sample above is shown below (plugin code is detailed in the next section). A complete explanation of the code is provided by AMP in the documents linked to above. In the following list are a few tricks/traps to be aware of:

  • Line 14: You can add a single style tag, but it must include the amp-custom attribute.
  • Line 26: DO NOT beautify the code. The boilerplate CSS is needed as supplied by AMP.
  • Line 42: The URL to the external video is passed here. Remember that since the name will be retrieved from an iframe's src URL, the name will be videoUrl.
  • Line 43: The data-video-id must be present, but is not assigned a value when using an external video.
  • Line 44: The width and height attributes determine the aspect ratio of the player embedded in responsive layouts.
  <!--
    ## Introduction
  
    The `amp-brightcove` component allows embedding a Brightcove
    [Video Cloud](https://www.brightcove.com/en/online-video-platform) or
    [Perform](https://www.brightcove.com/en/perform) player.
  -->
  <!-- -->
  <!doctype html>
  <html ⚡>
  <head>
    <meta charset="utf-8">
    <title>amp-brightcove</title>
    <style amp-custom>
      .player-container {
        width: 640px;
        height: 360px;
      }
    </style>
    <script async src="https://cdn.ampproject.org/v0.js"></script>
    <!-- ## Setup -->
    <!-- Import the Brightcove component in the header. -->
    <script async custom-element="amp-brightcove" src="https://cdn.ampproject.org/v0/amp-brightcove-0.1.js"></script>
    <meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1">
    <link rel="canonical" href="https://ampbyexample.com/components/amp-brightcove/">
    <style amp-boilerplate>body{-webkit-animation:-amp-start 8s steps(1,end) 0s 1 normal both;-moz-animation:-amp-start 8s steps(1,end) 0s 1 normal both;-ms-animation:-amp-start 8s steps(1,end) 0s 1 normal both;animation:-amp-start 8s steps(1,end) 0s 1 normal both}@-webkit-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@-moz-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@-ms-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@-o-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}</style><noscript><style amp-boilerplate>body{-webkit-animation:none;-moz-animation:none;-ms-animation:none;animation:none}</style></noscript>
  
  
  </head>
  <body>
  
    <!-- ## Basic Usage -->
    <!--
      A responsive brightcove video. The required data is `data-account` and `data-video-id`. Other
      supported parameters are `data-player-id`, `data-embed` and `data-playlist-id`.
    -->
    <div class="player-container">
      <amp-brightcove
        data-account="3676484087001"
        data-player-id="ByrhJWAPf"
        layout="responsive"
        data-param-video-url="//solutions.brightcove.com/bcls/videos/calm-day-oregon-coast.mp4"
        data-video-id
        width="16" height="9">
      </amp-brightcove>
    </div>
  
  
  </body>
  </html>

Plugin code examination

The way AMP functions is that the amp-brightcove component creates an iframe implementation of the Brightcove Player. In the URL for the iframe will be the custom attribute, as shown here:

  <iframe frameborder="0" allowfullscreen="true" src="https://players.brightcove.net/3676484087001/ByrhJWAPf_default/index.html?videoUrl=%2F%2Fsolutions.brightcove.com%2Fbcls%2Fvideos%2Fcalm-day-oregon-coast.mp4"; class="i-amphtml-fill-content" kwframeid="1"></iframe>

If you scroll over in the iframe code, you will see the query string shown here:

AMP iframe source

Notice that the query string name is videoUrl. Also note that the URL has been URL encoded. Both of these issues will reflected in the plugin code, shown here:

  • Lines 21-38: A helper function that finds the value associated with a query string, passed to the function as a parameter.
  • Line 7: Retrieve the value of the videoUrl query string using the helper function.
  • Line 8: Use JavaScript's decodeURIComponent() method to get a valid URL for the video.
  • Lines 11-14: Use the decoded URL and place the video in the player. If you are going to use formats of video other than MP4, you would either need to pass the correct type value, or write logic to read the video's extension and assign the correct value.
  • Lines 17-19: Of course not required, but if you want the video to play on startup you could use this code.
  videojs.registerPlugin('ampPassVideo', function() {
    var myPlayer = this,
      encodedVideoQueryParam,
      decodedVideoQueryParam;
  
    // Get the query string and un-URL encode it
    encodedVideoQueryParam = getQuerystring('videoUrl');
    decodedVideoQueryParam = decodeURIComponent(encodedVideoQueryParam);
  
    // Load the video into the player
    myPlayer.src({
      'type': 'video/mp4',
      'src': decodedVideoQueryParam
    });
  
    // On loadedmetadata event, play the video
    myPlayer.on('loadedmetadata', function(){
      myPlayer.play();
    });
  
    /*
     * usage: foo = getQuerystring("bctid", null);
     * foo will be equal to value of query param bctid
     * note that the default_ parameter is what you will get back
     * if the key isn’t found
     */
    function getQuerystring(key, default_) {
      var regex, qs;
      if (default_ == null) default_ = "";
      key = key.replace(/[\[]/, "\\\[").replace(/[\]]/, "\\\]");
      regex = new RegExp("[\\?&]" + key + "=([^&#]*)");
      qs = regex.exec(window.location.href);
      if (qs === null) {
        return default_;
      } else {
        return qs[1];
      }
    }
  });

You would assign this plugin to your player either using Studio or the Player Management API.

Features

Although discussed in the AMP documentation, a few features are highlighted here that are of special importance:

Custom parameters

You may want to pass additional information through to your player for your plugins to access. You can do this by adding extra attributes on the amp-brightcove element that must be named data-param-*, where * is the name of your property.

The parameters are passed through as camel cased attribute names appended to the player URL. Keys and values are URL encoded. For example:

  • data-param-language="de" becomes &language=de
  • data-param-ad-vars="key:val;key2:val2" becomes &adVars=key%3Aval%3Bkey2%3Aval2

External referrer support

Brightcove Player v6.25.0+ supports setting an arbitrary referrer on an iframe. The AMP component now supports passing through its own referrer to the player, by adding a referrer="EXTERNAL_REFERRER" attribute their amp-brightcove embed.

EXTERNAL_REFERRER is AMP's own macro - see https://github.com/ampproject/amphtml/blob/19135a3aac7813a9ff263a9f863fe35aeb316582/spec/amp-var-substitutions.md#external-referrer for further information.

AMP Analytics

An amp-analytics component can be used in an AMP document to track data to any arbitrary analytics. If publishers wish to include video events they can now do so.

AMP's doc on the AMP Analytics syntax (which is cumbersome) is here: https://www.ampproject.org/docs/reference/components/amp-analytics. And specifically video analytics: https://github.com/ampproject/amphtml/blob/master/extensions/amp-analytics/amp-video-analytics.md.

An example is available, tracking to example.com so you'll see the beacons as errors in the network tab: http://solutions.brightcove.com/bclifford/ampexamples/analytics.html.

AMP Bind

AMP Bind is AMP's API for interacting between components. At a basic level, it allows you to have something external to the player to control playback. For example, the following code would play a video, where myPlayer is the id of the amp-brightcove player.

    <button on="tap:myPlayer.play">Play</button>

AMP doesn't trust video events so you can't currently do something more useful, like acting on a video end. An example of this is available here: http://solutions.brightcove.com/bclifford/ampexamples/bind.html.

Autoplay

A warning may appear in the browser console if you use autoplay:

This error will appear if you use any autoplay option within the Brightcove Player configuration. "autoplay" must be set to false or be absent from the player configuration for the warning not to appear. AMP rules require that players in AMP only start playback if initiated by a user action or by AMP-managed autoplay, which can be set by adding the autoplay attribute to the amp-brightcove element. Brightcove recommends using a dedicated player for AMP pages without the autoplay setting within the player configuration if autoplay is required.