Track core playback on Chromecast track-core-playback-on-chromecast

This documentation covers tracking in version 2.x of the SDK.

If you are implementing a 1.x version of the SDK, you can download 1.x 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.

    MediaObject API reference:


    code language-none
    mediaObject =<name>, <id>, <duration>, <streamType>, <mediaType>);

    StreamType constants:

    ADBMobile Media

    MediaType constants:

    ADBMobile Media

  2. Attach video metadata

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

    • Standard video metadata

      Implement standard metadata on Chromecast

      note note
      Attaching the standard video metadata object to the media object is optional.
    • Custom metadata

      Create a variable object for the custom variables and populate with the data for this video. For example:

      code language-js
      /* Set custom context data */
      var customVideoMetadata = {
          isUserLoggedIn: "false",
          tvStation: "Sample TV station",
          programmer: "Sample programmer"
  3. Track the intention to start playback

    To begin tracking a media session, call trackSessionStart on the media object.

    code language-none, customVideoMetadata);
    note important
    trackSessionStart tracks the user intention of playback, not the beginning of the playback. This API is used to load the video data/metadata and to estimate the time-to-start QoS metric (the time duration between trackSessionStart and trackPlay).
    note note
    The second value is the custom video metadata object name that you created in step 2. If you are not using custom video metadata, simply send an empty object for the data argument in trackSessionStart, as shown in the commented out line in the iOS example above.
  4. Track the actual start of playback

    Identify the event from the video player for the beginning of the video playback, where the first frame of the video is rendered on the screen, and call trackPlay:

    code language-none;
  5. Update playhead value

    Update mediaUpdatePlayhead’ position value multiple times when the playhead changes.
    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.

    code language-none
    note note
    Consider the following when calling the media.updatePlayhead API:
    • When using progress markers, the content duration is required and the playhead needs to be updated as number of seconds from the beginning of the media item, starting with 0.
    • When using media SDKs, you must call the media.updatePlayhead API at least once per second.
  6. Track the completion of playback

    Identify the event from the video player for the completion of the video playback, where the user has watched the content until the end, and call trackComplete:

    code language-none;
  7. Track the end of the session

    Identify the event from the video player for the unloading/closing of the video playback, where the user closes the video and/or the video is completed and has been unloaded, and call trackSessionEnd:

    code language-none;
    note important
    trackSessionEnd marks the end of a video 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 video tracking session.
  8. Track all possible pause scenarios

    Identify the event from the video player for video pause and call trackPause:

    code language-none;

    Pause Scenarios

    Identify any scenario in which the Video 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 video from the point of interruption.
  9. Identify the event from the player for video play and/or video resume from pause and call trackPlay:

    code language-none;
    note 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 video playback resumes.
  • Tracking scenarios: VOD playback with no ads
  • Sample player included with the Chromecast SDK for a complete tracking example.