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 the jsDelivr CDN.

CDN

To use a built version of the plugin from the 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@/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 --save` OR
// `yarn add @segment/vimeo-analytics

const VimeoAnalytics = require('@segment/vimeo-analytics');

Getting Started

To beging using the plugin you will need to generate an Access Token in Vimeo. The plugin will use this token to access metadata about the video content being played.

Vimeo provides documentation outlining this process here. Please ensure you are carefully selecting your access scopes! The plugin only needs to read information about your video(s).

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 your Vimeo Access Token as the second.

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 distribution 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, 'XXXXXXXXXXXXXXXXXXXXXXXXXXXX0365');

    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, accessToken);

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
accessToken String

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!