clappr-ga-events-plugin

v2.2.0

Published

3 years ago

Google Analytics Events plugin for Clappr player.

Downloads

0High
0Medium
0Low

kslimani

clappr google analytics events

Clappr Google Analytics Events Tracking Plugin

Google Analytics Event Tracking plugin for Clappr video player.

Usage

Add both Clappr and the plugin scripts to your HTML:

<head>
  <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/clappr@latest/dist/clappr.min.js"></script>
  <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/clappr-ga-events-plugin@latest/dist/clappr-ga-events-plugin.min.js"></script>
</head>

Then just add ClapprGaEventsPlugin into the list of core plugins of your player instance, and the options for the plugin go in the gaEventsPlugin property as shown below.

var player = new Clappr.Player({
  source: "http://your.video/here.mp4",
  plugins: {
    core: [ClapprGaEventsPlugin],
  },
  gaEventsPlugin: {
    trackingId: 'UA-XXXX-Y',
  }
});

trackingId

trackingId required property is the Google Analytics tracking ID / web property ID. The format is UA-XXXX-Y.

createFieldsObject

createFieldsObject optional property is the fields object set in the create method. Default value is undefined which create a default tracker with automatic cookie domain configuration. For more details, read the Create Only Fields reference documentation.

  /* [...] */
  gaEventsPlugin: {
    trackingId: 'UA-XXXX-Y',
    createFieldsObject: {
      name: 'MyTrackerName',
      cookieDomain: 'example.com',
    },
  }
  /* [...] */

eventCategory

eventCategory optional property is the eventCategory set in the send method ("event" hit type) used for event tracking. Default value is Video.

  /* [...] */
  gaEventsPlugin: {
    trackingId: 'UA-XXXX-Y',
    eventCategory: 'MyCustomCategory',
  }
  /* [...] */

eventLabel

eventLabel optional property is the eventLabel set in the send method ("event" hit type) used for event tracking. Default value is the container playback resolved source value.

it's strongly recommended to set this option. Using video source as event label may result into truncated value. Event label maximum length is 500 bytes.

  /* [...] */
  gaEventsPlugin: {
    trackingId: 'UA-XXXX-Y',
    eventLabel: 'MyVideoTitle',
  }
  /* [...] */

eventValueAuto

eventValueAuto optional property is a boolean which indicate if eventValue is automatically set for some events. Default value is false. (default behaviour is to left eventValue undefined)

If this option is enabled, the eventValue is set to :

player position value in seconds for play, pause, stop and ended events
player "seek to" position value in seconds for seek event (may be an unexpected value for LIVE playback with DVR)
player volume percent value for volume event
0 or 1 for fullscreen, highdefinitionupdate, and playbackdvrstatechanged events

If playback type is LIVE, the eventValue is set to elapsed duration since play event in seconds. (It use a Timer instead of referring to player position)

  /* [...] */
  gaEventsPlugin: {
    trackingId: 'UA-XXXX-Y',
    eventValueAuto: true,
  }
  /* [...] */

Note: The event value is truncated using parseInt() function to convert to integer.

eventValueAsLive

eventValueAsLive optional property is a boolean which indicate if "on demand" playback is handled as LIVE playback. Default value is false.

If this option and eventValueAuto are enabled, the eventValue is always set to elapsed duration since play event in seconds.

For consistency, play event value is set to 0 (same as LIVE playback) but ended event value is still set to position. (ie: duration)

This option may be usefull, for example, to track the playing time of "on demand" playback. (stop & pause event values)

This option does NOT affect progressSeconds, progressPercent and progressEachSeconds behaviours.

  /* [...] */
  gaEventsPlugin: {
    trackingId: 'UA-XXXX-Y',
    eventValueAuto: true,
    eventValueAsLive: true,
  }
  /* [...] */

Note: This option is ignored if playback type is LIVE. (eventValueAuto option default behaviour)

eventToTrack

