Android players

Monitor ExoPlayer

Understand how FastPix ExoPlayer SDK tracks playback, performance, and user interactions on Android.

The FastPix Data SDK with ExoPlayer helps you track key video metrics like user interactions, playback quality, and performance to enhance the viewing experience. It lets you customize data tracking, monitor streaming quality, and securely send insights for better optimization and error resolution.

Key features:

  • Capture user engagement through detailed viewer interaction data.
  • Monitor playback quality with real-time performance analysis.
  • Identify and fix video delivery bottlenecks on Android.
  • Customize tracking to match specific monitoring needs.
  • Handle errors with robust reporting and diagnostics.
  • Gain deep insights into video performance with streaming diagnostics.

Step 1

Install and setup

Step 2

Import the SDK

Step 3

Basic integration

Step 4

Add metadata

Step 5

Advanced Customization

Step 6

Emit custom events

Detailed example

Configure ExoPlayer

Step 1

Install and setup

Step 2

Import the SDK

Step 3

Basic integration

Step 4

Add metadata

Step 5

Advanced Customization

Step 6

Emit custom events

Detailed example

Configure ExoPlayer


Prerequisites

  1. To track and analyze video performance, initialize the FastPix Data SDK with your Workspace key. This key is essential for client-side monitoring and must be included in your Android application’s code wherever you want to track video performance.
  2. An existing Android Studio project where you plan to integrate the FastPix Data SDK.
  3. Gradle configured in your project for managing dependencies.
  4. ExoPlayer pre-installed and integrated with your project for FastPix data setup.

Step 1: Install and setup

  1. Open your Android Studio project where you want to integrate the SDK.

  2. Add the FastPix Data SDK dependency:

    Navigate to your app-level build.gradle file (or build.gradle.kts if using Kotlin DSL).


    1//Add the following line under the dependencies section: 
    2dependencies{ 
    3  
    4	// check with latest version 
    5  implementation 'io.fastpix.data:exoplayer:1.1.0 ' 
    6}

    Navigate to your settings.gradle file


    1//Add the following lines inside repositories section: 
    2repositories { 
    3  maven { 
    4  url = uri("https://maven.pkg.github.com/FastPix/android-data-exo-player-sdk")  
    5  credentials { 
    6
    7  // Your GitHub account username (or) FastPix  
    8  username = "github-user-name" 
    9
    10  // Your (PAT) Personal access token Get It from you Github account 
    11  password = "github-pat"   
    12   	      } 
    13  	} 
    14}

  1. Sync your project with Gradle files

    Click “Sync Now” in the notification bar to download and integrate the FastPix Data SDK.


Once the above dependency is added, you can use the FastPix Data SDK module into your Android project where you intend to use its functionalities.


PLEASE NOTE
To ensure accurate analytics, initialize and complete the ExoPlayer setup first. Once the player is fully ready, integrate and start the Android data analytics SDK in your project.


Step 2: Import the SDK

1import io.fastpix.data.domain.model.CustomDataDetails
2import io.fastpix.data.domain.model.PlayerDataDetails
3import io.fastpix.data.domain.model.VideoDataDetails
4import io.fastpix.exoplayer_data_sdk.FastPixBaseExoPlayer

Step 3: Basic integration


Globally declare

You need to globally declare the ExoPlayer instance and FastPixBaseExoPlayer in your Android application. A global declaration ensures that these objects can be accessed throughout the lifecycle of your activity or application where required.


1import ... 
2
3class VideoPlayerActivity : AppCompatActivity() { 
4    private lateinit var exoPlayer: ExoPlayer // Global ExoPlayer instance 
5    private lateinit var fastPixDataSDK: FastPixBaseExoPlayer 
6}

You can initialize ExoPlayer with a PlayerView or SurfaceView in your Android application to enable seamless functionality. Use the following Kotlin or Java code in your Android application to configure ExoPlayer with FastPix:


