Skip to Content
Mux Docs: Home

Monitor Kaltura Player (iOS)

This guide walks through integration with iOS and TVOS Kaltura player to collect video performance metrics with Mux data.

Mux Data Mux-Stats-Kaltura supports iOS 9.0 or newer and TVOS 9.0 or newer. The Mux integration with Kaltura is built on top of Mux's core Objective-C SDK, and the full code can be seen here: muxinc/mux-stats-sdk-kaltura-ios.

This SDK is built with XCFramework bundle type and supports Mac Catalyst.

Features

The following data can be collected by the Mux Data SDK when you use the Kaltura iOS SDK, as described below.

Supported Features:

  • Engagement metrics
  • Quality of Experience Metrics
  • Available for deployment from a package manager
  • Custom Dimensions
  • Average Bitrate metrics and renditionchange events
  • Request metrics
  • Customizable Error Tracking
  • Preroll Ads metrics
Notes:

Packaged with: cocoapods.

1Install the Mux Data SDK

Installing with SwiftPM

  1. In Xcode click "File" > "Swift Packages" > "Add Package Dependency..."
  2. The package repository URL is https://github.com/muxinc/mux-stats-sdk-kaltura-ios.git
  3. Click next.
  4. Select dependency resolution options. We recommend setting the "Rules" to install the latest version and choosing the option "Up to Next Major".

Note that MUXSDKStatsKaltura has a dependency on MuxCore, so you will see that MuxCore gets installed as well.

As of Xcode 14.3.1 integrating the Mux SDKs as part of a shared framework using Swift Package Manager is now supported.

Installing with CocoaPods

To install with CocoaPods, modify your Podfile to use frameworks by including use_frameworks! and then add the following pods to your Podfile:

pod 'Mux-Stats-Kaltura', '~>3.0'

This will install Mux-Stats-Kaltura and the latest current release of our core Objective-C Library. There will be no breaking updates in major versions, so you can safely run pod update for future versions.

Next, add correct import statement into your application.

import MUXSDKKaltura

2Initialize the monitor for your Kaltura player instance

Get your ENV_KEY from the Mux environments dashboard.

Env Key is different than your API token

ENV_KEY is a client-side key used for Mux Data monitoring. These are not to be confused with API tokens which are created in the admin settings dashboard and meant to access the Mux API from a trusted server.

The example below uses monitorPlayer:player:playerName:customerData:.

The playerName parameter is a string that identifies this instance of your player. When calling destroyPlayer later on, you will need this string. Each instance of a player that runs simultaneously in your application should have a different playerName.

let playerName = "iOS KalturaPlayer"
let playerData = MUXSDKCustomerPlayerData(environmentKey: "ENV_KEY")
playerData?.playerName = self.playerName
let videoData = MUXSDKCustomerVideoData()
videoData.videoTitle = "Title Video Kaltura"
videoData.videoId = "my-video-id"
let viewData = MUXSDKCustomerViewData()
viewData.viewSessionId = "my-session-id"
let customData = MUXSDKCustomData()
customData.customData1 = "my-custom-data"
let viewerData = MUXSDKCustomerViewerData()
viewerData.viewerApplicationName = "my-app-name"
let customerData = MUXSDKCustomerData(
customerPlayerData: playerData,
videoData: videoData,
viewData: viewData,
customData: customData,
viewerData: viewerData
)
guard let player = self.kalturaPlayer, let data = customerData else {
return
}
MUXSDKStats.monitorPlayer(
player: player,
playerName: playerName,
customerData: data
)

For more complete examples check the demo apps in the repo.

After you've integrated, start playing a video in your player. A few minutes after you stop watching, you'll see the results in your Mux data dashboard. Login to the dashboard and find the environment that corresponds to your env_key and look for video views.

3Make your data actionable

The only required field is env_key. But without some more metadata the metrics in your dashboard will lack the necessary information to take meaningful actions. Metadata allows you to search and filter on important fields in order to diagnose issues and optimize the playback experience for your end users.

Metadata fields are provided via the MUXSDKCustomerPlayerData and MUXSDKCustomerVideoData objects.

For the full list of properties view the header files for this interfaces:

For more details about each property, view the Make your data actionable guide.

