Merge pull request ampproject#1909 from BrightcoveOS/amp-brightcove-p…

…arams

amp-brightcove - pass custom params and allow `data-player`

ads/integration-guide.md

@@ -51,7 +51,7 @@ A brightcove player can be invoked by the following:
 <amp-brightcove
       data-account="906043040001"
       data-video-id="1401169490001"
-      data-player-id="180a5658-8be8-4f33-8eba-d562ab41b40c"
+      data-player="180a5658-8be8-4f33-8eba-d562ab41b40c"
       layout="responsive" width="480" height="270">
   </amp-brightcove>
 ```

examples/brightcove.amp.html

@@ -16,7 +16,7 @@ <h2>Brightcove Player</h2>
   <amp-brightcove
       data-account="906043040001"
       data-video-id="1401169490001"
-      data-player-id="180a5658-8be8-4f33-8eba-d562ab41b40c"
+      data-player="180a5658-8be8-4f33-8eba-d562ab41b40c"
       layout="responsive" width="480" height="270">
   </amp-brightcove>
 

extensions/amp-brightcove/0.1/amp-brightcove.js

@@ -16,7 +16,8 @@
 
 import {isLayoutSizeDefined} from '../../../src/layout';
 import {loadPromise} from '../../../src/event-helper';
-
+import {addParamsToUrl} from '../../../src/url';
+import {dashToCamelCase} from '../../../src/string';
 
 class AmpBrightcove extends AMP.BaseElement {
 
@@ -38,17 +39,33 @@ class AmpBrightcove extends AMP.BaseElement {
         this.element.getAttribute('data-account'),
         'The data-account attribute is required for <amp-brightcove> %s',
         this.element);
-    const playerid = (this.element.getAttribute('data-player-id') || 'default');
+    const playerid = (this.element.getAttribute('data-player') ||
+      this.element.getAttribute('data-player-id') ||
+      'default');
     const embed = (this.element.getAttribute('data-embed') || 'default');
     const iframe = document.createElement('iframe');
-    let src = 'https://players.brightcove.net/' + encodeURIComponent(account) + '/' + encodeURIComponent(playerid) + '_' + encodeURIComponent(embed) + '/index.html';
+    let src = `https://players.brightcove.net/${encodeURIComponent(account)}/${encodeURIComponent(playerid)}_${encodeURIComponent(embed)}/index.html`;
+    const params = {};
+
     if (this.element.getAttribute('data-playlist-id')) {
       src += '?playlistId=';
       src += this.encodeId_(this.element.getAttribute('data-playlist-id'));
     } else if (this.element.getAttribute('data-video-id')) {
       src += '?videoId=';
       src += this.encodeId_(this.element.getAttribute('data-video-id'));
     }
+
+    // Pass through data-param-* attributes as params for plugin use
+    for (let i = 0; i < this.element.attributes.length; i++) {
+      const attr = this.element.attributes[i];
+      const matches = attr.nodeName.match(/^data-param-(.+)/);
+      if (matches) {
+        const param = dashToCamelCase(matches[1]);
+        params[param] = attr.nodeValue;
+      }
+    }
+
+    src = addParamsToUrl(src, params);
     iframe.setAttribute('frameborder', '0');
     iframe.setAttribute('allowfullscreen', 'true');
     iframe.src = src;
