This documentation covers tracking in version 3.x of the SDK.
If you are implementing any previous versions of the SDK, you can download the Developers Guides here: Download SDKs
Initial tracking setup
Identify when the user triggers the intention of playback (the user clicks play and/or autoplay is on) and create a MediaObject
instance.
Variable Name | Type | Description |
---|---|---|
name |
string | Non empty string denoting media name. |
id |
string | Non empty string denoting unique media identifier. |
length |
number | Positive number denoting length of media in seconds. Use 0 if length is unknown. |
streamType |
string | |
mediaType |
Type of media (Audio or Video). |
StreamType
constants:
Constant Name | Description |
---|---|
VOD |
Stream type for Video on Demand. |
AOD |
Stream type for Audio on Demand. |
MediaType
constants:
Constant Name | Description |
---|---|
Audio |
Media type for Audio streams. |
Video |
Media type for Video streams. |
var mediaObject = ADB.Media.createMediaObject(<MEDIA_NAME>,
<MEDIA_ID,
<MEDIA_LENGTH>,
<STREAM_TYPE>,
<MEDIA_TYPE>);
Attach metadata
Optionally attach standard and/or custom metadata to the tracking session through context data variables.
Standard metadata
Attaching the standard metadata is optional.
Media metadata keys API Reference - Standard metadata keys - JavaScript
See the comprehensive set of available metadata here: Audio and video parameters
Custom metadata
Create a variable object for the custom variables and populate with the data for this media. For example:
/* Set context data */
var contextData = {};
//Standard metadata
contextData[ADB.Media.VideoMetadataKeys] = "Sample Episode";
contextData[ADB.Media.VideoMetadataKeys] = "Sample Show";
//Custom metadata
contextData["isUserLoggedIn"] = "false";
contextData["tvStation"] = "Sample TV Station";
Track the intention to start playback
To begin tracking a media session, call trackSessionStart
on the Media Heartbeat instance:
var mediaObject = ADB.Media.createMediaObject("video-name",
"video-id",
60.0,
ADB.Media.StreamType.VOD,
ADB.Media.MediaType.Video);
var contextData = {};
//Standard metadata
contextData[ADB.Media.VideoMetadataKeys] = "Sample Episode";
contextData[ADB.Media.VideoMetadataKeys] = "Sample Show";
//Custom metadata
contextData["isUserLoggedIn"] = "false";
contextData["tvStation"] = "Sample TV Station";
tracker.trackSessionStart(mediaObject, contextData);
trackSessionStart
tracks the user intention of playback, not the beginning of the playback. This API is used to load the data/metadata and to estimate the time-to-start QoS metric (the time duration between trackSessionStart
and trackPlay
).
If you are not using contextData, simply send an empty object for the data
argument in trackSessionStart
.
Track the actual start of playback
Identify the event from the media player for the beginning of the playback, where the first frame of the media is rendered on the screen, and call trackPlay
:
tracker.trackPlay();
Update playhead value
When media playhead changes, notify the SDK by calling the mediaUpdatePlayhead
API.
For video-on-demand (VOD), the value is specified in seconds from the beginning of the media item.
For live streaming, if the player does not provide information about the content duration, the value can be specified as the number of seconds since midnight UTC of that day.
tracker.updatePlayhead(position)
Consider the following when calling the tracker.updatePlayhead
API:
tracker.updatePlayhead
API at least once per second.Track the completion of playback
Identify the event from the media player for the completion of the playback, where the user has watched the content until the end, and call trackComplete
:
tracker.trackComplete();
Track the end of the session
Identify the event from the media player for the unloading/closing of the playback, where the user closes the media and/or the media is completed and has been unloaded, and call trackSessionEnd
:
tracker.trackSessionEnd();
trackSessionEnd
marks the end of a tracking session. If the session was successfully watched to completion, where the user watched the content until the end, ensure that trackComplete
is called before trackSessionEnd
. Any other track*
API call is ignored after trackSessionEnd
, except for trackSessionStart
for a new tracking session.
Track all possible pause scenarios
Identify the event from the media player for pause and call trackPause
:
tracker.trackPause();
Pause Scenarios
Identify any scenario in which the media player will pause and make sure that trackPause
is properly called. The following scenarios all require that your app call trackPause()
:
Identify the event from the player for play and/or resume from pause and call trackPlay
:
tracker.trackPlay();
This may be the same event source that was used in Step 4. Ensure that each trackPause()
API call is paired with a following trackPlay()
API call when the playback resumes.