Monitor AVPlayer

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

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

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

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

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:

copy
pod 'Mux-Stats-AVPlayer', '~>2.8'  

This will install Mux-Stats-AVPlayer 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.

copy
@import MUXSDKStats;  

2Initialize the monitor for your AVPlayer instance

Get your ENV_KEY from the Mux environments dashboard.

The example below uses monitorAVPlayerViewController. If you are using AVPlayerLayer, use monitorAVPlayerLayer instead.

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

NSString *playName = @"iOS AVPlayer";
MUXSDKCustomerPlayerData *playerData = [[MUXSDKCustomerPlayerData alloc] initWithEnvironmentKey:@"ENV_KEY"];
// ...insert player metadata

MUXSDKCustomerVideoData *videoData = [MUXSDKCustomerVideoData new];
// ...insert video metadata

AVPlayerLayer *player = [AVPlayerViewController new];
[MUXSDKStats monitorAVPlayerViewController:player withPlayerName:playName playerData:playerData videoData:videoData];
// if you're using AVPlayerLayer instead of AVPlayerViewController use this instead:
// [MUXSDKStats monitorAVPlayerLayer:player withPlayerName:@"awesome" playerData:playerData videoData:videoData];  

For more complete examples check the 3 demo apps in the repo. There is one demo app for iOS objective-c, one for iOS swift and another one for TVOS.

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:

• MUXSDKCustomerPlayerData.h
• MUXSDKCustomerVideoData.h

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

NSString *playName = @"iOS AVPlayer";
MUXSDKCustomerPlayerData *playerData = [[MUXSDKCustomerPlayerData alloc] initWithEnvironmentKey:@"ENV_KEY"];
playerData.viewerUserId = @"1234";
playerData.experimentName = @"player_test_A";
// note that the 'playerName' field here is unrelated to the 'playName' variable above
playerData.playerName = @"My Main Player";
playerData.playerVersion = @"1.0.0";

MUXSDKCustomerVideoData *videoData = [MUXSDKCustomerVideoData new];
videoData.videoId = @"abcd123";
videoData.videoTitle = @"My Great Video";
videoData.videoSeries = @"Weekly Great Videos";
videoData.videoDuration = @(120000); // in milliseconds
videoData.videoIsLive = @NO;
videoData.videoCdn = @"cdn";

AVPlayerLayer *player = [AVPlayerViewController new];
[MUXSDKStats monitorAVPlayerViewController:player withPlayerName:playName playerData:playerData videoData:videoData];
// if you're using AVPlayerLayer instead of AVPlayerViewController use this instead:
// [MUXSDKStats monitorAVPlayerLayer:player withPlayerName:@"awesome" playerData:playerData videoData:videoData];  

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 monitorAVPlayer*. Then, once you have the metadata, you can update the metadata with the updateCustomerDataForPlayer method.

// Sometime later before the player is destroyed you can do this:
// The player name ("iOS AVPlayer" in this example) should be a player that
// you have already called one of the `monitorAvPlayer` methods with
MUXSDKCustomerVideoData *videoData = [MUXSDKCustomerVideoData new];
videoData.videoTitle = @"Big Buck Bunny";
videoData.videoId = @"bigbuckbunny";

// 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
MUXSDKCustomerData *customerData = [[MUXSDKCustomerData alloc] init];
customerData.customerVideoData = videoData;
[MUXSDKStats setCustomerData:customerData forPlayer:@"iOS AVPlayer"];  

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. This recommendation changed in v1.2.0.

It is also required to call player.play after replacing the current item.

If you have new player data you instead call videoChangeForPlayer.

copy
// Example of changing the AVPlayerItem

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"
MUXSDKStats.videoChange(forPlayer: "AVPlayer", with: videoData)

player.replaceCurrentItem(with: AVPlayerItem(url: url!))
// calling `play()` here is necessary
player.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:withCustomerData:. 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 library that integrates for tracking ad playback events.

You should have a fully functioning GoogleAds-IMA integration working in your iOS or TvOS application before adding the Mux tracking. To add Mux ad tracking follow these steps:

