Google Analytics Plugin

In this topic, you will learn the use of the Google Analytics plugin and how it can be implemented using Studio and through custom coding.

Overview

The Brightcove Google Analytics plugin provides functionality to send data to Google Analytics. Note that the plugin supports both Google Analytics 4 and the older Universal Analytics. This document contains seven main content sections, those being:

Workflow

The Google Analytics plugin first checks for the eventsToTrack option and the trackerID. If they're both present, it initializes GA and then listens for analytics-beacons and/or analytics_request events and on every player event, it checks if the event is present in the list of events to track. If it is, the plugin then gets the custom dimensions (that are also present in the paramsToTrack )associated with the event. The events that are handled in the GA plugin and the custom dimensions associated with them are:

  • player_load - common custom dimensions
  • video_engagement - common custom dimensions + video_duration+video_range+seconds_viewed
  • video_impression - common custom dimensions
  • play_request - common custom dimensions
  • ad_start/ad_mode_begin - common custom dimensions
  • ad_end/ ad_mode_complete - common custom dimensions
  • error - common custom dimensions
  • video_view - common custom dimensions
  • video_complete - common custom dimensions

    • Custom dimensions include - video_account, video_player, video_session, video_platform_version, video_tags.

Requirements

Brightcove Player Google Analytics Plugin v2.1.0 and newer requires the following:

  • Brightcove Player v7.0.0 or newer

Setting Up the Google Analytics 4 account

  1. Create a Google Analytics 4 Property.
  2. Within their Property, create a Web Data Stream. Google also offers other types of “data streams” - iOS data streams and Android data streams, but our GA analytics integration does not support them.

Configuring Google Analytics

To configure Google Analytics integration, follow these steps:

  1. Open the Players module.
  2. Click the player name you want to configure to open the player properties.
  3. Click Third-Party Analytics > Google Analytics in the left navigation menu.
  4. Check Enable Google Analytics.
  5. Click Sign In to Google Account.
  6. Select the Google account to sign in with and enter your credentials if prompted.
  7. Click Allow to let Brightcove access your Google account.
  8. Use the Select Account dropdown to select the Google account to send tracking data to.
  9. Select the Events for Tracking. See the Events and custom dimensions section below for a description of the events.
  10. Click Save. This will configure the player with the Google Analytics plugin and create any needed custom dimensions in your Google Analytics account.

Make sure to publish the changes to the player.

Implement using Players module

To implement the Google Analytics plugin using the Players module.

  1. In Studio select the Players module.
  2. Click the player to which you wish to add the Google Analytics plugin.
  3. In the Player's property screen select:
    1. Third-Party Analytics -> Google Analytics
    2. Check Enable Google Analytics
    3. Click Sign in to Google Account
    enable Google Analytics
  4. Complete the sign in process by entering information for your Google account and which Google Analytics account to send data.
  5. Select a GA4 account Tracking ID in the Google Analytics 4 (GA4) dropdown.
    enable Google Analytics
  6. Finish the configuration using the provided form.
    configuration
  7. Click Save. Publish your player.

Implement using code

To implement a plugin, the player needs to know the location of the plugin code, a stylesheet location (if needed), the plugin name and plugin configuration options. For the Google Analytics plugin:

  • The location of the JavaScript plugin code (no CSS needed in this instance) is as follows: 
            https://players.brightcove.net/videojs-bc-ga/2/videojs-bc-ga.min.js
  • The name of the plugin is bcGa
  • The standard configuration options are shown in the following code.