1import io.fastpix.data.domain.model.CustomDataDetails
2import io.fastpix.data.domain.model.PlayerDataDetails
3import io.fastpix.data.domain.model.VideoDataDetails
4import io.fastpix.exoplayer_data_sdk.FastPixBaseExoPlayer
5
6class VideoPlayerActivity : AppCompatActivity() { 
7
8    private lateinit var exoPlayer: ExoPlayer 
9    private lateinit var fastPixDataSDK: FastPixBaseExoPlayer
10  
11    override fun onCreate(savedInstanceState: Bundle?) { 
12        super.onCreate(savedInstanceState) 
13		setContentView(R.layout.your_layout) // don't forget this if needed 
14        initializePlayers() 
15    } 
16
17    private fun initializePlayers() { 
18        // Initialize ExoPlayer 
19        exoPlayer = ExoPlayer.Builder(this).build() 
20        val mediaItem = MediaItem.fromUri("https://your.video.url/here.mp4") 
21        exoPlayer.setMediaItem(mediaItem) 
22        exoPlayer.prepare()
23
24		val playerDataDetails = PlayerDataDetails(
25            "player-name",
26            "player-version"
27        )
28        val videoDataDetails =
29            VideoDataDetails(
30                UUID.randomUUID().toString(),
31                videoModel?.id
32            ).apply {
33                videoSeries = "This is video series"
34                videoProducer = "This is video Producer"
35                videoContentType = "This is video Content Type"
36                videoVariant = "This is video Variant"
37                videoLanguage = "This is video Language"
38				// ...etc
39            }
40        val customDataDetails = CustomDataDetails().apply {
41			customField1 = "Custom 1",
42			customField2 = "Custom 2"
43			// ... etc
44			customField10 = "Custom 3"
45		}
46		
47        fastPixDataSDK = FastPixBaseExoPlayer(
48            this,
49            playerView = binding.playerView,
50            exoPlayer = exoPlayer,
51            workSpaceId = "workspace-id",
52            videoDataDetails = videoDataDetails,
53            playerDataDetails = playerDataDetails,
54            customDataDetails = customDataDetails
55        )
56    } 
57} 
1import io.fastpix.data.domain.model.CustomDataDetails
2import io.fastpix.data.domain.model.PlayerDataDetails
3import io.fastpix.data.domain.model.VideoDataDetails
4import io.fastpix.exoplayer_data_sdk.FastPixBaseExoPlayer
5
6public class VideoPlayerActivity extends AppCompatActivity { 
7  
8    private ExoPlayer exoPlayer; 
9    private FastPixBaseExoPlayer fastPixDataSDK; 
10  
11    // You’ll need to define this or use ViewBinding 
12    private PlayerView playerView;  
13
14    @Override 
15    protected void onCreate(Bundle savedInstanceState) { 
16		super.onCreate(savedInstanceState); 
17		setContentView(R.layout.your_layout);
18        initializePlayers(); 
19    } 
20  
21    private void initializePlayers() { 
22
23        // 1. Initialize ExoPlayer 
24        exoPlayer = new ExoPlayer.Builder(this).build(); 
25        MediaItem mediaItem = MediaItem.fromUri("https://your.video.url/here.mp4"); 
26        exoPlayer.setMediaItem(mediaItem); 
27        exoPlayer.prepare(); 
28
29		// Optional
30        final VideoDataDetails videoDataDetails = new VideoDataDetails("video-id", "video-title");
31		videoDataDetails.videoSeries = "video-series";
32		videoDataDetails.videoProducer = "video-producer";
33		videoDataDetails.videoContentType = "video-content-type";
34		videoDataDetails.videoVariant = "video-variant";
35		videoDataDetails.videoLanguage = "video-language";
36		videoDataDetails.videoDuration = "video-duration";
37		// ... etc
38
39		// Optional
40		final CustomDataDetails customDataDetails = new CustomDataDetails();
41		customDataDetails.customField1 = "Custom 1";
42		customDataDetails.customField2 = "Custom 2";
43		// ... etc
44		customDataDetails.customField2 = "Custom 3";
45
46		// Optional
47		final PlayerDataDetails playerDataDetails = new PlayerDataDetails();
48		playerDataDetails.playerName = "exo-player";
49		playerDataDetails.playerVersion = "latest-version"
50
51		fastPixDataSDK = new FastPixBaseExoPlayer(
52			this,
53			playerView,
54			exoPlayer,
55			"workspace-id",
56			playerDataDetails,
57			videoDataDetails,
58			customDataDetails
59		);
60    } 
61}

Step 4: Including custom data and metadata

  • workSpaceId is a mandatory parameter that tells the SDK on which workspace the data will collect.
  • playerView is another mandatory parameter.
  • exoPlayer is also a mandatory parameter that SDK uses to anylyze the playback.

Check out the user-passable metadata documentation to see the metadata supported by FastPix. You can use custom metadata fields like custom_1 to custom_10 for your business logic, giving you the flexibility to pass any required values. Named attributes, such as video_title and video_id, can be passed directly as they are.


