guide.md

Usage guide

• Getting started
  • Setup
  • Configuration
• Using Data Layer Variables
• Tracking Player Custom Events
• Tracking Player UI Elements Clicks
• Player CSS Elements Selectors List

Getting started

Setup

First include the plugin script bundle after kaltura-player script in your web page.

<script src="https://raw.githack.com/kaltura/kaltura-player-js/master/dist/kaltura-ovp-player.js"></script>
<script src="./playkit-google-tag-manager.js"></script>

Add the plugin name (googleTagManager) to the player config under the plugins section along with the rest of plugins.

const config = {
    targetId: 'player-placeholder',
    provider: {
        partnerId: <YOUR PARTBER ID>,
    },
    plugins: {
       googleTagManager: {},
    }
  };

const player = KalturaPlayer.setup(config);

Configuration

Configure your container id

The container id is displayed on your admin tab in your Google Tag Manager dashboard (formatted as GTM-XXXXXX)

const config = {
  targetId: 'player-placeholder',
  provider: {
    partnerId: <YOUR PARTBER ID>,
  },
  plugins: {
    googleTagManager: {
      containerId: <YOUR CONTAINER ID>
    },
  }
};

const player = KalturaPlayer.setup(config);

Tracking player custom events

In order to track player custom events - you have two configuration options

1. Define your own list of events.
2. Track all events from a particular events' category.

The event categories are:

• Core Events
• UI Events
• Playlist Events
• Cast Events

You can also combine both options.

Custom list configuration option

Pass string array of event names:

const config = {
    ...
  },
  plugins: {
    googleTagManager: {
      containerId: 'GTM-XXXXXXX',
      customEventsTracking: {
        custom: ['play', 'pause', 'seeked', 'sourceselected']
      },
    }
  }
};

Preset lists configuration option

Just turn on the desired events category option (all are set to false by default):

const config = {
    ...
  },
  plugins: {
    googleTagManager: {
      containerId: 'GTM-XXXXXXX',
      customEventsTracking: {
        custom: [...],
        preset: {
           coreEvents: true,
           UIEvents: true,
           playlistEvents: true,                   
           castEvents: true                                  
        }
      },
    }
  }
};

The full list of events can be found here:

Core Events
Ads Events
UI Events
Playlist Events
Cast Events

Using Data Layer Variables

Our Player Custom Events payload are available as Data Layer Variable, in order to use them, you would just need to set Data Layer Variable one time! with dynamic key as explained bellow.

The Data Layer Variable key would always be at the pattern of Custom Event Name concatenated with the string -payload

For example: play-payload / seeked-payload / sourceselectd-payload and so on.

Note: not all player custom events have a payload, in that case, the value would be undefined

Set up the data layer variable

Open your Google Tag Manager Workspace and follow these steps:

1. Click Variables.
2. Under User-Defined Variables, click New.
3. Click Variable Configuration and select Data Layer Variable as the variable type.
4. In the Data Layer Variable Name field, click on the '+' icon and select the Custom Event Built-In Variable and add add the suffix -payload to the variable name
5. In most cases you should leave the Data Layer Version set to the default value of Version 2.
6. Save the variable.

Now you can use that Variable everywhere in your tag configuration

Tracking player UI elements clicks

In order to track some Player elements Clicks when condition of CSS selectors are true, You should use the Click Classes option of the conditions list.

(If you do not see the Click Classes option, you should add it through the Variables tab - go to Variables > Built-In Variables > Configure and select Click Classes from the list)

Player elements are identified by css class selectors. (The Player elements do not contain id selectors).

Use the following css class selectors:

Control Element	Class Name
PLAY / PAUSE	playkit-control-play-pause
PLAY	playkit-icon-play
PAUSE	playkit-icon-pause
REPLAY	playkit-icon-start-over
REWIND	playkit-icon-rewind-10
FORWARD	playkit-icon-forward-10
VOLUME / MUTE	playkit-icon-volume-mute
LANGUAGE	playkit-icon-language
SETTINGS	playkit-icon-settings
PICTURE IN PICTURE	playkit-control-picture-in-picture
PICTURE IN PICTURE / START	playkit-icon-picture-in-picture-star
PICTURE IN PICTURE / STOP	playkit-icon-picture-in-picture-stop
FULLSCREEN / MAXIMIZE	playkit-icon-maximize
FULLSCREEN / MINIMIZE	playkit-icon-minimize

For capturing all player controls clicks -select the 'contains' or 'start with' condition from the conditions and pass the playkit-icon class as the value.

Example - Single Selection

Example - Multiple Selection

Full example

Full example

Custom event trigger

Custom event trigger

About Player Events

Player Events