eventToTrack optional property is the player container event list to listen and to send to Google Analytics using eventAction tracking field. The default value is ['play', 'seek', 'pause', 'stop', 'ended', 'volume'].

Note: the list of available events is ['ready', 'buffering', 'bufferfull', 'loadedmetadata', 'play', 'seek', 'pause', 'stop', 'ended', 'volume', 'fullscreen', 'error', 'playbackstate', 'highdefinitionupdate', 'playbackdvrstatechanged']. This is not the complete Clappr container event list. If you think one or more event is needed, just open an issue or a pull request.

Keep in mind that Analytics limit is 200,000 hits per user per day and 500 hits per session. For more details, read Google Analytics Collection Limits and Quotas.

  /* [...] */
  gaEventsPlugin: {
    trackingId: 'UA-XXXX-Y',
    eventToTrack: ['play', 'pause', 'stop'],
  }
  /* [...] */

eventMapping

eventMapping optional property is a plain Object used to set the eventAction value for each container event. Default values are event name list listed above. The value can also be a function (argument value depends on event). Object can be partially filled (merged with default values).

  /* [...] */
  gaEventsPlugin: {
    trackingId: 'UA-XXXX-Y',
    eventMapping: {
      ready: 'MyReadyEventLabel', // default is 'ready'
      buffering: 'MyBufferingEventLabel', // default is 'buffering'
      bufferfull: 'MyBufferfullEventLabel', // default is 'bufferfull'
      loadedmetadata: 'MyLoadedmetadataEventLabel', // default is 'loadedmetadata'
      play: 'MyPlayEventLabel', // default is 'play'
      seek: 'MySeekEventLabel', // default is 'seek'
      pause: function(p) { return 'pause_at_'+p+'_seconds'; }, // default is 'pause'
      stop: 'MyStopEventLabel', // default is 'stop'
      ended: 'MyEndedEventLabel', // default is 'ended'
      volume: 'MyVolumeEventLabel', // default is 'volume'
      fullscreen: 'MyFullscreenEventLabel', // default is 'fullscreen'
      error: 'MyErrorEventLabel', // default is 'error'
      playbackstate: 'MyPlaybackstateEventLabel', // default is 'playbackstate'
      highdefinitionupdate: 'MyHighdefinitionupdateEventLabel', // default is 'highdefinitionupdate'
      playbackdvrstatechanged: 'MyPlaybackdvrstatechangedEventLabel', // default is 'playbackdvrstatechanged'
    },
  }
  /* [...] */

sendPlayOnce

sendPlayOnce optional property is a boolean which indicate if "play" events triggered as the result of "buffer full" during playback are not send to Google Analytics. Default value is false. (default behaviour is to send all "play" events)

"play" event is trigger most of the cases after a "buffer full" event as the result either autoplay, user click play button or user clicked on seek bar.

But "play" event is also trigger after buffer full during playback (slow connection, etc...) resulting in sending additional "play" events to Google Analytics.

If this option is set to true, the "play" event is send only once after video is started, or after a seek. If video pause or stop, then play, the "play" event is send again.

  /* [...] */
  gaEventsPlugin: {
    trackingId: 'UA-XXXX-Y',
    sendPlayOnce: true,
  }
  /* [...] */

stopOnLeave

stopOnLeave optional property is a boolean which indicate if player is paused or stopped when user decides to leave the page. Default value is false.

If this option is set to true, "beacon" transport will be used (if available) to attempt to send the event.

Note: this option may not be supported by all browsers, and therefore is not guaranteed to work.

sendExceptions

sendExceptions optional property is a boolean which indicate if container error events are send to Google Analytics using Exception ("exception" hit type). Default value is false. (default behaviour, if "error" is tracked, is to use "send" hit type like other player events)

If this option is set to true, the 'error' event is automatically added to events to track. (no need to specify 'error' in eventToTrack plugin option)

  /* [...] */
  gaEventsPlugin: {
    trackingId: 'UA-XXXX-Y',
    sendExceptions: true,
  }
  /* [...] */