1override fun onCreate(savedInstanceState: Bundle?) { 
2	 val videoDataDetails = VideoDataDetails("video-id", "video-title").apply {
3            videoSeries = "video-series"
4            videoProducer = "video-producer"
5            videoContentType = "video-content-type"
6            videoVariant = "video-variant"
7            videoLanguage = "video-language"
8            videoDuration = "video-duration"
9            //...etc
10        }
11        val customDataDetails = CustomDataDetails().apply {
12            customField1 = "Custom 1"
13            customField2 = "Custom 2"
14            //...etc
15        }
16        // By Default player sets these things, You don't have to worry about it unless you're not using
17        // some wrapper around media3
18        val playerDataDetails = PlayerDataDetails(
19            playerName = "media3",
20            playerVersion = "latest-version"
21        )
22		fastPixDataSDK = FastPixBaseExoPlayer(
23            this, // context
24            playerView = binding.playerView, // media3 playerView from XML
25            exoPlayer = exoPlayer, // media3 player
26            beaconUrl = "your-domain.com", // custom domain (Optional)
27            workSpaceId = "workspace-id",
28            playerDataDetails = playerDataDetails, // Optional
29            videoDataDetails = videoDataDetails, // Optional
30            customDataDetails = customDataDetails // Optional
31        )
32}

To set up video analytics, create a FastPixBaseExoPlayer object by providing the following parameters: your application’s Context (usually the Activity), the ExoPlayer instance, and the customerDataEntity and customOptions objects that you have prepared.

1fastPixDataSDK = FastPixBaseExoPlayer(
2            this, // context
3            playerView = binding.playerView, // media3 playerView from XML
4            exoPlayer = exoPlayer, // media3 player
5            workSpaceId = "workspace-id",
6)

Finally, when destroying the player, make sure to call the FastPixBaseExoPlayer.release() function to properly release resources.

1override fun onDestroy() { 
2  	super.onDestroy() 
3	fastPixDataSDK.release() // Cleanup FastPix tracking 
4}

After completing the integration, start playing a video in your player. A few minutes after stopping playback, you’ll see the results in your FastPix Video Data dashboard. Log in to the dashboard, navigate to the workspace associated with your ws_key, and look for video views.


Example to configure ExoPlayer with FastPix Data SDK.

Here are platform-specific examples to help you integrate the FastPix Data SDK with your ExoPlayer. Use the following Kotlin or Java code into your application:


1import io.fastpix.data.domain.model.CustomDataDetails
2import io.fastpix.data.domain.model.PlayerDataDetails
3import io.fastpix.data.domain.model.VideoDataDetails
4import io.fastpix.data.exo.FastPixBaseExoPlayer
5 
6class VideoPlayerActivity : AppCompatActivity() { 
7 
8    private lateinit var exoPlayer: ExoPlayer 
9    private var fastPixDataSDK: FastPixBaseExoPlayer? = null
10    override fun onCreate(savedInstanceState: Bundle?) { 
11        super.onCreate(savedInstanceState) 
12        setContentView(R.layout.your_layout)
13        initializePlayers() 
14    } 
15
16    private fun initializePlayers() { 
17
18        // Initialize ExoPlayer 
19        exoPlayer = ExoPlayer.Builder(this).build() 
20        val mediaItem = MediaItem.fromUri("https://your.video.url/here.mp4") 
21        exoPlayer.setMediaItem(mediaItem) 
22        exoPlayer.prepare() 
23
24        val videoDataDetails = VideoDataDetails("video-id", "video-title").apply {
25            videoSeries = "video-series"
26            videoProducer = "video-producer"
27            videoContentType = "video-content-type"
28            videoVariant = "video-variant"
29            videoLanguage = "video-language"
30            videoDuration = "video-duration"
31            //...etc
32        }
33		val customDataDetails = CustomDataDetails().apply {
34            customField1 = "Custom 1"
35            customField2 = "Custom 2"
36            //...etc
37        }
38		
39		// By Default player sets these things, You don't have to worry about it unless you're not using
40        // some wrapper around media3
41        val playerDataDetails = PlayerDataDetails(
42            playerName = "media3",
43            playerVersion = "latest-version"
44        )
45
46		fastPixDataSDK = FastPixBaseExoPlayer(
47            this, // context
48            playerView = binding.playerView, // media3 playerView from XML
49            exoPlayer = exoPlayer, // media3 player
50            workSpaceId = "workspace-id",
51            playerDataDetails = playerDataDetails,
52            videoDataDetails = videoDataDetails,
53            customDataDetails = customDataDetails
54        )
55    } 
56    override fun onDestroy() { 
57        super.onDestroy() 
58        fastPixDataSDK.release()
59    } 
60} 
1import io.fastpix.data.domain.model.CustomDataDetails
2import io.fastpix.data.domain.model.PlayerDataDetails
3import io.fastpix.data.domain.model.VideoDataDetails
4import io.fastpix.data.exo.FastPixBaseExoPlayer
5  
6public class VideoPlayerActivity extends AppCompatActivity {  
7    private ExoPlayer exoPlayer; 
8    private FastPixBaseExoPlayer fastPixDataSDK;
9
10    @Override 
11    protected void onCreate(Bundle savedInstanceState) { 
12        super.onCreate(savedInstanceState); 
13        setContentView(R.layout.your_layout);
14        initializePlayers(); 
15    } 
16
17    private void initializePlayers() { 
18      VideoDataDetails videoDataDetails = new VideoDataDetails("video-id", "video-title");
19       	videoDataDetails.setVideoSeries("video-series");
20		videoDataDetails.setVideoProducer("video-producer");
21		videoDataDetails.setVideoContentType("video-content-type");
22		videoDataDetails.setVideoVariant("video-variant");
23		videoDataDetails.setVideoLanguage("video-language");
24		videoDataDetails.setVideoDuration("video-duration");
25		// ... etc
26
27		CustomDataDetails customDataDetails = new CustomDataDetails();
28		customDataDetails.setCustomField1("Custom 1");
29		customDataDetails.setCustomField2("Custom 2");
30		// ... etc
31
32		// By default player sets these things, you don't have to worry about it
33		// unless you're using some wrapper around Media3
34		PlayerDataDetails playerDataDetails = new PlayerDataDetails(
35		        "exo-player",             // playerName
36		        "latest-version"      // playerVersion
37		);
38
39		fastPixDataSDK = new FastPixBaseExoPlayer(
40		        this,                       // context
41		        binding.getPlayerView(),    // media3 PlayerView from XML
42		        exoPlayer,                  // media3 player instance
43		        "beacon-url",               // beaconUrl (Optional)
44		        "workspace-id",             // workSpaceId
45		        playerDataDetails,          // player data (Optional)
46		        videoDataDetails,           // video data (Optional)
47		        customDataDetails           // custom data (Optional)
48		);
49    } 
50
51    @Override 
52    protected void onDestroy() { 
53        super.onDestroy(); 
54        if (fastPixDataSDK != null) { 
55            fastPixDataSDK.release(); // Cleanup FastPix tracking
56			fastPixDataSDK = null;
57        } 
58    } 
59}


