Google Tag Manager Plugin for Brightcove Player

In this topic, you will learn how to use the Google Tag Manager (GTM) plugin for Brightcove Player.

Overview

The Google Tag Manager (GTM) plugin allows you to integrate GTM functionality with Brightcove Player. Examples of tags, which generally is code that sends data to a system like Google Analytics, you may wish to manage include:

  • Google Analytics Universal tracking code or GA4 tracking code
  • Adwords Remarketing and/or Conversion Tracking code
  • Custom HTML scripts

For an introduction to GTM from Google itself, watch the video located on the Tag Manager overview document.

If you are already using Google Analytics, Adwords and DoubleClick, then you may also want to use Google Tag Manager, as it integrates well with these tools. GTM offers a large number of variable and trigger options.

Major implementation steps

From a high-lever perspective, here are the major steps you must follow to implement to use GTM:

  1. Create a GTM account and setup a container, which are both part of the initial GTM setup.
  2. Upon completion of initial setup, you will need to copy and paste the container snippets that need to be implemented on your web pages. Google suggest as locations hight in the <head> tag and immediately after the opening <body> tag.
  3. Add tags, for instance for Google Analytics or Brightcove Player.
  4. Publish your tags.

For an overview of the installation process from Google itself, watch the video located on the Set up and install Tag Manager document. Detailed hands on steps follow later in this document.

Working with Brightcove Player

The Google Tag Manager plugin enables you to track Brightcove Player events using the Google Analytics dashboard. The following player events can be tracked:

  • Player load
  • Video impression
  • Video view
  • Video engagement
  • Play request
  • Video complete
  • Advanced player events such as ad start, ad end
  • Errors which disrupt the playback experience

Tag management terminology

Here are some of the common terms you will encounter when using Google Tag Manager (GTM).

Term Description
Container Your tag management system account can have multiple containers (profiles), with its own tags and variables. Each container can have multiple environments, usually set up for development, staging and production.
Data layer The data layer refers to the collection of data that lives in the code of your web page. This JavaScript object is used to pass information from your website to your tag manager container. You can then use this information to populate variables and activate triggers in your tag configurations.
Event Events are data points used to send data to your reporting tool. These are related to video loading and playback.
Tag Tags are code snippets placed on your web page to collect user interaction data. Tag management systems simplify the process of adding tags to your site, requiring that you only supply the tag id and tag event type.
Tag marketplace Tag marketplace templates provide code snippets for deploying a tag. While this reduces the amount of code knowledge needed, some familiarity with JavaScript and HTML is required for successful implementation.
Tracker Trackers are objects that collect, store data and send that data to Google Tag Manager.
Trigger Triggers tell when tag code should be added to a page. These are user-defined conditions.

Requirements

The following requirements are needed to use the GTM plugin:

  • Brightcove Player v6.46.0 and newer

Getting started

To set up Google Tag Manager follow these steps:

Steps

  1. In Tag Manager, create an account or use an existing account. To create a new account, select the Create Account button.

    By default, a new container is created for a new account. You can create additional containers within each account.

    Create account
    Create account
  2. Enter values for your new account page, including account name and container name. Select a target platform.

    New account information
    New account information
  3. Select the Create button.
  4. Agree to the terms of service.
  5. The Install Google Tag Manager dialog appears. From here you will need to copy the snippets and place in the locations specified.
    New account information
    Snippets
  6. If you ever need to get back to the snippets, you click the container ID in the GTM dashboard.
    New account information
    Container ID to see snippets again

Reviewing events to track

Review the table below and determine which events you want to track.

Type Event Description
Player Load player_load Player has been loaded and is ready for playback
Video Impression video_impression Video has been loaded into a player and is ready for playback
Video View video_view Video has started playing back either through auto-play or due to user interaction
Video Engagement video_engagement A user watched a range of seconds of a video's timeline. This event is a heartbeat for tracking video engagement and will likely be sent many times during playback, depending on the user interaction and the length of the video.
Play Request play_request Playback is initiated either by the user expressly clicking the play button, or automatically when the platform triggers playback in an auto-play scenario
Ad Start ad_start Control is handed over to an advertising agent by the playback platform
Ad End ad_end Control is handed back from the advertising agent to the playback platform
Error error A fatal error has occurred which disrupts the playback experience
Video Complete video_complete Video playback finishes

Creating Variables, Tags & Triggers

Every Brightcove event that you want tracked must be created as an Event Tag in Google Tag Manager (GTM). The event IDs from GTM will then be used inside the Players module. This allows Brightcove event data to be passed to GTM events.

For each Event Tag, you need to create a GTM trigger to send the event to Google Analytics. Then, in the GTM Variables tab, you will create the custom parameters associated with each event.

Adding Variables to GTM

Brightcove parameters carry additional data and are passed with events. Every Brightcove parameter that will be recorded must be created as a Variable in Google Tag Manager. The parameter name will be used inside the player, allowing Brightcove parameters to be passed to Google Tag Manager Variables.

