This is a guide for building a custom integration with Mux Data in Objective-C.
Mux has a pre-built integration with Apple's AVPlayer for iOS and tvOS applications; for these players, see here: iOS Integration Guide.
If the player that you use does not expose the AVPlayer instance directly, swaps between multiple instances during playback, or uses some other playback mechanism completely, a custom integration may be needed.
Before proceeding, read the following overview: Building a Custom Integration.
In addition, the source code for Mux's integration with Apple's AVPlayer is open source and can be found in the Mux-Stats-AVPlayer GitHub repository. This project is a good example of how to use the Objective-C core library in building a player integration.
https://github.com/muxinc/stats-sdk-objc.gitnext.MuxCore follows SemVer, we recommend setting the "Rules" to install the latest version and choosing the option "Up to Next Major".To include the core Objective-C library via CocoaPods, modify your Podfile to use frameworks by including use_frameworks! and then add the following pod to your Podfile:
pod "Mux-Stats-Core", "~> 3.11"This will include our current release of the core Objective-C library. There will be no breaking updates within major versions of this library, so you can safely run pod update.
Since version 3, Mux-Stats-Core has been updated for Xcode 12 and XCFrameworks bundle type.
If you do not you use CocoaPods and wish to include the library manually, view the XCFramework directory in the Mux Objective-C Core SDK and dragging the framework into your Xcode project.
There is no need to initialize a player monitor for each player that is being tracked, as this happens automatically when events are emitted for a specific player. For the Objective-C library, the Environment and Viewer-specific data should be emitted to the SDK globally as follows.
MUXSDKEnvironmentData *environmentData = [[MUXSDKEnvironmentData alloc] init];
[environmentData setMuxViewerId:[[[UIDevice currentDevice] identifierForVendor] UUIDString]];
MUXSDKViewerData *viewerData = [[MUXSDKViewerData alloc] init];
NSString *bundleId = [[NSBundle mainBundle] bundleIdentifier];
if (bundleId) {
[viewerData setViewerApplicationName:bundleId];
}
// Set additional Viewer data as above
MUXSDKDataEvent *dataEvent = [[MUXSDKDataEvent alloc] init];
[dataEvent setEnvironmentData:environmentData];
[dataEvent setViewerData:viewerData];
[MUXSDKCore dispatchGlobalDataEvent:dataEvent];The only field that should be modified within MUXSDKEnvironmentData is the muxViewerId, via setMuxViewerId, which should be a device-specific string. This field is used within the Mux Dashboard as the Viewer ID in the case that a user-specific value is not provided in the metadata, via [MUXSDKCustomerViewerData setViewerUserId:].
For MUXSDKViewerData, the fields that may be provided are the following.
@property (nullable) NSString *viewerApplicationEngine;
@property (nullable) NSString *viewerApplicationName;
@property (nullable) NSString *viewerApplicationVersion;
@property (nullable) NSString *viewerConnectionType;
@property (nullable) NSString *viewerDeviceCategory;
@property (nullable) NSString *viewerDeviceManufacturer;
@property (nullable) NSString *viewerDeviceName;
@property (nullable) NSString *viewerOsArchitecture;
@property (nullable) NSString *viewerOsFamily;
@property (nullable) NSString *viewerOsVersion;See the AVPlayer integration for example values used.
For the Objective-C core SDK, there are two types of events that should be emitted: data events and playback events. Data events are events that update metadata about the video or view, whereas playback events are those described here: Mux Playback Events.
All events are emitted to a specific Player, so make sure to include the unique player ID with each event emitted.
Data events are emitted via [MUXSDKCore dispatchEvent: forPlayer:], and should be emitted when any of the following pieces of metadata change:
MUXSDKVideoDatavideoSourceWidth - width of the video currently being played, in pixelsvideoSourceHeight - height of the video currently being played, in pixelsvideoSourceIsLive - whether the video currently being played is live or notvideoSourceDuration - the duration, in milliseconds, of the video currently being playedvideoSourceAdvertisedBitrate - the bitrate of the current rendition being played, in bits per secondvideoSourceFrameDrops - the total number of dropped video frames for the current ViewMUXSDKCustomerPlayerData, as defined here: MetadataMUXSDKCustomerVideoData, as defined here: MetadataMUXSDKCustomerViewData, as defined here: MetadataWhen any of the above fields change, do the following:
MUXSDKVideoData , MUXSDKCustomerPlayerData, MUXSDKCustomerVideoData, and MUXSDKCustomerViewData depending on what changedMUXSDKDataEventMUXSDKDataEvent via [MUXSDKCore dispatchEvent: forPlayer:]For example, when the resolution of the video being played back changes (such as in adaptive streaming), the following should be done:
"code": "// Prepare the data update\nMUXSDKVideoData *videoData = [[MUXSDKVideoData alloc] init];\n[videoData setVideoSourceWidth:[NSNumber numberWithInt:width]];\n[videoData setVideoSourceHeight:[NSNumber numberWithInt:height]];\n// put it within a MUXSDKDataEvent\nMUXSDKDataEvent *dataEvent = [[MUXSDKDataEvent alloc] init];\n[dataEvent setVideoData:videoData];\n// Emit the event\n[MUXSDKCore dispatchEvent:dataEvent forPlayer:_playerName];",
"language": "objectivec"The Mux Playback Events should be emitted as the events are defined in the referenced document. With regards to naming, the names should align with those in the document, with the following changes: MUXSDK is appended in front of the name, the name itself should be PascalCased, and Event is appended at the end. For instance, for playerready, the corresponding event is MUXSDKPlayerReadyEvent, as defined in MUXSDKPlayerReadyEvent.h.
With each playback event that is emitted, the following fields within MUXSDKPlayerData should be included with the latest values:
playerMuxPluginName - The name of the integration being built, as a stringplayerMuxPluginVersion - The version of the integration being built, as a stringplayerSoftwareName - The name of the player software (e.g. AVPlayer, AVPlayerLayer, etc)playerSoftwareLanguageCode - The language code (e.g. en-US) of the player UI localizationplayerWidth - The width of the player, in logical pixelsplayerHeight - The height of the player, in logical pixelsplayerIsFullscreen - Boolean of whether the player is currently displayed in full screen or notplayerIsPaused- Boolean of whether the player is currently paused (i.e. not playing or trying to play)playerPlayheadTime - The current playhead time of the player, in millisecondsplayerErrorCode - Error code for the current fatal playback error. Omit this if the player has not encountered an error for this view.playerErrorMessage - Error message for the current fatal playback error. Omit this if the player has not encountered an error for this view.playerErrorContext - Error instance-specific information such as a stack trace or segment number. Omit this if the player has not encountered an error for this view.For instance, when emitting the MUXSDKPlayerReady event, it should look like the following:
// Get the player data
MUXSDKPlayerData *playerData = [[MUXSDKPlayerData alloc] init];
// Set the player data information
[playerData setPlayerMuxPluginName:@"Sample Custom Player"];
// ... repeat the above for all values within `MUXSDKPlayerData`
// Emit the event
MUXSDKPlayerReadyEvent *event = [[MUXSDKPlayerReadyEvent alloc] init];
[event setPlayerData:playerData];
[MUXSDKCore dispatchEvent:event forPlayer:_playerName];In addition to the above data fields, for ad and network events there are additional data fields that should be sent. These are documented alongside the events described in Mux Playback Events, and follow similar naming conventions.
In particular:
MUXSDKRequestBandwidthEvents, with the addition of MUXSDKBandwidthMetricData set on the event via [MUXSDKRequestBandwidthEvent setBandwidthMetricData:].renditionLists property of MUXSDKBandwidthMetricData track a stream's renditions with their resolution, framerate, bitrate, and RFC CODECS tag (ref).dispatchAdEvent, and details can be seen within Mux's IMA integration for AVPlayerLastly, for the MUXSDKRenditionChangeEvent, you should make sure to dispatch a MUXSDKDataEvent with the latest updated MUXSDKVideoData immediately before dispatching the MUXSDKRenditionChangeEvent.
There are multiple steps in setting up and tracking a view correctly. A very simple sequence of events to track a basic playback would look like the following steps:
MUXSDKViewInitEvent with the current state of the player and videoMUXSDKDataEvent with the updated MUXSDKCustomerVideoData and MUXSDKCustomerPlayerData for the current video viewMUXSDKPlayerReadyEvent, MUXSDKPlayEvent, MUXSDKPlayingEvent, MUXSDKTimeUpdateEvent, etc), each time with the updated current state of the playerNote: For each Playback Event and MUXSDKViewInitEvent that is dispatched, the current state of the player and video data (MUXSDKPlayerData and MUXSDKVideoData should be attached to the event prior to dispatching the event.
// First, emit the global data event setting up the information about
// the player. This will likely only be called once within your application
// and does not need to be called for each player that is tracked.
MUXSDKDataEvent *dataEvent = [[MUXSDKDataEvent alloc] init];
[dataEvent setEnvironmentData:environmentData];
[dataEvent setViewerData:viewerData];
[MUXSDKCore dispatchGlobalDataEvent:_dataEvent];
// Prepare the view before you emit any other playback events
MUXSDKViewInitEvent *event = [[MUXSDKViewInitEvent alloc] init];
[event setPlayerData:playerData];
[MUXSDKCore dispatchEvent:event forPlayer:playerName];
// Dispatch data about the view itself.
// Note: customerPlayerData must include your environment key.
MUXSDKDataEvent *dataEvent = [[MUXSDKDataEvent alloc] init];
[dataEvent setCustomerPlayerData:customerPlayerData];
[dataEvent setCustomerVideoData:customerVideoData];
[MUXSDKCore dispatchEvent:dataEvent forPlayer:_playerName];
// Emit playback events
MUXSDKPlayerReadyEvent *event = [[MUXSDKPlayerReadyEvent alloc] init];
[event setPlayerData:playerData];
[MUXSDKCore dispatchEvent:event forPlayer:_playerName];
// When the player begins to attempt playback
MUXSDKPlayEvent *event = [[MUXSDKPlayEvent alloc] init];
[event setPlayerData:playerData];
[MUXSDKCore dispatchEvent:event forPlayer:_playerName];
// When the player actually displays first moving frame
MUXSDKPlayingEvent *event = [[MUXSDKPlayingEvent alloc] init];
[event setPlayerData:playerData];
[MUXSDKCore dispatchEvent:event forPlayer:_playerName];
// ... and repeat for all of the playback eventsMost of the events are signaled as listed above. However, there are a few cases of events that require additional work.
In order to change the video within a player, there are a few events that need to be fired in sequence. You can see the implementation of this within the muxinc/mux-stats-sdk-avplayer code. You should do the following:
viewend eventviewinit eventMUXSDKDataEvent with the new video's MUXSDKCustomerVideoData, with the videoChange property set to YES.[player dispatchViewEnd];
[player dispatchViewInit];
MUXSDKDataEvent *dataEvent = [MUXSDKDataEvent new];
[dataEvent setCustomerVideoData:videoData];
dataEvent.videoChange = YES;
[MUXSDKCore dispatchEvent:dataEvent forPlayer:name];When you are tearing down the player and want to stop monitoring it, make sure to remove any listeners that you have on the player for sending events to MUXSDKCore. After this, make sure to call [MUXSDKCore destroyPlayer: _name]; for the name of your player, so that the core library can clean up any monitoring and end the view session.
MUXSDKEndedEvent in the public headersAPPLICATION_EXTENSION_API_ONLY = YESplayer_live_edge_program_timeplayer_program_timeMUXSDKCustomerData modelUIKitmux_embed fieldview_playing_timeThis 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 3.0:
@import MuxCoreTv;TVOS after 3.0:
@import MuxCore;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 3.0:
@import MuxCoreTv;TVOS after 3.0:
@import MuxCore;player_remote_played and view_session_id.MUXSDKCustomerPlayerData and MUXSDKCustomerVideoData objects, there is now support for MUXSDKCustomerViewData. The view_session_id may be set onMUXSDKCustomerViewData.lipo errors out, because it can't have the same architecture for two different platforms (it already has arm_64 for the device platform). This is a temporary work around until a later major version release which will use the new XCFramework hotnesspodspec and project build settings for XCode 12 compatibilityrenditionchange eventsorientationchange eventsresponseStart, fallback to requestStart in order to calculate throughputvideoSourceUrl on MUXSDKCustomerVideoData. This allows a user to set the videoSourceUrl (along with their other VideoData, in which case any videoSourceUrl that is inferred from the player will be ignored.player_instance_id a full uuid-style stringplayer_instance_id