Vimeo Analytics.js Plugin
Automatically track Vimeo video player events as Segment events.
Installation
The plugin is distributed as both an NPM package and as a direct export via a CDN.
CDN
Use a built version of the plugin from the jsDelivr CDN. Simply add the following script tag to the head
of your site. VimeoAnalytics
will be available as part of a globally accessible object called window.analyticsPlugins
.
<script src="https://cdn.jsdelivr.net/npm/@segment/vimeo-analytics.js-plugin@3/dist/vimeo.min.js"></script>
The above url will download the minified version of the plugin which you should use in production. To access the unminified version for use in development, simply replace
vimeo.min.js
withvimeo.js
NPM
// `npm install @segment/vimeo-analytics.js-plugin --save` OR
// `yarn add @segment/vimeo-analytics.js-plugin
const VimeoAnalytics = require('@segment/vimeo-analytics.js-plugin');
Initializing
To initialize the plugin you will need to create a new instance of the VimeoAnalytics
class and pass in the Vimeo.Player instance running on your page as the first argument and an array of objects, each containing information about the video(s) that are accessible in the player, as the second argument. The metadata object for each video should conform to our spec.
Please read more about the constructor function in the API documentation.
Next, you will need to start the plugin by calling it's initialize
method. The example below assumes you are using the CDN installation option.
<iframe src="https://player.vimeo.com/video/76979871" width="640" height="360" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
<script src="https://player.vimeo.com/api/player.js"></script>
<script>
var iframe = document.querySelector('iframe');
var player = new Vimeo.Player(iframe);
var VimeoAnalytics = window.analyticsPlugins.VimeoAnalytics
var vimeoAnalytics = new VimeoAnalytics(player, [{
sessionId: 'abcd-efgh-ijklm',
// The `assetId` must be Vimeo video Id.
assetId: '76979871',
program: 'Planet Earth',
title: 'Seasonal Forests',
episode: 10,
description: 'David Attenborough reveals the greatest woodlands on earth.',
season: 1,
genre: 'Documentary',
publisher: 'BBC',
fullEpisode: true,
keywords: ['nature', 'forests', 'earth']
}])
vimeoAnalytics.initialize()
</script>
The plugin will now begin listening for the Vimeo Player lifecycle events and responding to them with Segment video events.
API
Constructor
new VimeoAnalytics(player, metadata)
The VimeoAnalyics
constructor takes as it's arguments the instance of the Vimeo Player you would like to track events for and an Array of metadata about the video(s) that are accessible in the player.
Please ensure that the assetId
you pass in with each ContentEventObject is the Vimeo Id for that video.
Arguments
-
player
VimeoPlayer -
metadata
Array[ContentEventObject]
Initialize
vimeoAnalytics.initialize()
The .initialize
method will bootstrap all the supported event listeners outlined below.
Events
Play
Play events from the Vimeo Player will trigger Video Content Started and Video Playback Started Segment events. If the video player was previously paused, the play event will instead trigger a Video Playback Resumed event.
Pause
Pause events from the Vimeo Player will trigger Video Playback Paused Segment events.
Ended
Ended events from the Vimeo Player will trigger Video Playback Completed and Video Content Completed Segment events.
Time Update
Time Update events from the Vimeo Player will trigger Video Content Playing "heartbeat" events every 10 seconds.