Track core playback using JavaScript 3.x

IMPORTANT

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

  1. 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.

    createMediaObject API

    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>);
    
  2. Attach metadata

    Optionally attach standard and/or custom metadata to the tracking session through context data variables.

    • Standard metadata

      NOTE

      Attaching the standard metadata is optional.

    • 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";
      
  3. 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);
    
    IMPORTANT

    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).

    NOTE

    If you are not using contextData, simply send an empty object for the data argument in trackSessionStart.

  4. 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();
    
  5. 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();
    
  6. 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();
    
    IMPORTANT

    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.

  7. 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():

    • The user explicitly hits pause in the app.
    • The player puts itself into the Pause state.
    • (Mobile Apps) - The user puts the application into the background, but you want the app to keep the session open.
    • (Mobile Apps) - Any type of system interrupt occurs that causes an application to be backgrounded. For example, the user receives a call, or a pop up from another application occurs, but you want the application to keep the session alive to give the user the opportunity to resume the media from the point of interruption.
  8. Identify the event from the player for play and/or resume from pause and call trackPlay:

    tracker.trackPlay();
    
    TIP

    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.

  • Tracking scenarios: VOD playback with no ads
  • Sample player included with the JavaScript SDK for a complete tracking example.

On this page