let playerName = "My Main Player"
let playerData = MUXSDKCustomerPlayerData(environmentKey: "ENV_KEY")
playerData.experimentName = "player_test_A"
playerData.playerName = playerName
playerData.playerVersion = "1.0.0"
let videoData = MUXSDKCustomerVideoData()
videoData.videoId = "abcd123"
videoData.videoTitle = "My Great Video"
videoData.videoSeries = "Weekly Great Videos"
videoData.videoDuration = 120000 // in milliseconds
videoData.videoIsLive = false
videoData.videoCdn = "cdn"
let viewData = MUXSDKCustomerViewData()
viewData.viewSessionId = "my session id"
let customData = MUXSDKCustomData()
customData.customData1 = "Custom data 1"
customData.customData2 = "Custom Data 2"
let viewerData = MUXSDKCustomerViewerData()
viewerData.viewerApplicationName = "MUX Kaltura DemoApp"
let customerData = MUXSDKCustomerData(
customerPlayerData: playerData,
videoData: videoData,
viewData: viewData,
customData: customData,
viewerData: viewerData
)
guard let player = self.kalturaPlayer, let data = customerData else {
return
}
MUXSDKStats.monitorPlayer(
player: player,
playerName: playerName,
customerData: data
)

4Set or update metadata after monitor

There are some cases where you may not have the full set of metadata until after the video playback has started. In this case, you should omit the values when you first call monitorPlayer. Then, once you have the metadata, you can update the metadata with the setCustomerDataForPlayer method.

// Sometime later before the player is destroyed you can do this:
// The player name ("iOS KalturaPlayer" in this example) should be a player that
// you have already called `monitorPlayer` method with
let videoData = MUXSDKCustomerVideoData()
videoData.videoTitle = "Big Buck Bunny"
videoData.videoSeries = "Updated animation"
// In this example we are updating videoData, but the same can be done
// for updating playerData, customData or viewData
// the values in customerData passed as nil will keep previously set data
// viewerData can't be updated
guard let customerData = MUXSDKCustomerData(
customerPlayerData: nil,
videoData: videoData,
viewData: nil,
customData: nil,
viewerData: nil
) else {
return
}
MUXSDKStats.setCustomerDataForPlayer(name: "iOS KalturaPlayer", customerData: customerData)

5Advanced

Changing the Video

​ There are two cases where the underlying tracking of the video view need to be reset. First, when you load a new source URL into an existing player, and second when the program within a singular stream changes (such as a program within a live stream).

Note: You do not need to change the video info when changing to a different source of the same video content (e.g. different resolution or video format). ​

New source

​ When you change to a new video (in the same player) you need to update the information that Mux knows about the current video. Examples of when this is needed are: ​

  • The player advances to the next video in a playlist
  • The user selects a different video to play ​ This is done by calling videoChangeForPlayer which will remove all previous video data and reset all metrics for the video view. You can include any metadata when changing the video but you should only need to update the values that start with video_. ​ It is required to call videoChangeForPlayer immediately before telling the player which new source to play. ​
// Example of changing the media in Kaltura Player
// Call MUX videoChange before stop, because playkit stop will replace current item for nil
let playerData = MUXSDKCustomerPlayerData(environmentKey: self.environmentKey)
playerData?.playerName = self.playerName
let videoData = MUXSDKCustomerVideoData()
videoData.videoTitle = "Apple Video Kaltura"
videoData.videoId = "apple"
videoData.videoSeries = "conference"
let viewData = MUXSDKCustomerViewData()
viewData.viewSessionId = "my second session id"
let customData = MUXSDKCustomData()
customData.customData1 = "Kaltura test video change"
let viewerData = MUXSDKCustomerViewerData()
viewerData.viewerApplicationName = "MUX Kaltura DemoApp"
guard let customerData = MUXSDKCustomerData(
customerPlayerData: playerData,
videoData: videoData,
viewData: viewData,
customData: customData,
viewerData: viewerData
) else {
return
}
MUXSDKStats.videoChangeForPlayer(name: "iOS KalturaPlayer", customerData: customerData)
// Change media in your player (your steps may vary)
// For example:
// Resets The Player And Prepares for Change Media
self.kalturaPlayer?.stop()
// Prepare PlayKit player
self.kalturaPlayer?.prepare(newMediaConfig)
// Wait for `canPlay` event to play
self.kalturaPlayer?.addObserver(self, events: [PlayerEvent.canPlay]) { event in
self.kalturaPlayer?.play()
}

New program (in single stream)

​ In some cases, you may have the program change within a stream, and you may want to track each program as a view on its own. An example of this is a live stream that streams multiple programs back to back, with no interruptions. ​ In this case, call programChangeForPlayer:name:customerData. This will remove all previous video data and reset all metrics for the video view, creating a new video view. You can include any metadata when changing the video but you should only need to update the values that start with video.

Usage with Google Interactive Media Ads (IMA)

If you are using Google Interactive Media Ads and the PlayKit_IMA SDK, you can track ad playback events by installing the mux-stats-google-ima-kaltura-ios companion package.

Please note: A fully functioning PlayKit_IMA integration is required for ad playback tracking in your iOS or tvOS application.

Add the following to your Podfile and run pod install

