Monitor Kaltura Player

The FastPix Data SDK with KalturaPlayer 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.

Prerequisites:

To track and analyze video performance, initialize the SDK with your Workspace key. Learn about Workspaces.

1. Access the FastPix Dashboard: Log in and navigate to the Workspaces section.
2. Locate Your Workspace Key: Copy the Workspace Key for client-side monitoring. Include this key in your Java/Kotlin code on every page where you want to track video performance.
3. Ensure kalturaPlayer is already configured in your project.

Install and setup

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

2. Add the FastPix Data SDK dependency:

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

1
// FastPix Kaltura Player SDK
2
    implementation("io.fastpix.data:theo:0.0.2")
3
   
4
   //Kaltura player SDK
5
   implementation("com.kaltura.player:tvplayer:5.0.3")
6
   implementation("com.kaltura.playkit:playkitproviders:5.0.3")

Navigate to your settings.gradle file

1
dependencyResolutionManagement {
2
    repositories {
3
        google()
4
        mavenCentral()
5
        maven {
6
            url = uri("https://maven.pkg.github.com/FastPix/android-data-kalturaPlayer")
7
            credentials {
8
                username = "your-github-userName"
9
                password = "your-PAT" // Personal Access Token
10
            }
11
        }
12
    }
13
}

3. Sync your project with Gradle files Click Sync Now in the notification bar to download and integrate the FastPix Data SDK.

Import the SDK

Ensure kalturaPlayer is already configured in your project.

1
import io.fastpix.data.domain.model.CustomDataDetails
2
import io.fastpix.data.domain.model.PlayerDataDetails
3
import io.fastpix.data.domain.model.VideoDataDetails
4
import io.fastpix.data.kaltura_player_data.src.FastPixKalturaPlayer

Integrate with FastPix

1. Ensure that the workSpaceId is provided, as it is a mandatory field for FastPix integration, uniquely identifying your workspace. Install and import FastPixKalturaPlayer into your project, and create an fastPixKalturaPlayer instance to bind it to. If you are using any other custom player then create an instance of that player.

2. Next, create an instance of FastPixKalturaPlayer for tracking the analytics. After the video URL loads and playback begins, the SDK automatically begins tracking analytics.

1
class MainActivity : AppCompatActivity() {
2
 private var fastPixKalturaPlayer: FastPixKalturaPlayer? = null}

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

1
        val videoData = VideoDataDetails(
2
            videoId = "video-id",
3
            videoTitle = "Sample Video",
4
        )
5
 
6
        val customData = CustomDataDetails(
7
            customField1 = "custom-value-1",
8
            customField2 = "custom-value-2"
9
        )
10
 
11
        val playerData = PlayerDataDetails(
12
            playerName = "Kaltura Basic Player",
13
            playerVersion = "5.0.3"
14
        )
15
        fastPixKalturaPlayer = FastPixKalturaPlayer(
16
            context = this,
17
            playerView = binding.playerContainer,
18
            kalturaPlayer = kalturaPlayer!!,
19
            workspaceId = "your-workspace-id",
20
            videoDataDetails = videoData,
21
            playerDataDetails = playerData,
22
            customDataDetails = customData,
23
            enableLogging = true
24
        )

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.

See the User-Passable Metadata documentation to understand the metadata supported by FastPix.

You can use custom metadata fields such as customField1 to customField10 for implementing your business logic, allowing you to pass any required values. Named attributes like videoId and videoTitle can be passed directly without any additional configuration.

1
     val videoData = VideoDataDetails(
2
            videoId = "video-id",
3
            videoTitle = "Sample Video",
4
            videoSeries = "Demo Series",
5
            videoProducer = "Producer Name",
6
            videoContentType = "Video",
7
            videoVariant = "HD",
8
            videoLanguage = "en",
9
            videoCDN = "cloudflare"
10
        )
11
 
12
        val customData = CustomDataDetails(
13
            customField1 = "custom-value-1",
14
            customField2 = "custom-value-2"
15
        )

1. To set up video analytics, create a FastPixKalturaPlayer object by providing the following parameters: your application’s Context (usually the Activity), the KalturaPlayer instance, and the customerData.

1
  fastPixKalturaPlayer = FastPixKalturaPlayer(
2
            context = this,
3
            playerView = binding.playerContainer,
4
            kalturaPlayer = kalturaPlayer!!,
5
            workspaceId = "your-workspace-id",
6
            videoDataDetails = videoData,
7
            playerDataDetails = playerData,
8
            customDataDetails = customData,
9
            enableLogging = true
10
        )

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

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

3. 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 workspace_key, and look for video views.

CustomerData Parameters

The CustomerData class accepts the following parameters:

What FastPix Tracks

After initialization, the SDK automatically collects:

Example to configure Kaltura with FastPix Data SDK.

Provide your stream URL in url field"your-stream-url.m3u8" and your FastPix workspace Key in the workspaceId field.