The following shows using the Advanced (embed) code implementation of the player to associate the Google Analytics plugin with a single instance of a player.

  • Line 1: Gives the video-js tag an id attribute, with some value, in this case myPlayerID.
  • Line 9: Uses a script tag to include the plugin's JavaScript in the body of the HTML page.
  • Line 13: Creates a reference to the player.
  • Lines 14-35: Initializes the plugin and passes in custom options.
        <video-js id="myPlayerID"
          data-account="1752604059001"
          data-player="decfdaf5-0a6e-43f6-82d3-39d125c413c4"
          data-embed="default"
          data-video-id="4077874637001"
          controls=""></video-js>
        <script src="https://players.brightcove.net/1752604059001/decfdaf5-0a6e-43f6-82d3-39d125c413c4_default/index.min.js"></script>
      
        <script type="text/javascript" src="https://players.brightcove.net/videojs-bc-ga/2/videojs-bc-ga.min.js"></script>
      
        <script type="text/javascript">
          videojs.getPlayer('myPlayerID').ready(function() {
            var myPlayer = this;
            myPlayer.bcGa({
              "paramsToTrackGA4": [
                "account",
                "platform_version",
                "player",
                "range",
                "seconds_viewed",
                "session",
                "tags",
                "video_duration"
              ],
              "eventsToTrack": {
                "ad_end": "Ad Ended",
                "ad_start": "Ad Started",
                "error": "Player Errors",
                "play_request": "Play Request",
                "player_load": "Player Load",
                "video_engagement": "Video Engagement",
                "video_impression": "Video Impression",
                "video_view": "Video View"
              },
              "trackerGA4": "GA-123456-1"
            })
        });
        </script>

Options

The items listed below are plugin options used when configuring the Google Analytics plugin.

  • tracker: Google Analytics tracker ID.
  • eventsToTrack: An array that lists the events to send and the names that are used for those events.
    • Example: "player_load": "My name for player load event"
  • paramsToTrackGA4: An object that lists the parameters to include in events.
  • debug: Use true to turn on GA debug URL and visualize console trace. This should not be used in a production environment.

GA4 events and custom dimensions

Any event name used by the player's analytics_event and analytics-beacon events can be used, but the following have special handling in the GA plugin:

  • ad_end
  • ad_start
  • error
  • play_request
  • player_load
  • video_engagement
  • video_impression
  • video_view

The following are custom dimensions available for use:

  • account
  • platform_version
  • player
  • range
  • seconds_viewed
  • session
  • tags
  • video_duration

Parameters, which you add as custom dimensions in Google Analytics, are associated with event. The following parameters are common to all events:

  • account
  • player
  • session
  • tags
  • version

The video_engagement event includes the five parameters listed above, and also adds:

  • range
  • seconds_viewed
  • video_duration

GA4 and UA dual tagging example configuration

At this point in time (early 2023) both Google Analytics 4 and Universal Analytics are valid. The following is an example of dual tagging, where both Google Analytics 4 and Universal Analytics would function.

Dual tagging (both Google Analytics 4 and Universal Analytics)

{
  "registry_id": "@brightcove/videojs-bc-ga",
  "options": {
    "paramsToTrack": {
    "video_seconds_viewed": "dimension1",
    "range": "dimension2",
    "video_duration": "dimension3",
    "player": "dimension4",
    "session": "dimension5",
    ...
    },
    "paramsToTrackGA4": ["seconds_viewed","range","video_duration", "player", "session",...],
    "eventsToTrack": {
      "video_impression": "Video Impression",
      "play_request": "Play Request",
      "video_engagement": "Video Engagement",
      ...
    },
    "trackerGA4": "GA-123456-1",
    "tracker": "UA-123456-1"
  }
}

Google Analytics 4 migration

To ensure that data continues to be collected across Brightcove products with Google Analytics plugins, you must upgrade your Players to use GA4 instead of Universal Analytics.

Migration using Players module

  1. Make sure you are enabled in GA4 within Google. For more information, see How to get started with Google Analytics 4.
  2. In Studio select the Players module.
  3. Click the player to which you wish to update the Google Analytics plugin.
  4. In the Player Information section select:
    1. Third-Party Analytics -> Google Analytics
      enable Google Analytics
    2. Select a GA4 account Tracking ID in the Google Analytics 4 (GA4) dropdown.
      enable Google Analytics
  5. Click Save.
  6. Click Publish to publish the latest changes for your player.
  7. Repeat for each player using Universal Analytics.