Skip to main content

Quick Start

Video Tracking

Android SDK Reference

Overview

Android TV and Google TV applications use the Permutive Android SDK. The same SDK that powers mobile Android applications fully supports Android TV, providing identical APIs for tracking, identity management, and ad targeting.
Same SDK, Same APIs: The Permutive Android SDK works seamlessly on Android TV. All features documented in the Android SDK are available on Android TV.

Requirements

Installation

Add the Permutive SDK to your build.gradle:

Initialization

Initialize the SDK in your Application class:
The workspace ID and API key are UUIDs. From Java, use new Permutive.Builder().context(this).workspaceId(...).apiKey(...).build(). For detailed initialization options, see Android Initialization.

Video Tracking

Video tracking on Android TV uses the MediaTracker API. This is the primary use case for CTV applications.

Creating a MediaTracker

Integrating with ExoPlayer

Android TV applications typically use ExoPlayer (now part of Media3) for video playback:

MediaTracker Lifecycle

Always call stop(): Failing to call stop() when the video ends or the user exits will prevent VideoCompletion events from being tracked.
For complete MediaTracker documentation, see Android Video Tracking.

Video Properties

The SDK provides standard video properties for consistent tracking:

Video Ad Tracking

Track video advertisements within your content:
See Android Video Ad Tracking for details.

Identity Management

Set user identities for cross-device tracking:
See Android Identity Management for details.

Cohorts and Targeting

Accessing Cohorts

currentCohorts and currentActivations return a snapshot. From a coroutine, the suspend functions permutive.cohorts() and permutive.activations() wait for cohort updates from recently tracked events to finish first.
addPermutiveTargeting comes from the Google Ads add-on, which requires Android API 23 or later. See Android Google Ad Manager for complete integration details.

Android TV-Specific Considerations

Android TV uses the Leanback library for its 10-foot UI. Ensure your tracking implementation doesn’t interfere with Leanback components:
Android TV uses D-pad navigation. Tracking works independently of navigation, but ensure you handle the back button appropriately:
If your app supports PiP mode, continue tracking during PiP:
Android TV supports AAID. From core SDK v1.12, the SDK can collect the AAID automatically when this is enabled in your workspace configuration, with no provider code. See Migrating to v1.12.To add the AAID manually instead, use AaidAliasProvider from the Google Ads add-on (minimum Android API 23):
Either way, declare the com.google.android.gms.permission.AD_ID permission in your manifest. See AAID Provider for details.
Android TV apps may continue video playback when the home button is pressed. Handle this appropriately:

Best Practices

  • Initialize SDK early in Application.onCreate()
  • Create MediaTracker when video is ready to play
  • Call stop() when video ends or user exits
  • Sync play()/pause() with actual player state
  • Handle buffering states with pause()
  • Include video metadata for richer cohorts
  • Use Leanback-compatible patterns

Troubleshooting

Problem: Permutive instance is null or initialization fails.Solutions:
  • Verify API key and workspace ID are correct
  • Ensure initialization happens in Application.onCreate()
  • Check for initialization errors in Logcat
  • Enable debug mode: permutive.setDeveloperMode(true)
Problem: Video events don’t show in Permutive dashboard.Solutions:
  • Verify MediaTracker was created successfully
  • Ensure play() is called when video starts
  • Ensure stop() is called when video ends
  • Wait 5-10 minutes for events to process
  • Check Logcat for “Accepted: 1 / 1” messages
Problem: Engagement metrics don’t match expected values.Solutions:
  • Sync play()/pause() calls with actual player state
  • Call pause() during buffering
  • Provide accurate duration when creating MediaTracker
Problem: VideoCompletion events not appearing.Solutions:
  • Ensure stop() is called in onDestroy()
  • Handle back button to call stop() before navigation
  • Verify app isn’t killed before event sends

Android SDK Overview

Complete Android SDK documentation

Android Video Tracking

Detailed MediaTracker documentation

Android Video Ad Tracking

Video advertisement tracking

CTV Video Best Practices

Cross-platform video tracking guide