Track core playback on Android track-core-playback-on-android
This documentation covers tracking in version 2.x of the SDK.
-
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.table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 3-align-center 7-align-center 11-align-center 15-align-center 19-align-center 23-align-center Variable Name Description Required name
Media name Yes mediaId
Media unique identifier Yes length
Media length Yes streamType
Stream type (see StreamType constants below) Yes mediaType
Media type (see MediaType constants below) Yes StreamType
constants:table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 Constant Name Description VOD
Stream type for Video on Demand. LIVE
Stream type for Live content. LINEAR
Stream type for Linear content. AOD
Stream type for Audio On Demand AUDIOBOOK
Stream type for Audio Book PODCAST
Stream type for Podcast MediaType
constants:table 0-row-2 1-row-2 2-row-2 Constant Name Description Audio
Media type for Audio streams. Video
Media type for Video streams. code language-none MediaHeartbeat.createMediaObject(<MEDIA_NAME>, <MEDIA_ID>, <MEDIA_LENGTH>, <STREAM_TYPE>, <MEDIA_TYPE>);
-
Attach metadata
Optionally attach standard and/or custom metadata objects to the tracking session through context data variables.
-
Standard metadata
Implement standard metadata on Android
note note NOTE Attaching the standard metadata object to the media object is optional. - Media metadata keys API Reference - Standard metadata keys - Android
- See the comprehensive set of available video metadata here: Audio and video parameters
-
Custom metadata
Create a dictionary for the custom variables and populate with the data for this media. For example:
code language-java HashMap<String, String> mediaMetadata = new HashMap<String, String>(); mediaMetadata.put("isUserLoggedIn", "false"); mediaMetadata.put("tvStation", "Sample TV Station"); mediaMetadata.put("programmer", "Sample programmer");
-
-
Track the intention to start playback
To begin tracking a media session, call
trackSessionStart
on the Media Heartbeat instance. For example:code language-java public void onVideoLoad(Observable observable, Object data) { _heartbeat.trackSessionStart(mediaInfo, mediaMetadata); }
note tip TIP The second value is the custom media metadata object name that you created in step 2. note important IMPORTANT trackSessionStart
tracks the user intention of playback, not the beginning of the playback. This API is used to load the media data/metadata and to estimate the time-to-start QoS metric (the time duration betweentrackSessionStart
andtrackPlay
).note note NOTE If you are not using custom media metadata, simply send an empty object for the second argument in trackSessionStart
. -
Track the actual start of playback
Identify the event from the media player for the beginning of the media playback, where the first frame of the media is rendered on the screen, and call
trackPlay
:code language-java // Video is rendered on the screen) and call trackPlay. public void onVideoPlay(Observable observable, Object data) { _heartbeat.trackPlay(); }
-
Track the completion of playback
Identify the event from the media player for the completion of the media playback, where the user has watched the content until the end, and call
trackComplete
:code language-java public void onVideoComplete(Observable observable, Object data) { _heartbeat.trackComplete(); }
-
Track the end of the session
Identify the event from the media player for the unloading/closing of the media playback, where the user closes the media and/or the media is completed and has been unloaded, and call
trackSessionEnd
:code language-java // Closes the media and/or the media completed and unloaded, // and call trackSessionEnd(). public void onMainVideoUnload(Observable observable, Object data) { _heartbeat.trackSessionEnd(); }
note important IMPORTANT trackSessionEnd
marks the end of a media tracking session. If the session was successfully watched to completion, where the user watched the content until the end, ensure thattrackComplete
is called beforetrackSessionEnd
. Any othertrack*
API call is ignored aftertrackSessionEnd
, except fortrackSessionStart
for a new media tracking session. -
Track all possible pause scenarios
Identify the event from the media player for media pause and call
trackPause
:code language-java public void onVideoPause(Observable observable, Object data) { _heartbeat.trackPause(); }
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 calltrackPause()
:- 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.
-
Identify the event from the player for media play and/or media resume from pause and call
trackPlay
.code language-java // trackPlay() public void onVideoPlay(Observable observable, Object data) { _heartbeat.trackPlay(); }
note tip TIP This may be the same event source that was used in Step 4. Ensure that each trackPause()
API call is paired with a followingtrackPlay()
API call when the media playback resumes.
See the following for additional information on tracking core playback:
- Tracking scenarios: VOD playback with no ads
- Sample player included with the Android SDK for a complete tracking example.