MediaTracker API allows you to track video content events with Permutive. Use this for tracking video playback, engagement, and completion metrics.
Connected TV IntegrationVideo event tracking described below is available once the connected TV integration has been enabled. Please contact your Customer Success Manager (CSM) to enable this feature.
Overview
MediaTracker provides comprehensive video tracking capabilities:
- Automatic lifecycle tracking - Tracks Videoview and VideoComplete events
- Engagement metrics - Measures time spent watching and completion percentage
- Custom events - Track custom video-related events
- Rich metadata - Support for extensive video properties
Video Events
MediaTracker automatically tracks two event types:1. Videoview Event
Tracked when MediaTracker is created:2. VideoComplete Event
Tracked when video is stopped:📘 Note Thecompletionproperty requires a known duration to be set. PassdurationMillisecondswhen creating the MediaTracker.
Basic Usage
Creating a MediaTracker
Create a MediaTracker when video playback begins:MediaTracker Lifecycle
Expected Usage Flow
- Create MediaTracker instance with properties
- Call
play()when playback begins - Track buffering with
pause()/play() - Track scrubbing with
play(position) - Call
stop()when playback completes
⚠️ Single Instance Limitation Only a single instance ofPageTrackerorMediaTrackeris available at any time. Close existing trackers before creating new ones.
Playback Control Methods
play()
Call when video starts playing:play(positionMs)
Call when playback position changes (e.g., seeking):pause()
Call when video is paused or buffering:stop()
Call when video playback completes or user exits:
⚠️ Important: Always Call stop()
Failing to call stop() will prevent VideoComplete events from being tracked.
Video Properties
Standard Video Properties
The SDK provides standard video properties for consistent tracking:Property Reference
| Property | Type | Description |
|---|---|---|
| title | String | Video title |
| genre | List<String> | Video genres (e.g., “Drama”, “Comedy”) |
| contentType | List<String> | Content types (e.g., “Movie”, “Series”) |
| ageRating | String | Age rating (e.g., “PG-13”, “TV-MA”) |
| runtime | Int | Runtime in seconds |
| country | String | Origin country |
| originalLanguage | String | Original language code |
| audioLanguage | String | Audio language code |
| areSubtitlesEnabled | Boolean | Whether subtitles are enabled |
| subtitlesLanguage | String | Subtitle language code |
| seasonNumber | Int | Season number (for series) |
| episodeNumber | Int | Episode number (for series) |
| consecutiveEpisodes | Int | Consecutive episodes watched |
| iabCategories | List<String> | IAB content taxonomy categories |
💡 Best Practice Track as many properties as possible to enable richer cohort creation and insights.
Page Properties (Optional)
If the video is displayed within a page context (e.g., embedded in article), include page properties:PageProperties Reference
| Property | Type | Description |
|---|---|---|
| title | String | Page title |
| url | Uri | Page URL |
| referrer | Uri | Referring page URL |
Custom Properties
Add custom properties specific to your event schema:Complete Example
Tracking Custom Events
Track custom video-related events using thetrack() method:
Video Ad Tracking
If you need to track video ads within video content, use theAdTracker API:
Use Cases
Movie/TV App
Movie/TV App
Educational/Tutorial App
Educational/Tutorial App
Series/Episode Tracking
Series/Episode Tracking
Troubleshooting
VideoComplete Not Tracked
VideoComplete Not Tracked
Problem: VideoComplete events not appearing.Cause:
stop() not called.Solution: Always call stop() in onDestroy():Engagement Time Incorrect
Engagement Time Incorrect
Problem: Engaged time is inaccurate.Causes:
- Not calling
play()when video plays - Not calling
pause()when video pauses/buffers
Completion Percentage Missing
Completion Percentage Missing
Problem:
completion property is missing or null.Cause: Duration not provided when creating MediaTracker.Solution: Always provide durationMilliseconds:Multiple Tracker Error
Multiple Tracker Error
Problem: Error about multiple trackers.Cause: Creating new PageTracker or MediaTracker without closing existing one.Solution: Close existing tracker first:See Common Errors for more troubleshooting.
Best Practices
- Do
- Don't
- Always call
stop()when video finishes - Provide duration for completion tracking
- Track play/pause events accurately
- Include as many video properties as possible
- Close tracker before creating a new one
- Track buffering with pause/play
Related Documentation
Video Ad Tracking
Track video advertisements
Page Tracking
Track non-video content
Event Properties
Custom properties
Issues
Solve common issues
API Reference
For complete API documentation, see the Javadocs.MediaTracker Interface
play()- Start/resume video playbackplay(positionMs: Long)- Start at specific positionpause()- Pause video playbackstop()- Complete video tracking (sends VideoComplete)setDuration(durationMs: Long)- Update video durationtrack(eventName: String)- Track custom eventtrack(eventName: String, properties: EventProperties)- Track custom event with propertiestrackAdView(...)- Create AdTracker for video ad
Creating MediaTracker
Permutive.trackVideoView(durationMilliseconds, videoProperties, pageProperties, customEventProperties)- Create MediaTracker