Monitor AVPlayer

Connect Mux Data to AVPlayer to collect playback performance metrics. Use this guide when your iOS, tvOS, or visionOS application plays video with AVPlayer.

In this guide:

Features
The features supported by Mux Data for this player.

1 Install the Mux Data SDK
Install Mux-Stats-AVPlayer and import the framework into your application.

2 Initialize the monitor for your AVPlayer instance
The Mux monitor attaches to either AVPlayerLayer or AVPlayerViewController.

3 Make your data actionable
Use metadata fields to make the data collected by Mux actionable and useful.

4 Set or update metadata after monitor
If you do not have all the metadata available at initialization time, update metadata fields later.

5 Advanced
Depending on the details of your implementation, you may want to leverage some of the advanced options of Mux-Stats-AVPlayer.

Mux Data collects playback performance metrics from AVPlayer. Use this guide when your iOS, tvOS, or visionOS application plays video with AVPlayer and you want to monitor the playback experience of your viewers. You do not need Mux Video to use Mux Data.

Mux Data integration for AVPlayer supports applications running on iOS 12.0 or newer, tvOS 12.0 or newer, and Mac Catalyst that use AVPlayerViewController, AVPlayerLayer, or a standalone AVPlayer playing audio. Applications running on visionOS 1.0 and higher are also supported if they use AVPlayerViewController or a standalone AVPlayer playing audio.

This integration uses Mux's core Objective-C SDK and the full source can be seen here: muxinc/mux-stats-sdk-avplayer. This SDK is packaged as an xcframework.

Features

The following data can be collected by the Mux Data SDK when you use the AVPlayer SDK:

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
• Ads metrics
• Customizable Error Tracking
• Custom Beacon Domain
• Extraction of HLS Session Data
• Live Stream Latency metric

Notes:

Packaged with: cocoapods, SPM and carthage. Request Latency is not available.

1 Install the Mux Data SDK

Installation

Installing in Xcode with Swift Package Manager

1. In Xcode click "File" > "Swift Packages" > "Add Package Dependency..."

2. The package repository URL is https://github.com/muxinc/mux-stats-sdk-avplayer.git

3. Click Next.

4. Since the MUXSDKStats follows SemVer, we recommend setting the "Rules" to install the latest version and choosing the option "Up to Next Major". Here's an overview of the different SPM Dependency Rules and their semantics.

Installing in Package.swift

Open your Package.swift file, add the following to dependencies:

Note that MUXSDKStats 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 library targets is now supported. An example for setting this up is available here.

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:

This will install Mux-Stats-AVPlayer and the latest current release of our core Objective-C Library.

Next, add the correct import statement into your application.

2 Initialize the monitor for your AVPlayer 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 monitorAVPlayerViewController(_:withPlayerName:customerData:). If you are using AVPlayerLayer, use monitorAVPlayerLayer(_:withPlayerName:customerData:) instead.

The playerName parameter is a string that identifies this instance of your player. When calling destroyPlayer(_:) or videoChange(forPlayer:with:) later on, you will need this string. Each instance of a player that runs simultaneously in your application should have a different playerName.

If you are using SwiftUI, attach the monitor in the onAppear action for your view. This ensures that the Mux Data SDK is able to get the dimensions of the view which is used to calculate video quality metrics.

For more complete examples, check the demo app 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. Log in to the dashboard and find the environment that corresponds to your env_key and look for video views.

3 Make 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 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, refer to the MuxCore headers in the latest stats-sdk-objc release.

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

4 Set or update metadata after monitor

There are 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 monitorAVPlayerLayer, monitorAVPlayerViewController, or monitorAVPlayer. Once you have the metadata, update it by calling setCustomerData(_:forPlayer:).

5 Advanced

Changing the Video

There are two cases where the underlying tracking of the video view needs 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).

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 videoChange(forPlayer:with:), 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 videoChange(forPlayer:with:) immediately before telling the player which new source to play. This recommendation changed in v1.2.0. It is also required to call play() for the player after replacing the current item.

If you have new player data, you can include it in the customerData you pass to videoChange(forPlayer:with:).

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 programChange(forPlayer:with:). 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 specifically either the iOS SDK GoogleAds-IMA-iOS-SDK or the tvOS SDK GoogleAds-IMA-tvOS-SDK, then we have another plugin library that integrates tracking of ad playback events. You should have a fully functioning Google Ads IMA integration working in your iOS or tvOS application first.

Track orientation change events

As of 1.3.0, Mux-Stats-AVPlayer can optionally track orientationchange events. To use this functionality, call the orientationChange(forPlayer:with:) method.

Usage with AVQueuePlayer

To use with AVQueuePlayer, you will need to follow these steps:

1. Listen for AVPlayerItemDidPlayToEndTime in your application
2. When that notification fires, call videoChange(forPlayer:with:)

Overriding device metadata

By default, the Mux Data SDK for iOS collects data about your users' device to report on the dashboard. If you wish to provide your own device metadata, you can use CustomerViewerData to override the detected values.

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. 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 error tracking and track errors manually, you can do so by passing false as the automaticErrorTracking parameter to the monitorAVPlayerLayer, monitorAVPlayerViewController, or monitorAVPlayer method you are using.

Whether automatic error tracking is enabled or disabled, you can dispatch errors manually with dispatchError(_:withMessage:forPlayer:).