'Mux-Stats-Google-IMA-Kaltura' ~> '2.0.0'

Initialize the Mux monitor with MUXSDKStats.monitorPlayer. Create an listener instance by calling MUXSDKImaKalturaListener(playerBinding: playerBinding, player: player). Start dispatching the events by calling start on the listener instance.

import MUXSDKStatsKaltura
// Follow the instructions from pod 'PlayKit_IMA' to set up
// your IMA plugin configuration in the loadPlayer method
//
// When you call `monitorPlayer:withPlayer:playerName:customerData:`
// from your ViewController, you will get back a MUXSDKPlayerBinding object
let playerBinding = MUXSDKStats.monitorPlayer(
player: player,
playerName: self.playerName,
customerData: data
)
// Use the MUXSDKPlayerBinding object and the Player instance to initialize the MUXSDKImaKalturaListener class
// and call start on the listener object
let listener = MUXSDKImaKalturaListener(playerBinding: playerBinding, player: player)
listener.start()

You can find a complete example here.

Track orientation change events

You can optionally track orientationchange events. To use this functionality, call the orientationChangeForPlayer method. ​ These events will show up on the events log on the view views page.

override func viewWillTransition(to size: CGSize, with coordinator: UIViewControllerTransitionCoordinator) {
super.viewWillTransition(to: size, with: coordinator)
let orientation = UIDevice.current.orientation.isLandscape ? MUXSDKViewOrientation.landscape : MUXSDKViewOrientation.portrait
MUXSDKStats.orientationChangeForPlayer(name: "iOS KalturaPlayer", orientation: orientation)
}

Handling errors manually

By default, automaticErrorTracking is enabled which means the Mux SDK will catch errors that the player throws and track an error event. Error tracking is meant for fatal errors. When an error is thrown it will mark the view as having encountered an error in the Mux dashboard and the view will no longer be monitored. ​ If you want to disable automatic and track errors manually you can do by passing in automaticErrorTracking: false to the monitorPlayer method that you are using. ​ Whether automatic error tracking is enabled or disabled, you can dispatch errors manually with dispatchError.

let playerName = "iOS KalturaPlayer"
let playerData = MUXSDKCustomerPlayerData(environmentKey: "ENV_KEY")
// ...insert player metadata
let videoData = MUXSDKCustomerVideoData()
// ...insert video metadata
let customerData = MUXSDKCustomerData(customerPlayerData: playerData, videoData: videoData, viewData: nil, customData: nil, viewerData: nil)
guard let player = self.kalturaPlayer, let data = customerData else {
return
}
MUXSDKStats.monitorPlayer(player: player, playerName: self.playerName, customerData: data, automaticErrorTracking: false)
// Later, you can dispatch an error yourself
MUXSDKStats.dispatchErrorForPlayer(name: playerName, code: "1234", message: "Something is not right")

Release notes

Current release

v3.0.0

Improvements:

  • Repackage SDK as source distribution
  • Add Swift Package Manager support
  • Raise minimum deployment targets to iOS 13 and tvOS 13

Breaking:

  • Rename module name from Mux_Stats_Google_IMA_Kaltura to MUXSDKStatsKaltura

Known Issues:

  • Cocoapod pod spec linting fails on Xcode 14.3 and above due to Cocoapods/Cocoapods issue #11839. As a workaround use xcode-select to switch to Xcode 14.2 before linting.

Previous Releases

v2.0.1

Fixes:

  • Fix build issues in react-native projects

v2.0.0

Fixes: *Update MuxCore dependency and rebuild with recent tools. Some linkage changes have been necessary, but you shouldn't see any issues. You may require Xcode 14 to use this version of the Data SDK for Kaltura

v1.1.1

  • Fix: Change minimum deployment target to iOS 9.0 and tvOS 9.0

v1.1.0

  • Test: Unit test for destroy player
  • Feature: Support for Google IMA SDK Listener

v1.0.0

  • Fix: Missing play event
  • Fix: Improve rendition change detection
  • Fix: Missing rebuffering metrics
  • Test: Unit test infrastructure
  • Test: Add test coverage

v0.3.0

  • Third beta release of the Kaltura SDK for iOS
  • Adds tvOS support
  • Adds tvOS target to DemoApp and updates example project

v0.2.0

  • Second beta release of the Kaltura SDK for iOS
  • Adds setCustomerDataForPlayer to update metadata after monitor call
  • Adds videoChangeForPlayer to update metadata when a video change occurs
  • Adds programChangeForPlayer:name:customerData: to update metadata when a program change within a stream
  • Adds orientationChangeForPlayer to track orientation changes
  • Adds manual error tracking with dispatchError

v0.1.0

  • First beta release of the Kaltura SDK for iOS

Was this page helpful?