README

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 with vimeo.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.

Usage no npm install needed!