Android players

Monitor AndroidX Media3

FastPix Data SDK for AndroidX Media3 (latest version of 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.

Step 1

Installation and setup

Step 2

Import the SDK

Step 3

Basic integration

Step 4

Including metadata

Step 5

Advanced configuration

Step 6

Emit custom events

Detailed example

Configure Media3

Step 1

Installation and setup

Step 2

Import the SDK

Step 3

Basic integration

Step 4

Including metadata

Step 5

Advanced configuration

Step 6

Emit custom events

Detailed example

Configure Media3



PREREQUISITES

  • To track and analyze video performance, initialize the FastPixVideo 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.
  • An existing Android Studio project where you plan to integrate the Video Data SDK.
  • Gradle configured in your project for managing dependencies.
  • Media3 ExoPlayer pre-installed and integrated with your project for Video Data setup.

Step 1: Install and setup

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

  2. Add the Video 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: 
    2
    3dependencies { 
    4 	// check with latest version 
    5  	implementation 'io.fastpix.data:media3: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-media3-player-sdk")
    5			credentials { 
    6 			// Your GitHub account username (or) FastPix  
    7    			username = "Github_User_Name" 
    8 			// Your (PAT) Personal access token Get It from you Github account
    9    			password = "Github_PAT"   
    10			} 
    11  	} 
    12}

  3. 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 Media3 Exo-Player setup first. Once the player is fully ready, integrate and start the SDK in your project.


Step 2: Import the SDK

1import io.fastpix.data.domain.model.CustomDataDetails
2import io.fastpix.data.domain.model.VideoDataDetails
3import io.fastpix.data.exo.FastPixBaseMedia3Player
4import io.fastpix.data.domain.model.PlayerDataDetails

Step 3: Basic integration

Globally declare

You need to globally declare the ExoPlayer instance and FastPixBaseMedia3Player 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: FastPixBaseMedia3Player // Global FastPix instance 
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 Media3 ExoPlayer with FastPix:


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

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 customField1 to customField9 for your business logic, giving you the flexibility to pass any required values. Named attributes, such as videoTitle and videoId, can be passed directly as they are.


1override fun onCreate(savedInstanceState: Bundle?) {
2	 	// 1. Video Data Details (Optional)
3	 val videoDataDetails = VideoDataDetails("video-id", "video-title").apply {
4            videoSeries = "video-series"
5            videoProducer = "video-producer"
6            videoContentType = "video-content-type"
7            videoVariant = "video-variant"
8            videoLanguage = "video-language"
9            videoDuration = "video-duration"
10            //...etc
11        }
12		// 2. Custom Data Details (Optional)
13        val customDataDetails = CustomDataDetails().apply {
14            customField1 = "Custom 1"
15            customField2 = "Custom 2"
16            //...etc
17        }
18        // By Default player sets these things, You don't have to worry about it unless you're not using
19        // some wrapper around media3
20		// 3. Player Data Details (Optional)
21        val playerDataDetails = PlayerDataDetails(
22            playerName = "media3",
23            playerVersion = "latest-version"
24        )
25}

To set up video analytics, create a FastPixBaseMedia3Player object by providing the following parameters: your application’s Context (usually the Activity), the player-view ,exo-playerinstance, workspace-id, player-data-details, viwer-id, video-data-details and custom-data-details objects that you have prepared.

1	fastPixDataSDK = FastPixBaseMedia3Player(
2            this, // context
3            playerView = binding.playerView, // media3 playerView from XML
4            exoPlayer = exoPlayer, // media3 player
5            workSpaceId = "workspace-id",
6            playerDataDetails = playerDataDetails, // Optional
7            videoDataDetails = videoDataDetails, // Optional
8            customDataDetails = customDataDetails // Optional
9	)

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

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

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 Media3 ExoPlayer

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

Changelog

All notable changes to the Android Media3 Video Data SDK is documented below.

Current version

[1.2.7]

Upgrade

  • Updates Core SDK version to 1.3.1

[1.2.6]

Upgrade

  • Updates Core SDK version to 1.3.0

[1.2.5]

Upgrade

  • Version Upgrade to 1.2.9
  • Updates Core SDK version to 1.2.9
  • Adds unique player instance ID and enhanced logging for session tracking and release events
  • Refines pulse event scheduling logic across player states (play, seeked, buffering)
  • Optimizes event dispatching by adjusting pulse event triggers for improved session monitoring

[1.2.4]

Changes

  • Version Upgrade to 1.2.4
  • Updates Core SDK version to 1.2.7
  • Refactors SDK initialization to use FastPixAnalytics singleton
  • Adds unique player instance ID and enhanced logging for session tracking
  • Improves lifecycle management with better null safety and coroutine cancellation
  • Updates event dispatching logic to check initialization state and include session details in logs

[1.2.3]

Fix

  • Sdk Upgrade:
  • Sdk Version Update
  • Bug Fixes
  • Upgraded Core SDK version to 1.2.6

[1.2.2]

Fix

  • Sdk Version Upgrade:
  • Sdk Version Update

[1.2.1]

Fix

  • Major Bug Fixes:
  • Major Bug Fixes
  • Adds Missing Fields

[1.2.0]

Improved

  • Major Code Optimization and Refactoring:
  • Version Compatibility Update
  • Code Refactoring
  • Library Upgrade

[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.

Added

  • Code Update:
  • Variable types are improved.
  • Bugs are fixed.
  • Events work better now.

[v1.0.1]

Added

  • Code Update:
  • Variable types are improved.
  • Bugs are fixed.
  • Events work better now.

Previous version

[v1.0.0]

Added

  • Integration with Media3 ExoPlayer:
  • Enabled video performance tracking using FastPix Data SDK, supporting Media3 ExoPlayer streams with user engagement metrics, playback quality monitoring, and real-time diagnostics.
  • Provides robust error management and reporting capabilities for seamless Media3 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.