@@ -66,7 +83,7 @@ class AmpBrightcove extends AMP.BaseElement {
     /* id is either a Brightcove-assigned id, or a customer-generated reference id.
       reference ids are prefixed 'ref:' and the colon must be preserved unencoded */
     if (id.substring(0,4) === 'ref:') {
-      return 'ref:' + encodeURIComponent(id.substring(4));
+      return `ref:${encodeURIComponent(id.substring(4))}`;
     } else {
       return encodeURIComponent(id);
     }

extensions/amp-brightcove/0.1/test/test-amp-brightcove.js

@@ -17,20 +17,20 @@
 import {createIframePromise} from '../../../../testing/iframe';
 require('../amp-brightcove');
 import {adopt} from '../../../../src/runtime';
+import {parseUrl} from '../../../../src/url';
 
 adopt(window);
 
 describe('amp-brightcove', () => {
 
-  function getBrightcove(accountId, videoId, opt_responsive) {
+  function getBrightcove(attributes, opt_responsive) {
     return createIframePromise().then(iframe => {
       const bc = iframe.doc.createElement('amp-brightcove');
-      bc.setAttribute('data-account', accountId);
+      for (const key in attributes) {
+        bc.setAttribute(key, attributes[key]);
+      }
       bc.setAttribute('width', '111');
       bc.setAttribute('height', '222');
-      if (videoId) {
-        bc.setAttribute('data-video-id', videoId);
-      }
       if (opt_responsive) {
         bc.setAttribute('layout', 'responsive');
       }
@@ -41,7 +41,10 @@ describe('amp-brightcove', () => {
   }
 
   it('renders', () => {
-    return getBrightcove('906043040001','ref:ampdemo').then(bc => {
+    return getBrightcove({
+      'data-account': '906043040001',
+      'data-video-id': 'ref:ampdemo'
+    }).then(bc => {
       const iframe = bc.querySelector('iframe');
       expect(iframe).to.not.be.null;
       expect(iframe.tagName).to.equal('IFRAME');
@@ -53,15 +56,30 @@ describe('amp-brightcove', () => {
   });
 
   it('renders responsively', () => {
-    return getBrightcove('906043040001', 'ref:ampdemo', true).then(bc => {
+    return getBrightcove({
+      'data-account': '906043040001',
+      'data-video-id': 'ref:ampdemo'
+    }, true).then(bc => {
       const iframe = bc.querySelector('iframe');
       expect(iframe).to.not.be.null;
       expect(iframe.className).to.match(/-amp-fill-content/);
     });
   });
 
   it('requires data-account', () => {
-    return getBrightcove('').should.eventually.be.rejectedWith(
+    return getBrightcove({}).should.eventually.be.rejectedWith(
         /The data-account attribute is required for/);
   });
+
+  it('should pass data-param-* attributes to the iframe src', () => {
+    return getBrightcove({
+      'data-account': '906043040001',
+      'data-video-id': 'ref:ampdemo',
+      'data-param-my-param': 'hello world'
+    }).then(bc => {
+      const iframe = bc.querySelector('iframe');
+      const params = parseUrl(iframe.src).search.split('&');
+      expect(params).to.contain('myParam=hello%20world');
+    });
+  });
 });

extensions/amp-brightcove/amp-brightcove.md

@@ -16,13 +16,13 @@ limitations under the License.
 
 ### <a name="amp-brightcove"></a> `amp-brightcove`
 
-An `amp-brightcove` component displays a Brightcove [Video Cloud](https://www.brightcove.com/en/online-video-platform) or [Perform](https://www.brightcove.com/en/perform) player.
+An `amp-brightcove` component displays the Brightcove Player as used in Brightcove's [Video Cloud](https://www.brightcove.com/en/online-video-platform) or [Perform](https://www.brightcove.com/en/perform) products.
 
 Example:
 ```html
 <amp-brightcove
     data-account="12345"
-    data-player-id="default"
+    data-player="default"
     data-embed="default"
     data-video-id="1234"
     layout="responsive"
@@ -36,11 +36,13 @@ The width and height will determine the aspect ratio of the player embed in resp
 
 **data-account**
 
-The Brightcove Video Cloud or Perform account id
+The Brightcove Video Cloud or Perform account id.
 
-**data-player-id**
+**data-player** or **data-player-id**
 
-The Brightcove player id. This is a GUID or "default". The default value is "default".
+The Brightcove player id. This is a GUID, shortid or "default". The default value is "default".
+
+`data-player` is preferred. `data-player-id` is also supported for backwards-compatibility.
 
 **data-embed**
 
@@ -49,12 +51,23 @@ The Brightcove player id. This is a GUID or "default". The default value and mos
 **data-video-id**
 
 The Video Cloud video id. Most Video Cloud players will need this.
-This is not used for Perform players.
+
+This is not used for Perform players by default; use it if you have added a plugin that expects a `videoId` param in the query string.
 
 **data-playlist-id**
 
 The Video Cloud playlist id. For AMP HTML uses a video id will normally be used instead. If both a playlist and a video are specified, the playlist takes precedence.
-This is not used for Perform players.
+
+This is not used for Perform players by default; use it if you have added a plugin that expects a `playlistId` param in the query string.
+
+**data-param-***
+
+All `data-param-*` attributes will be added as query parameter to the player iframe src. This may be used to pass custom values through to player plugins, such as ad parameters or video ids for Perform players.
+
+Keys and values will be URI encoded. Keys will be camel cased.
+
+- `data-param-language="de"` becomes `&language=de`
+- `data-param-custom-ad-data="key:value;key2:value2"` becomes `&customAdData=key%3Avalue%3Bkey2%3Avalue2`
 
 #### Player configuration