To create Variables in Google Tag Manager, follow these steps

  1. Login to your Google Tag Manager account

  2. Select Variables in the left side navigation.
  3. In the User-Defined Variables section, select the New button.

    Data Layer Variable
    Data Layer Variable
  4. For variable type, select Data Layer Variable.

    Data Layer Variable
    Data Layer Variable
  5. These are the configuration details:

    • Data Layer Variable Name - Name of the variable
    • Data Layer Version - Version 2
  6. First, create three user-defined variables called; Event Action, Event Category, and Event Label. The configuration should look similar to this.

    • Event Action - eventAction
    • Event Category - eventCategory
    • Event Label - eventLabel
    Event action variable
    Event action variable
  7. Then create the variables required to reflect the Brightcove parameters. In this case, the name of the Data Layer Variable should match what is in the player’s JSON config for paramsToTrack after customDimensions in the GTM variable. Here is an example:

    Account variable
    Account variable
  8. Brightcove parameters you can create as GTM variables:

    • Account - Brightcove account name
    • Player - Player ID
    • Player Name - Player Name
    • Platform Version - Platform version number
    • Session - Session identifier
    • Video - Video ID
    • Video Name - Name of the video
    • Range - The range of seconds viewed in the format StartSecond..EndSecond
    • Video Seconds Viewed - Count of watched seconds
    • Video Duration - The duration of the video in seconds
    • Video Percent Viewed - Percentage of video watched
    • Error Code - Platform specific error code associated with the event
    • Video Milestone - Milestone (25%,50%,75%,100%) completed by the video
    • Video Playhead - The time in the video at which the event is triggered
    • Destination - URI that originated the event
  9. Your user-defined Variables should look similar to this in GTM:

    User-defined variables
    User-defined variables

Adding Tags to GTM

After you determine which events you want to track, Tags must be created in Google Tag Manager.

To create Tags in Google Tag Manager, follow these steps

  1. Login to your Google Tag Manager account

  2. Select Tags in the left side navigation, and select the New button.
  3. Select the Tag Type as Google Analytics: Universal Analytics.

    Tag configuration
    Tag configuration
  4. Enter the tag details:

    • Track Type - Set to Event
    • Category - Event Category Variable
    • Action - Event Action Variable
    • Label - Event Label Variable
    • Value - Nil
    • Non interaction hit - Set to True
    • Google Analytics Settings - Default setting
    • Tracking ID - Tracking ID of GA dashboard. Select Tracking ID Variable.
  5. Go to Advanced settings and set the related Custom Dimension indices and Dimension Values. These indices should match what's in Google Analytics.

  6. Your Tags should look similar to this in GTM:

    Tags in GTM
    Tags in GTM

Adding Triggers to GTM

For each event that you want to track, you also need a Trigger in Google Tag Manager.

To create Triggers in Google Tag Manager, follow these steps

  1. Login to your Google Tag Manager account

  2. Select Triggers in the left side navigation, and select the New button.
  3. Select the Trigger Type as Custom Event.

    Trigger configuration
    Trigger configuration
  4. Enter the Event name; the event name should look similar to the image below.
    Trigger configuration name
    Trigger configuration name
  5. Create a Trigger for each Event that you want to track.

  6. Your Triggers should look similar to this in GTM:

    Triggers in GTM
    Triggers in GTM

Integrating with Brightcove

To integrate GTM with Brightcove Player, add the Google Tag Manager plugin to your player.

Using Studio

The following steps detail using Video Cloud Studio to load the plugin.

  1. In Video Cloud Studio, open the PLAYERS module and either create a new player or locate the player to which you wish to add the plugin.
  2. Select the link for the player to open the player's properties.
  3. Select Plugins in the left navigation menu.
  4. Next, select the Add a Plugin button, and then select Brightcove Plugin.

    Add a Plugin button
    Add a Plugin button
  5. Expand the Brightcove Plugin dropdown and select Google Tag Manager.

    Google Tag Manager plugin
    Google Tag Manager plugin
  6. To tell the player which events and custom dimensions you want to track, create a JSON object to paste into the Options(JSON) text box.

    Field descriptions:

    • tracker - Your Google Tag Manager tracking id (GTM-XXXXXXX)
    • eventsToTrack - Events you want to track
    • paramsToTrack - Custom dimensions you want to track
    • milestones - An array of integers to alter the milestones from the default of 25, 50, 75, 100%. Of course, this is only applicable when bcvideo_video_milestone is being tracked.

    Here is an example:

     { "tracker":"your Google Tag Manager id", "eventsToTrack": {
     "ad_end": "Ad End",
     "ad_start": "Ad Start",
     "error": "Error",
     "play_request": "Play Request",
     "player_load": "Player Load",
     "video_complete": "Video Complete",
     "video_engagement": "Video Engagement", "video_impression": "Video Impression", "video_view": "Video View"
     },
     "paramsToTrack": {
     "bcvideo_video_duration": "duration",
     "bcvideo_error_code": "error",
     "bcvideo_account": "account",
     "bcvideo_session": "session",
     "bcvideo_video_milestone": "milestone", "bcvideo_video_name": "video_name",
     "bcvideo_range": "range",
     "bcvideo_video_seconds_viewed": "seconds_viewed", "bcvideo_player_name": "player_name",
     "bcvideo_video_percent_viewed": "percent_viewed", "bcvideo_destination": "destination",
     "bcvideo_video_playhead": "playhead"
     }
     
     }
  7. Select the Save button. You will now see the Google Tag Manager plugin added to the list of plugins for your player.

    Save button
    Save button
  8. To publish the player, select Publish & Embed > Publish Changes.
  9. To close the dialog, select Close.
  10. Return to the MEDIA and publish your video or playlist using the player you just updated for Google Tag Manager.

    When your player loads and the user interacts with the player, the specified events and parameters will be tracked.

