Google Tag Manager Plugin for Brightcove Player

Product(s)
Video Cloud
Brightcove Player
Role(s)
Studio User
Player Developer
Topic(s)
Analytics
Plugin Development
In this topic, you will learn the 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.

Tag managers allow you to add and publish tags without having to use code. Because they are a client-side solution, tag managers enable you to collect data across different marketing technologies. This empowers marketers by giving them the ability to collect user and player data across a diverse set of collection points.

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.

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.

Getting started

Review Google's documentation for setting up Google Analytics and Google Tag Manager. The setup will include the following:

  • Define tag configurations for Google Analytics
  • Define triggers to fire beacons
  • Create variables for events and custom dimensions

Using the Brightcove plugin

Like other Brightcove Player plugins, the Google Tag Manager plugin must be loaded into the player.

Using Studio

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

  1. 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. Now, you are ready to configure Google Analytics with the dimensions you want to track. Review the dimensions that are available, see the Events and parameters section of this document.

  7. There are two ways to populate custom dimensions with Google Analytics.

  8. 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
  9. To publish the player, select Publish & Embed > Publish Changes.
  10. To close the dialog, select Close.
  11. 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.

  12. To see the dimensions in your account, login to your Google Analytics account. Navigate to Admin > Custom Definitions > Custom Dimensions. Your account should look similar to this:

    Dimension report
    Dimension report

Events and parameters

The following events and parameters are available to send to Google Tag Manager.

Events

These events come from your player.

  • player_load
  • video_impression
  • play_request
  • video_view
  • video_engagement
    • video_engagement - 25% Milestone
    • video_engagement - 50% Milestone
    • video_engagement - 75% Milestone
  • ad_start
  • ad_end
  • error
  • video_complete - 100% Milestone

The video watched percentage (video_engagement) can be calculated as follows (similar to video_engagement event in Google and Adobe analytics):

Video watched percentage = duration the user actually watched / total video duration

For example, in a 20 second video, the 25% milestone can be achieved in both of the below cases

  • User watches from 0-5 seconds
  • User watches from 0-1st second and skip to 11th second and watch to 15th second

In both of the above cases, the user watched 5 seconds, so milestone will be reported as 25%.

Parameters

These parameters come from your player.

  • account
  • player
  • player_name
  • video
  • video_name
  • video_duration
  • range
  • video_seconds_viewed
  • session
  • platform_version
  • video_percent_viewed
  • video_playhead

Automatic parameters

These parameters are automatically sent to Google Tag Manager, so you don't have to specify these in the JSON code.

  • country
  • country_name
  • region
  • region_name
  • city
  • browser
  • browser_type
  • destination
  • source
  • device_type
  • device_os
  • device_os_version

Configuring dimensions manually

Follow these steps to manually configure custom dimensions in your Google Analytics account:

  1. In the Options(JSON) text box, enter the events and parameters you would like to track. Field descriptions:

    • tracker - Your Google Tag Manager id
    • eventsToTrack - List of events you want to track
    • paramsToTrack - List of parameters you want to track
     

    Here is an example:

    {
      "tracker":"your Google Tag Manager id",
      "eventsToTrack": {
        "error":"Error",
        "play_request":"Play Request",
        "video_engagement":"Video Engagement"
      },
      "paramsToTrack": {
        "bcvideo_video_seconds_viewed":"dimension1",
        "bcvideo_video_playhead":"dimension2",
        "bcvideo_account":"dimension3",
        "bcvideo_player":"dimension4",
        "bcvideo_player_name":"dimension5",
        "bcvideo_session":"dimension8",
        "bcvideo_video":"dimension6",
        "bcvideo_video_name":"dimension7",
        "bcvideo_platform_version":"dimension9",
        "bcvideo_video_duration":"dimension11",
        "bcvideo_range":"dimension10",
        "bcvideo_video_percent_viewed":"dimension12",
        "bcvideo_error_code":"dimension13",
        "bcvideo_video_milestone":"dimension14",
        "bcvideo_destination":"dimension15"
      }
    }

Configuring dimensions automatically

Follow these steps to automatically configure custom dimensions in your Google Analytics account. These steps to use a Google App Script.

  1. Copy the following custom app script code to your clip board.

    //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)
      }
    }
  2. Navigate to the G Suite Developer Hub and select the Apps Script new blank project.

    Apps Script project
    Apps Script project
  3. Paste the custom app script from your clip board into the function myFunction(){} code block.

    function myFunction() {
    
    }
  4. Update the following fields with your own values:

    //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';
  5. Review the dimensions that are being added and update them to match your needs. Notice that the dimensions are prefixed with bcvideo_. This is to ensure there are no naming conflicts with these variables.

    //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'];
  6. Run the app script as shown below:

    Run script
    Run script

Changelog

See the changelog here.