Integrate Gumlet insights with HLS.js player and monitor video playback performance.
HLS.js is a popular player to play videos on the web.
Step 1: Gumlet SDK Installation
The best and easiest way to install gumlet-insights.min.js is by including it in head section of the pages after the hls.JS has been included in the page.
<!-- Include other hlsjs plugin files here -->
<script src="/path/to/hls.js"></script>
<!-- Include gumlet insights sdk after HLS.js -->
<script src="https://cdn.gumlytics.com/insights/1.1/gumlet-insights.min.js"></script>
Step 2: Initialise the player
Initialise the HLSJS player with the appropriate player options and the video URL to be played.
<script type="text/javascript">
var video = document.getElementById('my-video');
var time = new Date().getTime();
var hls = new Hls({
// disable preload
autoStartLoad: false
});
hls.attachMedia(video);
hls.loadSource('<VIDEO URL>');
video.addEventListener('play', function() {
// needed for when preload disabled
hls.startLoad();
});
</script>
Step 3: Create Gumlet Configuration JSON
All the data is associated to a property ID which you need to get from our dashboard. Pass it in the config JSON as property_id. This is the only required field.
There is an option to pass extra data such as the user specific data and video meta data which can be viewed in the dashboard as data breakdowns. A full list of variables is available here -> add link here.
<script type="text/javascript">
// Create the Gumlet Configuration JSON
var gumletConfig = {
property_id: 'PROPERTY_ID_GOES_HERE', // required: please replace with correct property id.
};
</script>
Step 4: Initialise Gumlet SDK
Initialise the Gumlet Insights SDK with the config JSON to start receiving data on your dashboard. Pass the player object which you created in the previous step to Gumlet Insights object.
<script type="text/javascript">
var analytics = gumlet.insights(config);
analytics.registerHLSJSPlayer(hls, {starttime: time});
</script>
Done!
Once you integrate with these steps, you should start seeing data on your customised dashboard.
Full Code Example
<!DOCTYPE html>
<html lang="en" dir="ltr">
<head>
<meta charset="utf-8">
<title></title>
<script src="https://cdnjs.cloudflare.com/ajax/libs/hls.js/1.1.1/hls.min.js"></script>
<script type="text/javascript" src="https://cdn.gumlytics.com/insights/1.1/gumlet-insights.min.js"></script>
</head>
<body>
<h1>Gumlet Insights SDK</h1>
<div id="player" style="width: 400px"></div>
<video id="my-video" preload="true" width="640" height="264" controls></video>
<script type="text/javascript">
var video = document.getElementById('my-video');
var time = new Date().getTime();
var hls = new Hls({
// disable preload
autoStartLoad: false
});
hls.attachMedia(video);
hls.loadSource('https://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8');
video.addEventListener('play', function() {
// needed when preload is disabled
hls.startLoad();
});
// Create the Gumlet Configuration JSON
var config = {
property_id: 'TEST_PROPERTY', // required: please replace with correct property id.
};
var analytics = gumlet.insights(config);
analytics.registerHLSJSPlayer(hls, {starttime: time});
</script>
</body>
</html>
How to?
Add custom data
You can send first party user data to our dashboard via the SDK. While building the configuration to initialise the SDK object you can pass these parameters.
var gumletConfig = {
property_id : 'PROPERTY_ID_GOES_HERE', // required: please replace with correct property id.
userId : '123',
userName : 'Océane Bourgeois',
userEMail : '[email protected]',
userPhone : '(840)-295-4133',
userProfileImage : 'https://assets.gumlet.io/assets/gumlet-logo-white-font.png?w=240&format=auto',
userAddressLine1 : '8774, Rue de la Mairie',
userAddressLine2 : '',
userCity : 'Reims',
userState : 'Landes',
userCountry : 'France',
userZipcode : '83894',
customContentType : 'episode',
customVideoDurationMillis : 2600000, // 43 minutes 20 seconds
customEncodingVariant : 'test1',
customVideoLanguage : 'English',
customVideoId : 'HIMYMSeason1Episode1',
customVideoSeries : 'HIMYMSeason1',
customVideoProducer : 'Ece Tekelioglu',
customVideoTitle : 'Pilot',
customVideoVariantName : '',
customVideoVariant : '',
customPlayerIntegrationVersion : 'v1.1',
customPlayerName : 'Trailer',
customPageType : 'Homepage',
customData1 : '',
customData2 : '',
customData3 : '',
customData4 : '',
customData5 : '',
customData6 : '',
customData7 : '',
customData8 : '',
customData9 : '',
customData10 : ''
};
var gumletInsights = gumlet.insights(gumletConfig);
Change the essential user details being sent to the Gumlet Dashboard.
If the user decides to login after the Gumlet SDK was attached to the player then you can use the following function to update the data being sent to the Gumlet backend.
Use the updateCustomUserData() function available in the SDK.
gumletInsights.updateCustomUserData({
userId : '123',
userName : 'Christelle Robert',
userEMail : '[email protected]',
});
Change the video title that is being played in the player.
If your app supports multiple videos in the same player after it is initialised then you need to tell our SDK to track the new video details after the player finishes playing a video and is about to start the new video.
Use the updateCustomVideoData() function available in the SDK
gumletInsights.updateCustomVideoData({
customVideoTitle : 'Episode2'
})
API Documentation
insights(config)
The Initialise method takes in a config JSON and returns a Gumlet Insights object which is then attached with a player. Only the property id to which data is to be sent is a mandatory parameter, but there is an option to pass custom data as well, the whole list of parameters is available here
// Create the Gumlet Configuration JSON
var gumletConfig = {
property_id: 'PROPERTY_ID_GOES_HERE', // required: please replace with correct property id.
};
var gumletInsights = gumlet.insights(gumletConfig);
registerHLSJSPlayer(player)
The registerHLSJSPlayer method takes in a video.js player object as an argument. After the SDK has been installed and initialised on the page it needs a player object to listen events from. The registerHLSJSPlayer event accepts this player object and attaches the Gumlet Insight object with the player.
If there are multiple player windows on a page please initialise the same number of Gumlet SDK objects and pass the different player objects to it.
Gumlet insights SDK won't start sending data to the dashboard unless the player is registered with it.
analytics.registerHLSJSPlayer(hls, {starttime: time});
updateCustomUserData(data)
Gumlet Insights SDK allows you to pass user data which is stored in the projects main database to allow analysis at user level complete list of user parameters is available here
There is an option to update this data via a function call while the SDK is already initialised with some user data.
gumletInsights.updateCustomUserData({
userId : '123',
userName : 'Christelle Robert',
userEMail : '[email protected]',
userPhone : '(078)-380-95-96',
userProfileImage : 'https://assets.gumlet.io/assets/gumlet-logo-white-font.png?w=240&format=auto',
userAddressLine1 : '8774, Rue de la Mairie',
userAddressLine2 : '',
userCity : 'Reims',
userState : 'Landes',
userCountry : 'France',
userZipcode : '83894',
});
updateCustomVideoData(data)
Gumlet Insights SDK allows you to pass custom data related to a video to easily identify and drill down metrics for a particular video on the dashboard. A complete list of parameters is available here
gumletInsights.updateCustomVideoData({
customContentType : 'episode',
customVideoDurationMillis : 2405000, // 40 minutes 5 seconds
customEncodingVariant : 'test1',
customVideoLanguage : 'English',
customVideoId : 'HIMYMSeason1Episode2',
customVideoSeries : 'HIMYMSeason1',
customVideoProducer : 'Ece Tekelioglu',
customVideoTitle : 'Episode2',
customVideoVariantName : '',
customVideoVariant : '',
})
updateCustomData(data)
Each SDK allows ten additional data points which can be used to a particular use case for an application. The values in these parameters can be anything which needs to be tracked. Each parameter is optional ad accepts alphanumeric values. The whole lit of parameters is available here
gumletInsights.updateCustomData({
customData1 : '',
customData2 : '',
customData3 : '',
customData4 : '',
customData5 : '',
customData6 : '',
customData7 : '',
customData8 : '',
customData9 : '',
customData10 : ''
});