Using Once UX Advertising on an AMP Page

Product(s)
Brightcove Player
SSAI
Role(s)
Player Developer
Topic(s)
Advertising
Type
Support Doc

In this topic, you will learn how to use Accelerated Mobile Pages (AMP) with the Once UX advertising plugin.

Overview

This document details the steps needed to use Once UX technology (server-side ad insertion) with AMP and Brightcove Player (non-Video Cloud customer version, although if you are a Video Cloud customer the steps are the same). The broad steps are listed here, then detailed in the rest of the document:

  1. Configure your Once UX implementation. You will need at least a metadataUri. For details on Once UX see the Brightcove Once UX Implementation Guide.
  2. Create the JavaScript needed to correctly play the Once UX asset using a custom Brightcove Player plugin.
  3. Add the Once UX plugin and the custom plugin to the player configuration using Studio.
  4. Use the configured player in an AMP page.

Sample

The following is a sample AMP HTML page that uses Brightcove Player to display a Once UX asset. The player functions normally, so the HTML is the interesting part of this sample. The code is examined later in this document.

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

Plugin code examination

The way AMP functions is that the amp-brightcove component creates an iframe implementation of the Brightcove Player. In the amp-brightcove component you can pass a custom attribute which will contain the value for the Once UX asset. The plugin reads and uses the value with the Once UX plugin. In the URL for the iframe will be the custom attribute, as shown here (the URL shown is NOT a Once UX metadataUri, for brevity's sake):

      <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 24-35: 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 9: Use JavaScript's decodeURIComponent() method to get a valid URL for the video.
  • Lines 11-13: Creates an object for use when calling the Once UX plugin.
  • Line 15: Calls the Once UX plugin using the options object.
videojs.registerPlugin('lift', function () {
  var myPlayer = this,
    options = {},
    encodedVideoQueryParam,
    decodedVideoQueryParam;
  // Retrieve the query string from Brightcove Player src attribute in the iframe
  encodedVideoQueryParam = getQuerystring('videoUrl');
  // Remove the URLenceded formatting
  decodedVideoQueryParam = decodeURIComponent(encodedVideoQueryParam);
  // Create an options object to pass to the Once UX plugin
  options = {
    "metadataUri": decodedVideoQueryParam
  };
  // Call the Once UX plugin passing the options object
  myPlayer.onceux(options);

  // Helper function to get value from specified query parameter
  /*
   * 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];
    }
  }
});

Configure the player

You need to add the Once UX plugin and the custom plugin described in the previous section to the player. Note that for the Once UX plugin you will just add the URLs to the JavaScript and CSS and NOT specify the plugin name, as you do that in the plugin. (The plugin's URLs for JavaScript and CSS can be copied from the Advertising with the Once UX Plugin document.) For the custom plugin, you will specify the JavaScript URL (no CSS needed), and the name defined in the plugin code, in this instance lift.

The following screenshot shows the configuration done in Studio:

AMP iframe source

The lift plugin was added as a plugin, of course. The JavaScript file containing the custom plugin was added using the Add a File button.

This screenshot shows the player configuration as displayed by looking at the config.json of the player:

AMP iframe source

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 for the Once UX metadataUri. Remember that since the name will be retrieved from an iframe's src URL, the name will be videoUrl.
  • 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="S1VV8j3Zdf"
      layout="responsive"
      data-param-video-url="https://onceux.unicornmedia.com/now/ads/vmap/od/auto/c8860df3-6695-44f7-a405-ed3634148b85/2a501e22-792f-4348-ad6c-3e48020b199a/725cba9b-a821-47af-ba5b-677d115c4dcf/content.once"
      data-video-id
      width="16" height="9">
    </amp-brightcove>
  </div>


</body>
</html>

You have completed the steps necessary to use the Once UX plugin with AMP and Brightcove Player.