• Overview
• Integration
• API Reference
• Code sample

Overview

We provide a javascript library that you can use to create your own plugin bridge between a particular type of video player you use and our analytics platform.

The Streamhub Analytics JavaScript library ease that development task by exposing  a simple and comprehensible set of predefined JavaScript methods for sending video usage reporting data to the Streamhub platform.

Integration

1. Load the JavaScript library

First, you need to load the Streamhub Analytics JavaScript library by putting the following code inside a HTML script tag.

x.y.z refers to the version of the library you want to use.

The documentation in this page applies to the latest version of the library which is 7.0.0 as of the time of writing. All the available versions of StreamhubAnalytics plugin library are listed on the index page: http://static.streamhub.tv/index.php

You can also use //static.streamhub.tv/analytics/streamhub-analytics.min.js which always points to the latest version of our library.

2. Create an instance of StreamhubAnalytics

The next step is to create a StreamhubAnalytics object. The constructor accepts six parameters detailed below.2. Create an instance of the StreamhubAnalytics class

1. PARTNER_ID [string] provided to you by Streamhub.
2. END_POINT [string] (//stats.streamhub.io) can be changed for testing purposes.
3. PLAYER_ID [string] unique identifier of the player playing the video. It is a unique identifier for the player in both your system and ours.
   Those player Ids can be generated on your side using a UUID online generator: https://www.uuidgenerator.net/ but have to be communicated to us, or we can’t generate a list of unique ids for all your players.
4. IS_LIVE [boolean] tells whether the content is live (‘true’) or VOD (‘false’)
5. USER_ID [string] if a login is required to view the media, you can provide a user identifier here to track your logged users or undefined.
6. ANALYTICS_ID [string] provided to you by Streamhub.

3. Call methods within the library to track events and ticks

Once a library instance has been created, you can access the API methods.

API Reference

The table below lists all methods currently available within the Streamhub Analytics library.

As a minimum, we require the onMediaReady method to be called each time a new media file or stream is about to be played, plus a minutely ticker to be called during playback via the onTicker method.

method name: onMediaReady [mandatory]

parameters: mediaId [String][mandatory]

description: This method must be called to provide the unique identifier of the media about to be played. Most video players provide a mechanism to read the video unique identifier (usually though a ‘metadata’ callback or equivalent. See code sample). This is the perfect place to plug in the call to onMediaReady and provide the required information.

Code sample

Assuming one version of the StreamhubAnalytics library has been loaded from our server:

<!-- x.y.z is the version number of the StreamhubAnalytics library you want to use -->
src="https://static.streamhub.tv/analytics/streamhub-analytics.min.js">

[code language=”javascript”]
var partnerId = "some-partner"; // Youtube, Brightcove, SimpleStream… is generally the platform that hosts your video.
var endPointUrl = "https://stats.streamhub.io";
var playerId = "some-player"; // an identifier for a particular video player in your system. This will provide analytics per type of player.
var isLive = false; // whether your player is providing a live service or a onDemand service
var userId = undefined; // can be used to track your logged users if your service requires authentication
var analyticsId = "your-analytics-id"; // this has been given to you by a Streamhub representative
var firstplay = true; // a convenient variable to track the first time the media is played and call the onMediaStart function accordingly

/**
* Creates the StreamhubAnalytics object providing the required parameters to initialize the library
*/
var shAnalytics = new StreamhubAnalytics( partnerId, endPointUrl, playerId, isLive, userId, analyticsId );

/**
* Here we handle a fictional mediaLoaded event callbacks for a fictional video player accessible via the js variable player
*/
player.on( ‘mediaLoaded’, function( metadata ){
shAnalytics.onMediaReady( metadata.videoId, metadata.bitrate, metadata.title, metadata.description );
});

/**
* Here we handle a fictional playStateChange event callback. We track usage of play and pause event and call the onMediaStart function if the media is played for the first time.
*/
player.on( ‘playStateChange’, function( isPlaying ){
if(isPlaying == true){
if(firstplay){
firstplay = false;
shAnalytics.onMediaStart();
}
shAnalytics.setPaused(false);
}
else
shAnalytics.setPaused(true);
});
/**
* Here we handle the fictional event callback ‘timeUpdate’ providing the current time in the video playback
* make sure currentTimeInSecond has a second resolution (some players API provide this value in milliseconds)
* This is the most important part of the integration as it will keep track of the video views and engagement of
* the person watching the video.
*/
player.on( ‘timeUpdate’, function( currentTimeInSecond /* usually a float value */ ){
shAnalytics.onTick( currentTimeInSecond );
});

player.on( ‘complete’, function( event ){
shAnalytics.onMediaComplete();
});

[/code]

top

© Copyright 2015 Streamhub