1. Add the pod 'Mux-Stats-Google-IMA' ~> '0.6 to your Podfile and run pod install
2. import Mux_Stats_Google_IMA
3. After initializing the Mux monitor with monitorAVPlayerViewController or monitorAVPlayerLayer, save this value to a variable (below it's called playerBinding)
4. Create an imaListener instance by calling MuxImaListener.init(playerBinding: playerBinding!).
5. Dispatch events to the imaListener in your adsLoader and adsManager delegate methods.

@import Mux_Stats_Google_IMA;

- (void)viewDidLoad {
  // Follow the instructions from pod 'GoogleAds-IMA-iOS-SDK' to set up
  // your adsLoader and set your ViewController as the delegate
  //
  // From your ViewController, when you call either
  //    monitorAVPlayerViewController:withPlayerName:playerData:videoData:
  //    monitorAVPlayerLayer:withPlayerName:playerData:videoData:
  //
  // You will get back a MUXSDKPlayerBinding object
  [MUXSDKPlayerBinding *playerBinding] = [MUXSDKStats monitorAVPlayerViewController:_avplayerController
                                  withPlayerName:DEMO_PLAYER_NAME
                                      playerData:playerData
                                       videoData:videoData];
  //
  // Use the MUXSDKPlayerBinding object to initialize the MuxImaListener class
  //
  _imaListener = [[MuxImaListener alloc] initWithPlayerBinding:playerBinding];
}
// when the adsLoader fires adsLoadedWithData you get a
// reference to the adsManager. Set your ViewController as the delegate
// for the adsManager
- (void)adsLoader:(IMAAdsLoader *)loader adsLoadedWithData:(IMAAdsLoadedData *)adsLoadedData {
    _adsManager = adsLoadedData.adsManager;
    _adsManager.delegate = self;
    IMAAdsRenderingSettings *adsRenderingSettings = [[IMAAdsRenderingSettings alloc] init];
    adsRenderingSettings.webOpenerPresentingController = self;
    [_adsManager initializeWithAdsRenderingSettings:adsRenderingSettings];
}
// Use these delegate methods to call dispatchEvent and send events
// through the imaListener
- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdEvent:(IMAAdEvent *)event {
    // When the SDK notified us that ads have been loaded, play them.
    if (event.type == kIMAAdEvent_LOADED) {
        [_adsManager start];
    }
    if (_imaListener != nil) {
        [_imaListener dispatchEvent:event];
    }
}

- (void)adsManager:(IMAAdsManager *)adsManager didReceiveAdError:(IMAAdError *)error {
    [_avplayer play];
    if (_imaListener != nil) {
        [_imaListener dispatchError: error.message];
    }
}

- (void)adsManagerDidRequestContentPause:(IMAAdsManager *)adsManager {
    [_avplayer pause];
    if (_imaListener != nil) {
        [_imaListener onContentPauseOrResume:true];
    }
}

- (void)adsManagerDidRequestContentResume:(IMAAdsManager *)adsManager {
    [_avplayer play];
    [_imaListener onContentPauseOrResume:false];
}  

For complete example projects look in the "/apps" directory of mux-stats-sdk-avplayer on GitHub.

All of these apps have examples with Google IMA ads.

• DemoApp is an iOS app written in objective-c
• video-demo is an iOS app written in Swift
• TVDemoApp is a TVOS app written in objective-c

Track orientation change events

As of 1.3.0 Mux-Stats-AVPlayer 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.

@implementation ViewController

  - (void)viewWillTransitionToSize:(CGSize)size
       withTransitionCoordinator:(id<UIViewControllerTransitionCoordinator>)coordinator {
    [coordinator animateAlongsideTransition:^(id<UIViewControllerTransitionCoordinatorContext> context) {} completion:^(id<UIViewControllerTransitionCoordinatorContext> context) {
        [MUXSDKStats orientationChangeForPlayer:DEMO_PLAYER_NAME withOrientation:[self viewOrientationForSize:size]];

    }];
    }

  - (MUXSDKViewOrientation) viewOrientationForSize:(CGSize)size {
      return (size.width > size.height) ? MUXSDKViewOrientationLandscape : MUXSDKViewOrientationPortrait;
  }

@end  

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 videoChangeForPlayer:withVideoData

Here is an example that sets up a AVQueuePlayer with two items, and listener after the first item finishes playing and passes in new videoData.

copy
let playName = "iOS AVPlayer"

override func viewDidLoad() {
    super.viewDidLoad()

    let item1 = AVPlayerItem(url: URL(string: "https://stream.mux.com/jY02nK1sxQKmJiQ7ltXY01w9LZQWdtNetE.m3u8")!)
    let item2 = AVPlayerItem(url: URL(string: "https://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8")!)
    NotificationCenter.default.addObserver(
        self,
        selector: #selector(self.playerItemDidReachEnd),
        name: NSNotification.Name.AVPlayerItemDidPlayToEndTime,
        object: item1
    )
    player = AVQueuePlayer(items: [item1, item2])

    let playerData = MUXSDKCustomerPlayerData(environmentKey: "ENV_KEY");
    playerData?.playerName = "AVPlayer"
    let videoData = MUXSDKCustomerVideoData();
    videoData.videoIsLive = false;
    videoData.videoTitle = "Title1"
    MUXSDKStats.monitorAVPlayerViewController(self, withPlayerName: playName, playerData: playerData!, videoData: videoData);
    player!.play()
}

@objc func playerItemDidReachEnd (notification: NSNotification) {
    let videoData = MUXSDKCustomerVideoData();
    videoData.videoTitle = "Title2"
    videoData.videoId = "applekeynote2010-2"
    MUXSDKStats.videoChange(forPlayer: playName, with: videoData)
}  

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 monitor* method that you are using.

Weather automatic error tracking is enabled or disabled, you can dispatch errors manually with dispatchError.

NSString *playName = "iOS AVPlayer";

MUXSDKCustomerPlayerData *playerData = [[MUXSDKCustomerPlayerData alloc] initWithEnvironmentKey:@"ENV_KEY"];
// ...insert player metadata
MUXSDKCustomerVideoData *videoData = [MUXSDKCustomerVideoData new];
// ...insert video metadata
AVPlayerLayer *player = [AVPlayerLayer new];
[MUXSDKStats monitorAVPlayerLayer:player
                   withPlayerName:playName
                       playerData:playerData
                        videoData:videoData
                     automaticErrorTracking: false];

//
// Later, you can dispatch an error yourself
//
[MUXSDKStats dispatchError:@"1234"
               withMessage:@"Something is not right"
                 forPlayer:playName];  

Installing manually with Carthage (not recommended)

The recommended way to install the Mux SDKs is with CocoaPods. However, if you want to install manually via Carthage that is supported only for version 1.x of Mux-Stats-AVPlayer. Carthage does not work with Xcode 12, so if you are using Carthage with Xcode 12, please see the following workaround.

If you are installing Mux-Stats-AVPlayer your Cartfile will also need to specify the mux-core library. Like this:

copy
github "muxinc/mux-stats-sdk-avplayer" ~> 2.6.0
github "muxinc/stats-sdk-objc" ~> 3.5.0  

After running carthage update --platform iOS follow the usual instructions for linking the frameworks. The Carthage README on GitHub walks through that and this guide is a good walk-through.

If you are using the Google IMA integration there are a few extra steps. Your Cartfile will have these dependencies:

copy
github "muxinc/mux-stats-sdk-avplayer" ~> 2.6.0
github "muxinc/stats-sdk-objc" ~> 3.5.0
github "muxinc/mux-stats-google-ima" ~> 0.5.0  

In addition to specifying these dependencies in the Cartfile and linking them up, you will also need to follow Google's documentation for "Manually, using the SDK download".

App Store warning: ITMS-90809: Deprecated API Usage

It has come up a few times that users of our iOS library get this warning from Apple.

If you run grep -r "UIWebView" . in your project you will see a match coming from the dSYM/ directory in Mux-Core. At first glance, we too thought our SDK was triggering this warning.

However, after looking into this with several different applications we found that the warning was not being triggered by our SDK. In every case it was coming from another 3rd party.

Note that none of the Mux iOS libraries (including Mux-Core and Mux-Stats-AVPlayer) use UIWebView. If you are getting this warning you must have another SDK that is using UIWebView.

The reason there is some confusion around this and the reason you get a match in the dSYM/ directory in Mux-Core is because our SDK links to UIKit and targets a version of iOS that may include UIWebView. The dSYM files are used for debugging purposes and they do not contain any functional code. You may see that this same confusion came up in other SDKs like Mapbox and Stripe (listed below).

Resources:

• Mux issue #32
• Mux issue #53
• Mapbox issue #373
• Stripe issue #82

Release notes

Current release

v2.8.0

• Fixes a bug that caused missing seek events when seeking programmatically

Previous Releases

v2.7.0

• Add player_live_edge_program_time
• Add player_program_time

v2.6.0

• Allow overriding of viewer information (application name)
• Tests for AVQueuePlayer
• Custom beacon collection domains
• Adds programChangeForPlayer:withCustomerData:

v2.5.0

• Consolidates MUXSDKCustomerViewData, MUXSDKCustomerVideoData, and MUXSDKCustomerPlayerData into MUXSDKCustomerData and deprecates methods that treat these as separate arguments
• Adds support for custom dimensions

v2.4.2

• Replaces identifierForVendor with alternative UUID
• Fixes race condition when checking viewer connection type

v2.4.1

• Fixes a bug when disabling automatic video change that could sometimes result in views not being split apart and/or having a high seek latency.

v2.4.0

• Automatically build statically linked frameworks
• Removes use of categories
• Updates documentation

v2.3.2

• Adds a new method to disable built in videochange calls when using AVQueuePlayer. This method can be called as:

copy
[MUXSDKStats setAutomaticVideoChange:PLAYER_NAME enabled:false];  

v2.2.2

• Fixes a code signing is missing error for Mac Catalyst
• Fixes a crash from a KVO observer being removed incorrectly
• Fixes bugs in seeking tracking for tvOS

v2.2.1

• Fixes a bug where AirPlay rebuffering was incorrectly reported as paused

v2.2.0

• Add Swift PM support

v2.1.0

• Submits viewer_device_model field
• Updates our implementation of the Google IMA SDK in demo apps to work with the latest version
• Automated UI test for ads

v2.0.0

This release moves the build process to use XCFramework bundle type. For iOS, there are no changes required to your application code.

If you are using this SDK with TVOS the name of the module has changed (the Tv suffix is no longer needed):

TVOS before 2.0:

copy
@import MuxCoreTv;
@import MUXSDKStatsTv;  

TVOS after 2.0:

copy
@import MuxCore;
@import MUXSDKStats;  

v1.7.0

• Adds support for view_session_id.
• Adds support for player_remote_played - this will be true when a video is shown over Airplay.

v1.6.0

• Add viewer_connection_type for iOS (either wifi or cellular). Detecting viewer_connection type is done off the main thread to make sure this doesn't interfere with the performance of your application. Note that viewer_connection_type is omitted from TVOS because in versions before TVOS 12 there is no reliable way to detect wifi vs. ethernet.

v1.4.1

• (bugfix) monitorAVPlayerLayer with optional argument automaticErrorTracking was misnamed to withAutomaticErrorTracking. This has been changed to the correct name which is consistent with the corresponding monitorAVPlayerViewController method (thanks @hlung in #58)
• (bugfix) nullability warnings for MUXSDKStats (thanks @hlung in #58)

v1.4.0

• add option to disable automatic error tracking when calling either monitorAVPlayerViewController or monitorAVPlayerLayer
• add MUXSDKStats.dispatchError method to manually dispatch an error

You probably will not need to use these features, but if your player is throwing noisy non-fatal errors or you want to catch the player errors yourself and take precise control over the error code and error message then you now have that ability.

Dispatching an error should only be used for fatal errors. When the player goes into the error state then it is no longer being tracked and the view will show up as having encountered an error in the Mux dashboard.

v1.3.8

• Performance updates that optimize main thread usage.

v1.3.7

• Bug fix: Update our framework build process to be compatible with carthage 0.35.0. See the GitHub issue for more details. The gist of it is that Carthage no longer ignores dSYM files, so those need to be packaged up correctly with the framework.

v1.3.6

• Bug fix: Rebuild frameworks without importing UIKit (we don't use it). This came to our attention when it was reported that our SDK was triggering this warning from Apple “The App Store will no longer accept new apps using UIWebView as of April 2020 and app updates using UIWebView as of December 2020.”

v1.3.5

• Bug fix for usage with AVQueuePlayer. Unlike other methods of changing the playerItem on an AVPlayer instance, when AVQueuePlayer progresses from one item to the next the rate observer does not fire so we have to handle it in a special case. See instructions above for usage with AVQueuePlayer.

v1.3.4

• Update scaling logic to report upscaling based on logical resolution, not physical resolution. This will result in lower upscaling percentages, but correlates more closely with perceived visual quality

v1.3.3

• Fix a bug to make sure all needed header files are included in the tvOS framework

v1.3.2

• Fix a bug in request metrics tracking, request metric event timestamps should always be sent in Unix millisecond timestamps, not seconds.

v1.3.1

• Fix an issue where multiple AVPlayer instances that are tracked simultaneously report the same throughput metrics.

v1.3.0

• Add support for orientationchange events. This can be dispatched with MUXSDKStats orientationChangeForPlayer: withOrientation:
• Add support for automatically tracking renditionchange events. You can see this new event in the events list for a view.
• Improve implementation for bandwidth metrics calculation. Instead of polling for changes on the access log, use AVPlayerItemNewAccessLogEntryNotification
• Fix bug in programChange so that it works consistently now
• Dispatch viewend when destoryPlayer is called. Previously this was not called which didn't affect metrics, but resulted in a viewdropped event in the events list.

v1.2.1

• Fix bug that prevents request metrics tracking from working. AVPlayer gives us requestStart and requestResponseEnd, so with those data points we can track throughput. This bug fix requires Mux-Stats-Core v2.1.3 or greater. Run pod update Mux-Stats-AVPlayer and pod update Mux-Stats-Core to get the latest versions.

v1.2.0

• Fix bug in Mux-Stats-AVPlayer that prevents videoChangeForPlayer from working
• Fix bug in AVPlayer SDK where it misses initial play event at times if SDK is initialized too late. This could cause some iOS views to not be displayed in the real-time dashboard, and to potentially have incomplete metrics such as Video Startup Time.
• Add ability to optionally pass in new player data when calling videoChangeForPlayer: videoChangeForPlayer:withPlayerData:withVideoData

v1.1.3

• Fix a bug to prevent an edge-case scenario where crashes can happen after calling destroyPlayer when observers have not yet bet set up on the player instance.

v1.1.2

• bump dependency version of Mux-Stats-Core to 2.1

v1.1.1

• bugfix - report the correct Mux Plugin Version. This SDK was erroneously reporting the incorrect 'Mux Plugin Version' attribute for views

v1.1.0

• Added new static method to MUXSDKStats updateCustomerDataForPlayer:withPlayerData:withVideoData. This allows a developer to update customerPlayerData and/or customerVideoData after the SDK has been initialized. Not all metadata can be changed if it was previously set, but all metadata that was not set initially can be updated to the intended values.

v1.0.2

• Fix a bug that caused slowness when loading AVPlayer due to checking currentItem.asset.duration before the duration was loaded

v1.0.1

• Fix a bug with incorrect source video duration

v1.0.0

• Extract GoogleAds-IMA-iOS-SDK into a separate library (Mux-Stats-Google-IMA). The reason for this change was to remove the hard dependency on GoogleAds-IMA-iOS-SDK
• In order to implement ad events tracking, please follow the instructions to use this library (Mux-Stats-AVPlayer) in conjunction with Mux-Stats-Google-IMA and GoogleAds-IMA-iOS-SDK

0.1.5

• add support for tracking ad playback with GoogleAds-IMA-iOS-SDK

0.1.1

• add support for AVPlayer monitoring