sendExceptionsMsg

sendExceptionsMsg optional property is a boolean which indicate if resolved error message is send as exception description. Default value is false. (exception description value is "error")

This option must be used with sendExceptions, otherwise is ignored.

Note: this option is disabled by default because error messages may contains sensitive informations.

progressPercent, progressPercentCategory & progressPercentAction

Note: These options are ignored if player container playback type is LIVE. (duration is unknown)

progressPercent optional property is an Array of percentage values (must be integer), where each value is a video progress event to send to Google Analytics. Default value is [].

progressPercentCategory optional property is the eventCategory set to send video progress event. Default value is undefined, which default to eventCategory plugin option value.

progressPercentAction optional property is a Function which return the eventAction set to send video progress event. Default value is function(i) { return 'progress_' + i + 'p' }, where i argument is the video progress percentage value.

Note: If user seek video past a progress event time range, then the "leaped" event is not send.

  /* [...] */
  gaEventsPlugin: {
    trackingId: 'UA-XXXX-Y',
    progressPercent: [25,50,75],
    progressPercentCategory: 'Video percent', // default is 'Video'
    progressPercentAction: function(i) { return i + '%' },
  }
  /* [...] */

Event label value used for video progress events is the eventLabel plugin option value.

progressSeconds, progressSecondsCategory & progressSecondsAction

These optional properties are exactly the same as "progress percent" above, but instead is progress duration in seconds. (except for LIVE, read explanations below)

progressSeconds default value is [].

progressSecondsCategory default value is undefined, which default to eventCategory plugin option value.

progressSecondsAction default value is function(i) { return 'progress_' + i + 's' }, where i argument is the video progress duration value.

If playback type is LIVE, then events are send according time elapsed since play event. If video pause, seek or stop, then events are send again after Nth seconds. (It use a Timer instead of referring to player position)

Note: If user seek video past a progress event time range, then the "leaped" event is not send. (seek is available only if video has DVR feature enabled)

  /* [...] */
  gaEventsPlugin: {
    trackingId: 'UA-XXXX-Y',
    progressSeconds: [10,20,30,40,50],
    progressSecondsCategory: 'Video progress', // default is 'Video'
    progressSecondsAction: function(i) { return i + ' seconds' },
  }
  /* [...] */

progressEachSeconds, progressEachSecondsCategory & progressEachSecondsAction

These optional properties are again exactly the same, but instead send progress event each N seconds.

progressEachSeconds must be a positive integer, is the delay in seconds between two events.

progressEachSecondsCategory default value is undefined, which default to eventCategory plugin option value.

progressEachSecondsAction default value is function(i) { return 'progress_' + i + 's' }, where i argument is the video progress duration value.

If playback type is LIVE, then events are send according time elapsed since play event. If video pause, seek or stop, then events are send again each Nth seconds. (It use a Timer instead of referring to player position)

Note: If user seek video past a progress event time range, then the "leaped" event is not send. (seek is available only if video has DVR feature enabled)

  /* [...] */
  gaEventsPlugin: {
    trackingId: 'UA-XXXX-Y',
    progressEachSeconds: 10,
    progressEachSecondsCategory: 'Video progress', // default is 'Video'
    progressEachSecondsAction: function(i) { return i + ' seconds' },
  }
  /* [...] */

External Interface

If tracker name is provided using the createFieldsObject plugin option, then gaEventsTracker() method is added to Clappr player instance. This method return the Google Analytics tracker instance associated to player.

var player = new Clappr.Player({
  source: "http://your.video/here.mp4",
  plugins: {
    core: [ClapprGaEventsPlugin],
  },
  gaEventsPlugin: {
    trackingId: 'UA-XXXX-Y',
    createFieldsObject: {
      name: 'MyTrackerName'
    },
  }
});

var tracker = player.gaEventsTracker();

Development

Install dependencies :

  yarn

Start HTTP dev server (http://0.0.0.0:8080) :

  npm start