Google Analytics Plugin

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:

Requirements: Requirements for using the Google Analytics Plugin v2.1.0 and newer.
Implement using Players module: Steps to follow to implement the plugin using Studio's Players module. Note that at this time configuration in the Players module must be done through the JSON Editor only. The user interface options are for Universal Analytics only.
Implement using code: Steps to follow to implement the plugin in an HTML page.
Options: The configuration options available for the plugin.
GA4 events and custom dimensions: The GA4 data options to send to Google Analytics.
GA4_and_UA_dual_tagging_example_configuration: Configuration option for both Google Analytics 4 and Universal Analytics, referred to as dual tagging.

Requirements

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

Brightcove Player v7.0.0 or newer

Implement using Players module

To implement the Google Analytics plugin using the Players module.

In Studio select the Players module.
Click the player to which you wish to add the Google Analytics plugin.
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
Complete the sign in process by entering information for your Google account and which Google Analytics account to send data.
Select a GA4 account Tracking ID in the Google Analytics 4 (GA4) dropdown.
Finish the configuration using the provided form.
Click Save. Publish your player if not completing the rest of the rest of the steps.
You need to do the rest of the steps in this section ONLY if you are configuring for GA4 or dual tagging.
In the left-navigation, click JSON editor.
You need to make the following changes:
- Change the version to 2.x: "version": "2.x",
- Update the options and events to track as desired. See the GA4 events and custom dimensions section below for details.
- Change the tracker to your GA4 tracker ID.
Example:
Click Save and 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.
eventsToTrackGA4: 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.
Note: These parameters are be added as custom dimensions in the Google Analytics UI. Instructions for this task follow later in this document.
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

Create custom dimensions

You must create each of the custom dimensions you are using. Note the following:

During the creation of each custom dimension, you are asked to select a Scope. For these custom dimensions use the value Event.
When creating the dimensions you can choose a more friendly name. For instance, consider the following:
- When creating the custom dimension for video_duration you name it simply Duration because you want the friendlier name used in your reports.

Use the follow steps to create the custom dimensions in the Google Analytics UI (steps assume you have create your property):

Login to your Google Analytics account.
In the GA page:
1. Click Admin (gear icon) in the bottom-let of the UI.
2. In the Property column, click Custom Dimensions.
Click Create custom dimension.
Create a custom dimension for each parameter listed in the paramsToTrackGA4 array, those being:
- account
- platform_version
- player
- range
- seconds_viewed
- session
- tags
- video_duration
For each parameter in the array, complete the form:
- Dimension name: Friendly name for your parameter.
- Scope: This is always Event for Brightcove GA plugin.
- Description: Add appropriate description.
- Event parameter: Choose one of the parameters listed just above.

These custom dimensions are now associated with the appropriate event in your Google Analytics reports.

For further information on using the Google Analytics UI, see the following:

Introducing the next generation of Analytics, Google Analytics 4
Set up Analytics for a website and/or app
Add a Google Analytics 4 property (to a site that already has Analytics)
[GA4] Custom dimensions and metrics: Create dimensions and metrics from event parameters and user properties so you can easily access data in reports and explorations

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

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