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.


    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.


    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:


    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 Player has been loaded and is ready for playback
    Video Impression bcvideo_video_impression Video has been loaded into a player and is ready for playback
    Video View bcvideo_video_view 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 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 Control is handed over to an advertising agent by the playback platform
    Ad End bcvideo_ad_end Control is handed back from the advertising agent to the playback platform
    Error bcvideo_error A fatal error has occurred which disrupts the playback experience
    Video Complete bcvideo_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. Enter the details:

      • Data Layer Variable Name - Name of the variable
      • Data Layer Version - Version 2
    6. Select Save.

      Save variable
      Save variable
    7. 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
      • 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
    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. 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)
      • paramsToTrack - Custom dimensions you want to track
      • eventsToTrack - Events 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", 
        "paramsToTrack": {
        "eventsToTrack": {
          "video_impression": "Video Impression", 
          "video_view": "Video View",
          "video_complete": "Video Complete", 
          "play_request": "Play Request",
          "video_engagement": "Video Engagement", 
          "ad_start": "Ad Start",
          "ad_end": "Ad End",
          "player_load": "Player Load",
          "error": "Error"
    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. By using Google Scripts, you can automate the process of adding custom dimensions in Google Analytics.

    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],
          //This create a request to the new custom dimension 
          // 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.
    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

    Page last updated on 12 Aug 2022