Radiant Media Player

Analytics API



Documentation sections


Player API analytics methods

Analytics data can be delivered by the player with JavaScript. See our player API documentation for a better understanding of how to use the player API and a list of generally available API methods. In addition we provide the following analytics-oriented API methods:

getTimeViewed()
rmp.getTimeViewed()

This methods returns a Number expressed in milliseconds that represents the cumulative time viewed for the current player instance. Returns -1 if not available. This number can exceed content duration if the same part of content is viewed multiple times for a given player session.

getPercentViewed()
rmp.getPercentViewed()

This methods returns a Number expressed in % that represents the cumulative percent viewed for the current player instance (example 20 for 20%). This is calculated against content duration. It will only return valid for on-demand content as for live/DVR content the duration is unknown. Returns -1 if not available. This number can exceed 100% if the same part of content is viewed multiple times for a given player session.

getTimeReady()
rmp.getTimeReady()

This methods returns a Number expressed in milliseconds that represents the time for the player to be ready, i.e. fully appended to DOM, ready to receive user interaction (or autoplay if required) and API calls. It computed from the moment init player method is called on player. See example below to also take into account the time required to load Radiant Media Player core library (rmp.min.js). Returns -1 if not available.

getStartUpTime()
rmp.getStartUpTime()

This methods returns a Number expressed in milliseconds that represents the time needed for the player to display the first frame of content or pre-roll ad when available, whichever comes first, after the viewer has requested playback through an initial user interaction (or when autoplay is requested). Returns -1 if not available. This method should be queried when the startuptimeavailable player event fires.

Computing time to load Radiant Media Player core file library

In addition to getting time to reach player ready state (getTimeReady), you may want to get the time it took for Radiant Media Player core library (rmp.min.js) to load, either from our cloud service or when self-hosted. The code below shows an example of how to get this data:

<!-- Here we start our timer to compute time to load rmp.min.js -->
<script>
var timeAfterLoad;
var timeBeforeLoad = Date.now();
</script>
<script src="https://cdn.radiantmediatechs.com/rmp/4.10.5/js/rmp.min.js" 
  integrity="sha384-C/ULeCJDlenAbw9Hm+dhOlswTP+pmQHD+i4ihKhNzkzPz02MB5xJMUD1uUpT8kcY"
  crossorigin="anonymous"></script>
<div id="rmpPlayer"></div>
<script>
var bitrates = {
  hls: 'https://your-hls-url.m3u8'
};
var settings = {
  licenseKey: 'your-license-key',
  bitrates: bitrates,
  width: 640,
  height: 360,
  poster: 'https://your-poster-url.jpg'
};  
var elementID = 'rmpPlayer';
var rmp = new RadiantMP(elementID);
var rmpContainer = document.getElementById(elementID);
// We wire our events before calling init
rmpContainer.addEventListener('ready', function() {
  // ready event fires this is when the timer for getTimeReady API method stops
  var timeToLoad = timeAfterLoad - timeBeforeLoad;
  var timeToReady = rmp.getTimeReady();
  var totalReadyTime = timeToLoad + timeToReady;
  // print our data to console
  console.log('timeToLoad is ' + timeToLoad + ' ms');
  console.log('timeToReady is ' + timeToReady + ' ms');
  console.log('totalReadyTime is ' + totalReadyTime + ' ms');
});
// Here we also print the player start-up time
rmpContainer.addEventListener('startuptimeavailable', function () {
  var startupTime = rmp.getStartUpTime();
  console.log('startupTime is ' + startupTime + ' ms');
});
// Here we stop our timer to compute time to load rmp.min.js
// In this case we also add the time it took to create Radiant Media Player instance and to wire our app logic
timeAfterLoad =  Date.now();
// init is called this is when the timer for getTimeReady API method starts
rmp.init(settings);
</script>

Make sure to review our performance guide to get the most out of Radiant Media Player.


Player API analytics events

Player events can be used to track analytics data. See our player API events documentation for a list of generally available player events.


Heatmap player API

A heatmap represents which parts of your content are actually being consumed by your audience. For example in the case of soccer when a goal happens viewers will tend to replay a reduced section of the content multiple times indicating a clear area of interest. Better than words an image:

heatmap representation

The idea here is to provide API player methods in order to reconstruct a heatmap for a given asset. This is only available for on-demand video. Live/DVR content have fluctuant duration and thus a heatmap cannot be drawn.

The heatmap analytics API is a client-side API. In order to get to a complete solution you will need to send the information provided by the player to a remote logging server where heatmap analytics data can be stored and processed. This last part is for you to set up.

