Track Brightcove IFRAME video playback (bonus: with Adobe Launch)

In a previous blog post, I had described how to use Adobe Experience Platform Launch (or Adobe Launch, as it's more commonly known) to track Brightcove video playback to Adobe Media Analytics. It was part of three-part series on video tracking for Adobe Analytics:

1. Part one: tracking video playback events using Adobe Analytics' Custom Links.
2. Part two: tracking video playback events to Adobe Media Analytics, Adobe's media tracking and reporting solution.
3. Part three: tracking Brightcove video playback events to Adobe Media Analytics, instead of Brightcove's own analytics integration.

But those instructions for Brightcove video playback had been written for the advanced <VIDEO-JS> implementation of Brightcove videos into your website. It did not work with Brightcove's more common <IFRAME> implementation.

In this guide, I provide instructions and a working script that can detect video playback events from Brightcove's IFrame player. This is written as a standalone guide, so you don't need to read the earlier three-part series.

As a bonus, I also provide a short guide on how these events can then be used with Adobe Experience Platform Launch. Adobe Experience Platform Launch, more commonly known as Adobe Launch, is Adobe's tag management solution. To find out more about Adobe Launch, you can read it from Adobe's documentation.

Recipe to track Brightcove IFrame video playback events
(with bonus Adobe Launch implementation!)

1. Add custom script to the Brightcove player.
2. Bonus! Setup Adobe Launch to track these video playback events.

1. Add a custom script to the Brightcove player.

The main challenge of tracking video playback events from the Brightcove IFrame player is that of working with the IFrame. Web browsers prevent any events that happen within an IFrame from being detected in the parent window (the one that contains the IFrame). As a result, when the user presses the "Play" or "Pause" button in the Brightcove player, the player can play and pause the video accordingly, but the parent window is unable to detect those events.

And if the parent window cannot detect those video playback events, then any analytics tracking system that runs from that parent window – whether through native tracking code or a tag management system like Adobe Launch – also cannot track the playback.

Fortunately, browsers allow something called "messages" to be passed (or "posted") from an IFrame to the parent window (and vice versa). This mechanism allows both window frames to communicate with each other. But in the case of the Brightcove IFrame player, that "post message" mechanism has to be scripted by the Brightcove account owner.

I have provided a complete working Brightcove IFrame video playback event tracking script that can do exactly that:

• Detect the video playback events that happen within the player.
• Post those events as messages back to the parent window.

My script is available for public use, so you can adapt it to use with your own Brightcove player. The script is licensed through the GNU General Public License version 3.0. Also, take note of the disclaimer in my script.

Out of the box, my script can detect these video playback events:

• loadeddata
• stalled
• play
• pause
• timeupdate
• ended
• volumechange

(Coincidentally, these are also the events that Adobe Launch's Core extension can detect natively from HTML5 media elements.)

Whenever any of those video playback events occur in the player, a corresponding message is posted to the parent window in this structure:

{
    currentTime: float,
    duration: float,
    name: string,
    state: string,
}

where:

• currentTime: the current time indicated in the video's timeline, in seconds.
• duration: the total length of the video, in seconds.
• name: the name of the video stated in Brightcove.
• state: the video playback event, e.g. "play", "pause", etc.

My script does not perform a lot of processing beyond event detection and message posting. This is designed purposely: the point of my script is to allow the video playback events to be sent back to the parent window, e.g. for analytics tracking. So any processing that should be done on the video playback events should be done at the parent window's level.

These should be enough information to track most video playback events. But if they are insufficient, you can make a copy of my script and modify according to your needs, in accordance with the GPL v3.0 licence. Also, if you modify the script, please update the @author line to indicate that you are the author, and also give credit to me for the original script.

To include my script in the Brightcove player:

1. In your player's settings, click on "Plugins".
   

   

   Click on "Plugins" in the Brightcove player settings menu

2. Click on "Scripts", then the "Add a Script" button.
   

   

   In Plugins, add a script

3. Add the URL to the script, then press "Save". If you're using my script, then the URL is https://gist.github.com/yuhui/3375b8221f6152600321bdf710dbe90b.js. By using my script, you also agree implicitly to the disclaimer indicated in my script. Otherwise, use your own URL. Your script must be hosted somewhere, Brightcove does not host scripts.
   

   

   Add the script URL and save.

4. Publish the player. It may take a few minutes for the published Brightcove player's changes to be reflected in the player in your website.

My script works with both the standard Brightcove player and also the Brightcove "Gallery" experience. In the Gallery experience, you need to include a player that Brightcove will load in its IFrame. Include my script in the player itself, not in the experience.

To test that my script is working, in your parent window's web page, add an event listener to the window to listen for "messages" from "https://players.brightcove.net" and log them to the console. For example:

window.addEventListener('message', function(e) {
  if (e.origin === 'https://players.brightcove.net') {
    var message = JSON.parse(e.data);
    console.log(message);
  }
});

That is all you need to detect the video playback events from the Brightcove IFrame player in your web page's parent window. You can then make use of the posted message as you require in your analytics tracking system.

2. Setup Adobe Launch to track these video playback events.

If you're using Adobe Launch as your tag management system, then you can make use of these posted messages from the Brightcove IFrame player to track video playback. I've chosen to load the event listener at Window Loaded. This should ensure that the user's web browser has loaded the Brightcove IFrame player completely, so that message posting-and-listening can occur successfully.

Window Loaded rule to listen for the posted messages from the Brightcove IFrame player

I personally prefer to re-send these messages as Custom Events, and then have separate rules based on those Custom Events to send the video playback data to Adobe Analytics. Doing so reduces some coding, while also allowing for the Custom Events to be re-used with other Brightcove events in future (a rudimentary "future-proofing").

The Custom Code action that dispatches these Custom Events is as follows:

window.addEventListener("message", function(e) {
  if (e.origin === "https://players.brightcove.net") {
    var message = JSON.parse(e.data);
 
    // build the Custom Event
    var customEvent = new CustomEvent("Brightcove video playback", { detail: message });
 
    // send the Custom Event via the Brightcove IFrame player
    var brightcoveIframe = document.querySelector("iframe[src*='brightcove']");
    brightcoveIframe.dispatchEvent(customEvent);
 
    // use the Custom Event "Brightcove video playback" in a rule to send Adobe Analytics beacons
  }
});

This is also a good place to run any code to process the data before sending to Adobe Analytics, for example, calculating 25%/50%/75% watched milestones.

Now, you can track video playback events from your Brightcove IFrame player to your analytics tracking system. If you're using the advanced Brightcove <VIDEO-JS> method, you can refer to my previous guide on how to track those video playback events.