Mobile SDK - Implementing Video Analytics on Android

The Mobile SDK Video module supplies numerous events for you to connect to your analytics service of choice.

Events are returned through the media player callback trackMediaEvents(). You can read more about trackMediaEvents() in the Getting Started guide. This method contains four callback methods, and can be implemented like this:

mediaPlayer.trackMediaEvents(object: ArcVideoEventsListener {
    override fun onVideoTrackingEvent(type: trackingType?, videoData: TrackingVideoTypeData?) {
    }
    override fun onSourceTrackingEvent(type: TrackingType?, source: TrackingSourceTypeData?) {
    }
    override fund onError(type: TrackingType?, video: TrackingErrorTypeData?) {
    }
    override fun onAdTrackingEvent(type: TrackingType?, adData: TrackingAdTypeData?) {
    }
})

The data returned with each callback method depends on the method. This signature for each of these data types is:

sealed class TrackingTypeData {
    data class TrackingVideoTypeData(
        var position: Long? = null,//position within the video
        var percentage: Int? = null,//percentage of video played
        var arcVideo: ArcVideo? = null,//video object being played
        var sessionId: String? = null//unique session ID for the video (livestream only)
    ) : TrackingTypeData()

    data class TrackingAdTypeData(
        var position: Long? = null,//position within the video
        var arcAd: ArcAd? = null,//ad object
        var sessionId: String? = null//unique session ID for the video (livestream only)
    ) : TrackingTypeData()

    data class TrackingSourceTypeData(
        var position: Long? = null,//position within the video
        var source: String? = null,//identifier for the source
        var sessionId: String? = null//unique session ID for the video (livestream only)
    ) : TrackingTypeData()

    data class TrackingErrorTypeData(
        var arcVideo: ArcVideo? = null, //video object being played
        var sessionId: String? = null,//unique session ID for the video (livestream only)
        var adData: VideoAdAvail? = null//avail data that caused failure
    ) : TrackingTypeData()
}

Events available

Event	Description
`ON_PLAY_STARTED`	Reported when video playback starts.
`ON_PLAY_COMPLETED`	Reported when video playback completes.
`ON_PLAY_PAUSED`	Reported when video playback is paused.
`ON_PLAY_RESUMED`	Reported when video playback is resumed
`ON_OPEN_FULL_SCREEN`	Reported when the user enters full screen mode.
`ON_CLOSE_FULL_SCREEN`	Reported when the user exits full screen mode.
`ON_SHARE`	Sends a pre-configured event and url when share button is clicked.
`VIDEO_PERCENTAGE_WATCHED`	Reported when video progress is 25%, 50%, and 75% completed
`ON_ERROR_OCCURRED`	Reported when an error involving cast occurs.
`ON_MUTE`	Reported when the user mutes the video.
`ON_UNMUTE`	Reported when the user turns off mute on a muted video.
`VIDEO_25_WATCHED`	Reported when the video playback reaches 25%.
`VIDEO_50_WATCHED`	Reported when the video playback reaches 50%.
`VIDEO_75_WATCHED`	Reported when the video playback reaches 75%.
`PREROLL_AD_STARTED`	Reported when a preroll ad starts playing.
`PREROLL_AD_COMPLETED`	Reported when a preroll ad completes playing.
`MIDROLL_AD_STARTED`	Reported when a midroll ad starts playing.
`MIDROLL_AD_COMPLETED`	Reported when a midroll ad completes playing.
`ALL_MIDROLL_AD_COMPLETE`	Fired when a set of midroll ads is complete and the video playback resumes.
`POSTROLL_AD_STARTED`	Reported when a postroll ad starts playing.
`POSTROLL_AD_COMPLETED`	Reported when a postroll ad completes playing.
`MIDROLL_AD_25, MIDROLL_AD_50, MIDROLL_AD_75`	Reported when the midroll ad playback reaches the specified percentage.
`AD_CLICKTHROUGH`	Fired when an ad is clicked. This will return the beacon URL for the ad.
`AD_COMPANION_INFO`	Fired when this information for the ad is passed from the server. It will be returned through the data element of the callback.
`AD_MEDIA_FILES`	Fired when this information for the ad is passed from the server. It will be returned through the data element of the callback.
`AD_SKIPPED`	Reported when the user selects to skip an ad.
`AD_SKIP_SHOWN`	Reported when the skip button becomes visible in the player window
`AD_IMPRESSION`	`Not implemented yet.`
`ON_PLAYER_TOUCHED`	Fired when the player is touched regardless of if it is playing an ad or a video. If it is sent when an ad is playing the data returned will be of type `TrackingAdTypeData`. If it is sent during video playback, it will return the ID of the video as a string.
`ERROR_PLAYLIST_EMPTY`	Reported when the user tries to play an empty playlist
`SUBTITLE_SELECTION`	This event is returned through the `onSourceTrackingEvent` callback. It returns a string as its data that is the language selected for the closed captioning. It is only called if the closed caption dialog is used for selection.
`BEHIND_LIVE_WINDOW_ADJUSTMENT`	Triggered when pause on a live stream is on long enough that the current window is no longer valid so the player has to jump to the current window. This is caught and handled, but an event is fired when video jumps position.
`NEXT_BUTTON_PRESSED`	Triggered when the next button is clicked.
`PREV_BUTTON_PRESSED`	Triggered when the previous button is clicked.
`MALFORMED_AD_AVAIL`	Triggered when the Avail data is not as expected.
`BACK_BUTTON_PRESSED`	Triggered when the back button is clicked (not the physical device button but back button within playback control view.
`AD_PAUSE`	Triggered when an ad is paused.
`AD_RESUME`	Triggered when an ad is resumed.

Example

The following is an example of implementing a callback method:

mediaPlayer.trackMediaEvents(object : ArcVideoEventsListener {
    override fun onVideoTrackingEvent(type: TrackingType, videoData: TrackingTypeData.TrackingVideoTypeData) {
        when (type) {
            TrackingType.ON_MUTE -> {
            }
            TrackingType.ON_UNMUTE -> {
            }
            TrackingType.ON_PLAY_STARTED -> {
            }
            TrackingType.ON_PLAY_COMPLETED -> {
            }
            TrackingType.VIDEO_PERCENTAGE_WATCHED -> {
            }
        }
    }
    override fun onAdTrackingEvent(type: TrackingType, adData: TrackingTypeData.TrackingAdTypeData) {
        val arcAd: ArcAd = adData.arcAd ?: return
        when (type) {
            TrackingType.AD_CLICKTHROUGH -> {
            }
            TrackingType.AD_SKIPPED -> {
            }
            TrackingType.AD_SKIP_SHOWN -> {
            }
        }
    }
    override fun onSourceTrackingEvent(type: TrackingType, trackingSourceTypeData: TrackingTypeData.TrackingSourceTypeData) {

    }
    override fun onError(type: TrackingType, trackingErrorTypeData: TrackingTypeData.TrackingErrorTypeData) {

    }
})

ArcAd

An ArcAd object is passed back with the onAdTrackingEvent() method through the TrackingAdTypeData object. This object contains important information about the currently playing ad.

Parameter	Type	Description
`adId`	String?	The unique ID of the ad
`adDuration`	Double?	Duration of the ad in seconds
`adTitle`	String?	Title of the ad
`companionAds`	List?	Companion ad objects in JSON format
`mediaFiles`	MediaFiles?	MediaFiles object
`clickthroughUrl`	String?	The url to be navigated when the ad is touched