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

Google's Tag Manager (GTM) allows you to track the usage of your websites, video content, and mobile apps. First, you add a container tag to your assets. Then, you use a web-based user interface to customize the individual tags associated with your container tag based on your business rules.

Here are some tag examples:

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

If you are new to GTM, review Google's Tag Manager overview document.

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

Major implementation steps

From a high level, here are the major steps you must follow to implement and use GTM:

  1. Create a GTM account and setup a container - these are both part of the initial GTM setup
  2. Copy and paste the container snippets that need to be implemented on your web pages. Google suggests that this code be placed in the <head> tag or immediately after the opening <body> tag.
  3. Create tags - for Google Analytics or Brightcove Player
  4. Publish your tags.

For setup details, see Google's Set up and install Tag Manager document.

Working with Brightcove Player

Brightcove's GTM 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 the code for a tag 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 or later
  • The Google Tag Manager plugin requires that you use the Advanced embed code when publishing your player. You should NOT use the Standard (iFrame) embed code with this plugin. For details, see the Integrating with Brightcove section.

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, click 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 the values for your new account page, including the account name and container name, and select a target platform.

    New account information
    New account information
  3. Click 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 them 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 and dimensions

Choose the events and dimensions that you want to track from Brightcove Player.

Events

Any event name used by Brightcove player's analytics-beacon event can be used, but the following have special handling in the GTM plugin.

Event Description
player_load Player has been loaded and is operational
video_impression Video has been loaded into a player and is ready for playback
video_view Video has started playing back either through auto-play or user interaction
video_engagement A user watches 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 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 Control is handed over to an advertising agent by the playback platform
ad_end Control is handed back from the advertising agent to the playback platform
error A fatal error has occurred which disrupts the playback experience
video_complete Video playback finishes

Dimensions

The following dimensions will be sent for all events(except error)

Parameter Description
bcvideo_account Video Cloud Studio account ID
bcvideo_destination Playback location
bcvideo_platform_version Brightcove Player version
bcvideo_player Brightcove Player ID
bcvideo_player_name Brightcove Player name
bcvideo_session Session associated with the player
bcvideo_video Video ID
bcvideo_name Video name
bcvideo_tags List of tags associated with the video

Event-specific dimensions

These custom dimensions will be sent in specific events.

Parameter Description
bcvideo_video_playhead Sent in play_request and engagement events
bcvideo_video_duration Sent in engagement event
bcvideo_video_range Sent in engagement event
bcvideo_video_percent_viewed Sent in engagement event
bcvideo_video_seconds_viewed Sent in engagement event
bcvideo_video_milestone Sent in engagement event

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. Click Variables in the left side navigation.
  3. In the User-Defined Variables section, click the New button, and then click Variable Configuration.

    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. 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
  7. Brightcove parameters you can create as GTM variables:

    • Account - Brightcove account ID
    • 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
  8. 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. Click Tags in the left side navigation, and click the New button, and then click Tag Configuration.
  3. Select the Tag Type as Google Analytics: GA4 Configuration.

    Tag configuration
    Tag configuration
  4. Enter the tag details:

    • Measurement ID - Enter your "G-" ID, or select the variable.
    • If you want to automatically send pageview events, keep the Send a page view event when this configuration loads option checked.

    Optional settings:

    • Server-side tagging - To send all GA4 events to a Tag Manager server container instead of Google Analytics, select Send to server container.
    • Parameters - Add any parameters to configure in Fields to Set.
    • Custom properties - Add any custom user properties to configure in User Properties.
  5. Select the corresponding trigger to to make the tag fire.

    Tags in GTM
    Trigger
  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. Click Triggers in the left side navigation, and click the New button, and then click Trigger Configuration.
  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. Click the link for the player to open the player's properties.
  3. Click Plugins in the left navigation menu.
  4. Next, click 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. Click 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, click Close.
  10. Return to the MEDIA module and publish your video or playlist using the player you just updated for Google Tag Manager. Choose the Advanced embed code to publish your player.

    Advanced embed code
    Advanced embed code
  11. 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 custom dimensions directly in Google Analytics, follow these steps:

Use the follow steps to create the custom dimensions in the Google Analytics UI:

  1. Login to your Google Analytics account.
  2. In the GA page:
    1. Click Admin (gear icon) in the bottom-let of the UI.
    2. In the Property column, click Custom Definitions.
      custom dimensions
  3. Click Create custom dimension.
  4. Fill in the fields with the necessary information:

    • 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.

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

Viewing custom dimensions

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

  1. Log in to Google Analytics.
  2. Click 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

GTM dual tagging

To set up dual tagging in a website that already uses Universal Analytics through Google Tag Manager, a corresponding tag in Google Tag Manager for Google Analytics 4 will need to be set up for every current tag. The process must be replicated until all current Universal Analytics tags have parallel Google Analytics 4 tags.

  1. Create a Google Analytics 4 property and note its tracking ID. In Google Tag Manager, create a new tag and select Google Analytics: GA4 configuration as the tag type.

    Analytics admin
    Create tag
  2. Enter the new GA4 property tracking ID in the measurement ID field.

    Analytics admin
    Property Tracking ID
  3. Select All pages as the trigger to make the tag fire.

    Analytics admin
    Selecting Trigger
  4. Create a GA4 tag for every Universal Analytics event that is set up. For example, to set up the play_request event, you must create the trigger first.

    Analytics admin
    Play Request Trigger
  5. Then, create a tag and select Google Analytics: GA4 Event as the tag type, select Google Analytics: GA4 configuration as the configuration type, play_request as the event name, and select the play request trigger as the firing trigger.

    Analytics admin
    Play Request Tag Configuration
  6. To test the setup, click Preview on the top right corner and enter the website URL with UA GTM installed. Make sure that the newly set GA4 tags get fired along with the already existing UA tags.

    Analytics admin
    Play Request Test