Changelog

All notable changes to the ExoPlayer (Android) Video Player SDK is documented below.


Current version

[1.1.4]

  • Upgrades Core SDK to 1.3.1
  • Removes synchronous bandwidth data capture and storage in onLoadCanceled to streamline event dispatching.

Previous version

[1.1.3]

  • Upgrades Core SDK to 1.3.0

[1.1.2]

Improves pulse analytics dispatch behavior during playback state transitions and updates SDK versions/documentation.

General

  • Updates core SDK version to 1.2.9 in libs.versions.toml.
  • Updates FastPixExoplayerLibraryInfo SDK version constant to 1.1.2.

FastPixBaseExoPlayer

  • Ensures pulse events are scheduled on viewBegin, play, and buffering instead of being canceled.
  • Prevents unnecessary pulse cancellation on playerReady, seeking, and buffered.
  • Updates seeked handling to cancel pulse events only when playback is not active, and keep pulse scheduling when playback continues.
  • Stops scheduling pulse events on variantChanged to avoid unintended heartbeat behavior during rendition switches.

[1.1.1]

Updates versions, refactors FastPixBaseExoPlayer to improve event handling, and enhances documentation.

General

  • Updates core SDK version to 1.2.7 in libs.versions.toml.
  • Updates exoplayer-data-sdk Maven publication version to 1.1.1.
  • Configures settings.gradle.kts to load GitHub credentials from local.properties.

FastPixBaseExoPlayer

  • Refactors SDK initialization to use FastPixAnalytics singleton.
  • Implements a coroutine-based pulse event system for periodic analytics heartbeats.
  • Adds comprehensive state tracking for playback (playing, buffering, seeking, ended).
  • Improves bandwidth and chunk load tracking, including better handling of canceled and failed requests.
  • Ensures proper resource cleanup in release() by canceling background jobs and clearing state.
  • Adds FastPixExoplayerLibraryInfo to track SDK name and version.

Documentation

  • Overhauls README.md with updated requirements, simplified installation steps, and clearer Kotlin integration examples.
  • Adds version 1.1.1 to CHANGELOG.md.

v1.1.0

Changed

  • Major Code Optimization and Refactoring:
  • Comprehensive code refactoring for improved maintainability and performance.
  • Optimized internal components and dependencies for better efficiency.
  • Enhanced code structure and organization across the SDK.
  • Improved overall stability and reduced technical debt.

v1.0.0

Added

  • Integration with ExoPlayer:
    • Enabled video performance tracking using FastPix Data SDK, supporting ExoPlayer streams with user engagement metrics, playback quality monitoring, and real-time diagnostics.
    • Provides robust error management and reporting capabilities for seamless ExoPlayer video performance tracking.
    • Allows customizable behavior, including options to disable data collection, respect Do Not Track settings, and configure advanced error tracking with automatic error handling.
    • Includes support for custom metadata, enabling users to pass optional fields such as video_id, video_title, video_duration, and more.
    • Introduced event tracking for onPlayerStateChanged and onTracksChanged to handle seamless metadata updates during playback transitions.