Google Analytics

Integrating Brightcove’s video player with Google Analytics

For the many customers of Brightcove’s video platform, understanding user engagement (ex: play, pause, percentage watched) with their videos is key. And while Brightcove offers reports showing user engagement, there are many advantages to tying that data into a broader analytics platform such as Google Analytics. One particular advantage of this approach is that AdWords remarketing lists can be generated based on video engagement. Did a user watch your video but not convert? Remarket them!

I recently completed a Brightcove/GA integration and learned some things along the way worth sharing.

Setting the Stage

This being my first introduction to Brightcove, I found it overwhelming reading through documentation that referenced multiple iterations of the Brightcove platform and plug-ins. Are we using the Smart Player? The Video Cloud? Which 3rd party GA plug-in? You’ll find references to all of these items on both Brightcove’s website and on 3rd party blog posts and forums.

While I can’t say I understand the entire landscape, this post will focus on the technologies I used during this engagement:

• The Brightcove Video Cloud studio
• The Standard and Advanced player embed code
• The Google Analytics for Brightcove player plug-in

A few things to prepare in advance to integrate Google Analytics and Brightcove:

• You’ll need access to your Brightcove Video Cloud account in order to modify your video player’s settings
• You’ll need to know the property ID of the Google Analytics account that should receive the information (this is typically in the format of UA-XXXXX-Y)
• You’ll need to host the Google Analytics for Brightcove JavaScript file somewhere on your servers
• You’ll need to have already installed the GA tracking tag on the page hosting the video player. This is typically either loaded from a tag management provide or is placed directly within the page HTML in the form of: ga(‘create’, ‘UA-XXXXX-Y’, ‘auto’);
• You’ll want to have Google Tag Assistant installed for debugging purposes

Step 1 – Configure your Player

The first step is to configure your player from within the Video Cloud studio to utilize the GA for Brightcove plug-in. This is fairly easy to do and there are detailed instructions on the GA for Brightcove GitHub readme.

One thing those instructions are missing are screen shots showing what the final configuration looks like:

Note that there are plenty of other configuration options available from within the plug-in if you wish to change the events that are captured and how they appear within GA.

Step 2 – Embed your Player

At this point, we’re ready to embed your player. Brightcove provides 2 options for embedding players: standard (iFrame) or advanced (HTML5 <video> tag). Here is where we need to diverge a bit and talk about the differences and how they relate to analytics.

The Problem with iFrames

Brightcove recommends the “standard” embed code as it is slightly simpler to implement and is immediately compatible with older browsers (namely IE8 and below). However, there’s an undocumented issue with regards to how this embed code interacts with the Google Analytics plug-in that require some explanation.

When a user visits a website with the GA tracking code installed, GA assigns them a unique “client id” and places it in a first-party cookie that’s associated with the domain of the website. As the user performs various actions on the website (page views, clicks, etc) all of this data is associated with the same “client id”.

Why is this relevant to our Brightcove standard embed code? Because it loads an iFrame from players.brightcove.net which is a different domain than your website. This means that when the user loads your webpage containing the iFrame, in the background Google Analytics is creating 1 client id for your website and a different client id for the iFrame. Practically what this means is that the “page view” hit sent when the user loads the page will not be tied to the “media play” events that you’re collecting against the Brightcove player. It will look as though 2 different users were loading the page and then utilizing the player.

There is a way to code yourself out of this situation, but it requires modifying both the iFrame embed code and the GA Brightcove plug-in itself. To summarize: you pull the client ID out of the GA cookie on your page and pass it as a URL parameter to the iFrame. When the GA plug-in loads, it can then be instructed to utilize the client ID it was passed. I can share this code if anyone likes, but it isn’t pretty 🙂

The Beauty of HTML5

Fortunately, all of the above can be avoided by using the ‘advanced’ player embed code which utilizes HTML5 in order to serve the video player natively from your website, instead of from player.brightcove.net. Because all interactions are occurring from a single domain, a single GA client ID will be generated.

Be aware that this introduces the aforementioned compatibility issues with IE8 and lower, but Brightcove has provided a fix for IE8 that’s relatively easy to implement. There will still be issues with IE7 and IE6 so be sure to check your analytics to understand the impact on these browsers.

Players vs Media

Just a quick point that confused me and may confuse others: Brightcove keeps a strong separation between “media” and the “players” that play that media. If you grab the iFrame or Advanced embed code from the Video Cloud studio, you’ll still need to associate that player with a specific Video ID. There are instructions here on how to do so.

Step 3 – Validate and Analyze

You now have the player emebeded on your page and it’s time to validate whether or not data is being collected as expected. The best way to do this is by using the Google Analytics Tag Assistant plug-in for Chrome which allows you to record and playback Google Analytics sessions. In this way, we can see the data as GA will see it and ensure that we avoid common errors.

If everything has been properly configured, the Tag Assistant plug-in will produce a report showing the GA events firing as expected.

In order to validate that this information is flowing into Google Analytics, you can use GA’s “Real Time Analytics” report. Just be sure that you’re looking at an unfiltered view as many views will filter out traffic from a company or remote employee’s IP.

Common Errors

While the report above shows the best case scenario – a working integration – I ran into many errors along the way.

1. Duplicate trackers – When I first started the project, Tag Assistant showed that the client had inserted the GA snippet twice and was therefore tracking 2 page views for every view. Removing one of the snippets resolved this.
2. Session starting with Event – Google Analytics requires that the first hit used to start a session be a pageview hit. The Tag Assistant will warn you if the first hit sent to Google Analytics is an event. This likely means that the GA Brightcove plug-in is installed but you’re not sending a pageview hit on page load.
3. Client ID changed – When we were using the Brightcove iFrame embed, it was Tag Assistant that warned us about the problem with client ID’s mentioned earlier.
4. If you’re missing the event data altogether it’s likely that the GA Brightcove plug-in isn’t installed properly.

Conclusion

I hope this breakdown helps anyone who needs to complete the same task. As always please reach out with any questions or suggestions!