Creating custom dimensions

Custom dimensions are metrics that you create yourself in Google Analytics. There are two ways to add custom dimensions, the first is adding the dimensions directly in Google Analytics, and the other is using Google Scripts.

Adding custom dimensions with Google Analytics

To add the ustom dimensions directly in Google Analytics, follow these steps:

  1. Log in to Google Analytics.

  2. Select Admin.

    Analytics admin
    Analytics admin
  3. Click on Custom Definitions to expand it, then select Custom Dimensions.

    Custom dimensions
    Custom dimensions
  4. Click the New Custom Dimension button.

    New Custom dimensions
    New Custom dimensions
  5. Enter the Custom Dimension Name and then click on Create. Google Analytics will assign an index number automatically. You will need to create a custom dimension for each parameter you want to track.

    Add Custom dimensions
    Add Custom dimensions

Adding custom dimensions with Google App Script

To use a Google App Script to create custom dimensions, follow these steps:

  1. If you are new to custom dimensions, review Google's Custom dimensions & metrics document.
  2. Log in to Google.
  3. Navigate to the G Suite Developer Hub and select the Apps Script new blank project.

    Apps Script project
    Apps Script project
  4. Select Untitled project and give your project a name.

    Script editor
    Script editor
  5. Copy the following custom app script code to an editor, and update the following values:

    • accountId - Your Google Analytics account ID
    • webPropertyId - Your Google account tracking ID
    • dimensions - The custom dimensions to be added. The current list contains all of the custom dimensions. Notice that the dimensions are prefixed with bcvideo_. This is to ensure there are no naming conflicts with these variables.
     //Set values for GA Account ID and web property ID to which you have to set custom dimensions.
     var accountId='your account id'; var webPropertyId='your tracking code'; //Add required custom dimensions to be created to this list var dimensions=['bcvideo_video_seconds_viewed','bcvideo_video_playhead','bcvideo_account','bcvideo_player','bcvideo_player_name','bcvideo_video','bcvideo_video_name','bcvideo_session','bcvideo_platform_version','bcvideo_range','bcvideo_video_duration', 'bcvideo_video_percent_viewed','bcvideo_error_code','bcvideo_milestone','bcvideo_destination']; //Function to create custom dimensions in GA function createGACustomDimensions() {
     //This loop iterates through the custom dimensions in order to set the custom dimension scope, active values into our GA property for(var index=0;index<dimensions.length;index++){ var customDimensions ={
     'name': dimensions[index],
     'scope':'HIT',
     'active':true,
     }
     //This create a request to the new custom dimension Analytics.Management.CustomDimensions.insert(customDimensions,accountId,webPropertyId); // Pause for 1 second between adding each custom dimension, this ensure that the GA property has time // to process the request fully before moving to the next custom dimension.
     Utilities.sleep(1000)
     }
     }
  6. Replace the function myFunction(){} code block, as shown below, with your custom app script.

     function myFunction() { }
  7. Save the project. You need to save the project to be able to use Google Analytics API.
  8. To enable Google Analytics API, in the script editor, select Resources > Advanced Google services.

    Advanced Google Services
    Advanced Google Services
  9. Then, find Advanced Google services, and turn it on. Select OK.

    Google Analytics API
    Google Analytics API
  10. To run your app script, select Run > Run function, and choose your script.

    Run script
    Run script
  11. In the authorization dialog, select Review Permissions.

    Authorization dialog
    Authorization dialog
  12. Select the Allow button.

    Allow permissions
    Allow permissions

Viewing custom dimensions

To view custom dimensions in Google Analytics, follow these steps:

  1. Log in to Google Analytics.
  2. Select Admin

    Analytics admin
    Analytics admin
  3. Click on Custom Definitions to expand it, then select Custom Dimensions.

    Custom dimensions
    Custom dimensions
  4. You should see the custom dimensions along with their associated indices.

    Dimensions and indices
    Dimensions and indices