heatMap: Boolean
heatMap: true

This is a player setting. In order to use Radiant Media Player heatmap feature you must set this setting to true. Default: false.

heatMapAccuracy: Number
heatMapAccuracy: 20

This is a player setting. The default is 20 which means that the content will be cut into 20 segments. Each segment represent 5% of the content duration. Ticks are logged for each of those 5% segments. You can increase accuracy up to 100. With a 100 value the player ticks will be logged within segments that represent 1% of the content duration.

getRawHeatMap
rmp.getRawHeatMap()

This API method returns an Array. The array size is dictated by the heatMapAccuracy setting (see below). Each item of the array consists of an incremental number of player ticks. A player tick is registered each time the timeupdate event fires.
Typically after a certain amount of time playing a video the getRawHeatMap method may return something like:
[18, 19, 18, 19, 81, 84, 45, 36, 17, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]

This would be the output for the heatMapAccuracy default value of 20. This means that ticks are logged within segments that represent 5% (1/20) of the content. The first number in the array - 18 - means that when the getRawHeatMap method was called 18 ticks have been registered for the first 5% of the content. At index 4 of the array we can see an increase in ticks, 81 then at index 5, 84 ticks. This means that this area of the video has been watched more intensively by the viewer while the second half of the video was completely ignored.

This can effectively tell you which parts of a content work for your audience.
In order to draw a clear picture you will need to query the getRawHeatMap method at regular intervals or when the player session ends (e.g. a browser tab/window is closed) and to send those data to a logging server for post-processing.

You are most likely going to have to play around with the above methods/player setting in order to grab the full scope of the heatmap concept and how powerful it can be in order to achieve a successful online video strategy.


3rd-party analytics service integration

By default, Radiant Media Player integrates with Google Analytics. You could want to build your own custom Google Analytics integration or support other analytics services like comScore, Adobe Site Catalyst or Nielsen. This can be achieved through our player API. Assuming your analytics service can send and receive information through JavaScript, all player API events and methods can be tracked.

In the example below we show how to retrieve commonly needed analytics information through the player API.

<script src="https://cdn.radiantmediatechs.com/rmp/4.10.5/js/rmp.min.js" 
  integrity="sha384-C/ULeCJDlenAbw9Hm+dhOlswTP+pmQHD+i4ihKhNzkzPz02MB5xJMUD1uUpT8kcY"
  crossorigin="anonymous"></script>
<div id="rmpPlayer"></div>
<script>
var bitrates = {
  hls: 'https://your-hls-url.m3u8'
};
var settings = {
  licenseKey: 'your-license-key',
  bitrates: bitrates,
  width: 640,
  height: 360,
  ads: true,
  adTagUrl: 'https://www.radiantmediaplayer.com/vast/tags/inline-linear.xml', 
  poster: 'https://your-poster-url.jpg'
};
var elementID = 'rmpPlayer';
var rmp = new RadiantMP(elementID);

// Player container which will receive API events
var rmpContainer = document.getElementById(elementID);

// We attached our listeners to be notified of player events
rmpContainer.addEventListener('ready', function() {
  // player is ready
  // TODO: send data to your custom analytics service
}); 

rmpContainer.addEventListener('error', function() {
  // player has encountered a fatal error preventing playback
  // TODO: send data to your custom analytics service
});

rmpContainer.addEventListener('bufferstalled', function() {
  // current buffer is empty - media playback is stopped until enough buffer has been downloaded to resume playback
  // TODO: send data to your custom analytics service
});

rmpContainer.addEventListener('buffernotstalledanymore', function() {
  // player has resumed playback after a bufferstalled event (e.g. it exits buffering state)
  // TODO: send data to your custom analytics service
});

rmpContainer.addEventListener('ended', function() {
  // player has ended content
  // TODO: send data to your custom analytics service
});

rmpContainer.addEventListener('timeupdate', function() {
  // player has moved its playhead
  var currentTime = rmp.getCurrentTime(); // current playback position in milliseconds
  if (currentTime > XX) {
    var fullscreen = rmp.getFullscreen(); // current fullscreen state of the player
    var volume = rmp.getVolume(); // current player volume 
    // TODO: send data to your custom analytics service
  }
});

rmpContainer.addEventListener('adimpression', function() {
  // player has pinged the VAST impression URL
  // TODO: send data to your custom analytics service
});

// Player initialisation only after API events are registered
rmp.init(settings);
</script>
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License.