1
class MainActivity : AppCompatActivity() {
2
 
3
    private lateinit var binding: ActivityMainBinding
4
    private var kalturaPlayer: KalturaBasicPlayer? = null
5
    private var fastPixKalturaPlayer: FastPixKalturaPlayer? = null
6
 
7
    override fun onCreate(savedInstanceState: Bundle?) {
8
        super.onCreate(savedInstanceState)
9
        binding = ActivityMainBinding.inflate(layoutInflater)
10
        setContentView(binding.root)
11
 
12
        setupKalturaPlayer()
13
        setupFastPixSDK()
14
    }
15
 
16
    private fun setupKalturaPlayer() {
17
        val initOptions = PlayerInitOptions().setAutoPlay(true)
18
        kalturaPlayer = KalturaBasicPlayer.create(this, initOptions)
19
20
        kalturaPlayer?.setPlayerView(
21
            FrameLayout.LayoutParams.MATCH_PARENT,
22
            FrameLayout.LayoutParams.MATCH_PARENT
23
        )
24
25
        val playerView = kalturaPlayer?.getPlayerView() ?: run {
26
            return
27
        }
28
29
        binding.playerContainer.addView(playerView)
30
31
        val entry = PKMediaEntry().apply {
32
            mediaType = PKMediaEntry.MediaEntryType.Vod
33
            sources = listOf(
34
                PKMediaSource().apply {
35
                    url = "your-stream-url.m3u8"
36
                }
37
            )
38
        }
39
40
        kalturaPlayer?.setMedia(entry)
41
    }
42
 
43
    private fun setupFastPixSDK() {
44
        val videoData = VideoDataDetails(
45
            videoId = "video-id",
46
            videoTitle = "Sample Video",
47
            videoSeries = "Demo Series",
48
            videoProducer = "Producer Name",
49
            videoContentType = "Video",
50
            videoVariant = "HD",
51
            videoLanguage = "en",
52
            videoCDN = "cloudflare"
53
        )
54
 
55
        val customData = CustomDataDetails(
56
            customField1 = "custom-value-1",
57
            customField2 = "custom-value-2"
58
        )
59
 
60
        val playerData = PlayerDataDetails(
61
            playerName = "Kaltura Basic Player",
62
            playerVersion = "5.0.3"
63
        )
64
 
65
        fastPixKalturaPlayer = FastPixKalturaPlayer(
66
            context = this,
67
            playerView = binding.playerContainer,
68
            kalturaPlayer = kalturaPlayer!!,
69
            workspaceId = "your-workspace-id",
70
            videoDataDetails = videoData,
71
            playerDataDetails = playerData,
72
            customDataDetails = customData,
73
            enableLogging = true
74
        )
75
    }
76
 
77
    override fun onDestroy() {
78
        super.onDestroy()
79
        fastPixKalturaPlayer?.release()
80
        kalturaPlayer?.destroy()
81
    }
82
}
83
 

Debug Logging

Enable logs using:

1
enableLogging = true

Troubleshooting

SDK Not Tracking Events

• Ensure you’ve initialized the SDK after configuring Kaltura Player
• Check that workSpaceId is correct
• Verify Kaltura Player events are firing (check Kaltura Player logs)
• Enable logging to see FastPix SDK activity

Memory Leaks

• Always call release() in onDestroy()
• Ensure kalturaPlayer?.destroy() is called before releasing FastPix SDK

Missing Events

• The SDK automatically tracks all events from Kaltura Player
• Events are tracked based on Kaltura Player native event system
• Check that Kaltura player is properly configured and receiving events

Change log

v1.0.4

Changes

• SDK & Dependencies
  • Bumped SDK_VERSION to 1.0.4 in FastPixKalturaLibraryInfo.kt.
  • Updated publication version to 1.0.4 in build.gradle.kts.
  • Updated core library dependency to version 1.3.1 in libs.versions.toml.
• Documentation
  • Updated version reference to 1.0.4 in README.md.
  • Added entry for v1.0.4 in CHANGELOG.MD.

v1.0.3

• Upgrades Core SDK to 1.3.0

v1.0.2

Changed

• SDK & Dependencies
  • Updated androidx.core:core-ktx (core) from 1.2.7 to 1.2.9.
  • Updated README.md dependency example to 1.0.2.
• FastPixKalturaPlayer Event Handling
  • Adjusted pulse lifecycle to schedule periodic pulse events on viewBegin, play, and buffering transitions.
  • Improved seek handling so pulse events are cancelled only when playback remains paused after seeked, and resumed when playback continues.
  • Removed unnecessary pulse scheduling from variantChanged dispatch to avoid duplicate pulse triggers.
• Stability
  • Guarded FastPixAnalytics.release(...) with a null-check on fastPixDataSDK to avoid releasing analytics when SDK is not initialized.

v1.0.1

Changed

• SDK & Dependencies
  • Bumped io.fastpix.data version to 1.0.1.
  • Updated core library version to 1.2.7.
  • Removed MuxKalturaSDK and associated Maven repositories from the project.
• FastPixKalturaPlayer Enhancements
  • Switched to FastPixAnalytics singleton for SDK initialization and management.
  • Implemented a background pulse event mechanism (10-second interval) to track active playback sessions.
  • Improved event lifecycle management by ensuring pulse events are cancelled during buffering, seeking, pausing, or errors.
  • Refined release() logic to ensure proper state cleanup and final position reporting.
  • Updated PlayerListener interface implementation to match updated types for frame rate and duration.
• Cleanup
  • Removed unused Utils.kt and redundant Mux initialization code from MainActivity.
  • Cleaned up unused Kaltura library dependencies from the app module.

v1.0.0

Integration with Kaltura Player

• Added Kaltura Player integration with automatic video performance tracking using the FastPix Data SDK.
• Enabled playback event tracking, including play, pause, buffering, seek, and completion events.
• Added support for custom metadata such as video_id, video_title, video_series, video_language, and more.
• Included player metadata tracking with player name and version details.
• Added customizable behavior with options for logging, custom beacon URL, and metadata configuration.
• Implemented lifecycle-safe handling with automatic cleanup and resource release.
• Added support for switching videos with seamless tracking of new playback sessions.

Support

📩 Email: support@fastpix.com 📚 Docs: fastpix.com/docs