support Contact Support | system status System Status
Page Contents

    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.

    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.

    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.

    Getting started

    To set up Google Tag Manager follow these steps:

    Steps

    1. Review Google's documentation to Setup and install Tag Manager.
    2. 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
    3. Enter values for your new account page, including account name and container name. Select a target platform.

      New account information
      New account information
    4. Select the Create button.

    Reviewing events to track

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

    Type Event Description
    Player Load bcvideo_player_load Sent when a player has been loaded and is ready for playback
    Video Impression bcvideo_video_impression Sent when a video has been loaded into a player and is ready for playback
    Video View bcvideo_video_view Sent when a video has started playing back either through auto-play or due to user interaction
    Video Engagement bcvideo_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 bcvideo_play_request Sent when 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 bcvideo_ad_start Sent when control is handed over to an advertising agent by the playback platform
    Ad End bcvideo_ad_end Sent when control is handed back from the advertising agent to the playback platform
    Error bcvideo_error Sent when fatal errors which disrupt the playback experience are encountered
    Video Complete bcvideo_video_complete Sent when video playback finishes

    Creating Variables, Tags & Triggers

    Every Brightcove event to be tracked must be created as an Event Tag in Google Tag Manager. The event IDs from GTM are used inside the player, allowing Brightcove event data to be passed to GTM events.

    GTM triggers, for each Tag, need to be created to send these events to Google Analytics (GA). The custom parameters associated with the events are also created in the GTM Variables tab.

    Adding Variables to GTM

    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 named will then 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. For User-Defined Variables, select the New button.
    4. Select the Variable Type as Data Layer Variable.

      Data Layer Variable
      Data Layer Variable
    5. Enter the details:

      • Data Layer Variable Name - Name of the variable
      • Data Layer Version - Version 2
    6. Parameters to be created:

      • 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
      • Country - ISO-3166 (alpha 2) country code, e.g.: US
      • Country Name - Human readable country name e.g.: United States
      • Region - ISO-3166 (alpha 2) region code
      • Region Name - Human readable region name
      • City - City Name
      • Browser - Full name and version of the browser used
      • Browser Type - Common name of browser used (i.e. Chrome, Edge, Firefox)
      • Destination - URI that originated the event
      • Source - URI that sent end-user to destination
      • Device Type - Override to specify the OS of the device that originated the event in cases where the User-Agent is unreliable
      • Device OS - The name of OS being used by the device
      • Device OS Version - The version of OS being used by the device
    7. 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.

    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

      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"
        }
      }
    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. For details, see Google's Custom dimensions & metrics document.

    Using Google Scripts, you can automate the process of adding custom dimensions in Google Analytics.

    Steps

    Follow these steps to use a Google App Script to create custom dimensions:

    1. Log in to Google.
    2. Navigate to the G Suite Developer Hub and select the Apps Script new blank project.

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

      Script editor
      Script editor
    4. 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)
        }
      }
    5. Replace the function myFunction(){} code block, as shown below, with your custom app script.

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

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

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

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

      Authorization dialog
      Authorization dialog
    11. 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

    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

    Changelog

    See the changelog here.


    Page last updated on 28 Sep 2020