This is a guide for building a custom integration with Mux Data in Java. Build a custom integration if Mux does not already have an SDK for your player.
Mux has a pre-built integration with Google's ExoPlayer v2 and Android Media Player for Android applications.
If the player that you use does not expose the ExoPlayer instance directly, swaps between multiple instances during playback, or uses some other playback mechanism completely (for instance, outside of Android), 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 Google's ExoPlayer is open source and can be found in the Mux-Stats-SDK-ExoPlayer GitHub repository. This project is a good example of how to use the Java core library in building a player integration.
The Mux Core Java library is made available as a JAR file which can be installed using the following methods:
Add the Mux Maven repository to your Gradle file:
repositories {
maven {
url "https://muxinc.jfrog.io/artifactory/default-maven-release-local"
}
}Next, add a dependency on Mux Core (current version is 7.0.11):
api 'com.mux:stats.muxcore:7.0.11'Add the Mux repository to your Maven pom.xml:
<repository>
<id>mux</id>
<name>Mux Maven Repository</name>
<url>https://muxinc.jfrog.io/artifactory/default-maven-release-local</url>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>Next, add a dependency on Mux Core (current version is 7.0.11):
<dependency>
<groupId>com.mux</groupId>
<artifactId>stats.muxcore</artifactId>
<version>7.0.11</version>
</dependency>The core Java SDK is initialized by implementing certain interfaces and providing these back to the SDK. In general, the structure used within MuxBaseExoPlayer should be followed, where you create a class that extends EventBus and implements IPlayerListener, and then follows the following general steps.
import com.mux.stats.sdk.core.events.EventBus;
import com.mux.stats.sdk.core.model.CustomerPlayerData;
import com.mux.stats.sdk.core.model.CustomerVideoData;
import com.mux.stats.sdk.core.model.CustomerViewData;
import com.mux.stats.sdk.muxstats.IPlayerListener;
public class PlayerListener extends EventBus implements IPlayerListener {
MuxStats muxStats;
PlayerListener(Context ctx, ExoPlayer player, String playerName, CustomerPlayerData customerPlayerData, CustomerVideoData customerVideoData, CustomerViewData customerViewData) {
super();
this.player = new WeakReference<>(player);
state = PlayerState.INIT;
MuxStats.setHostDevice(new MuxDevice(ctx));
MuxStats.setHostNetworkApi(new MuxNetworkRequests());
muxStats = new MuxStats(this, playerName, customerPlayerData, customerVideoData, customerViewData);
addListener(muxStats);
}
}The above does the following:
EventBus superclassIDeviceINetworkRequestMuxStats, passing itself (a class that implements IPlayerListener) along with metadatathis's events (via EventBus)The IDevice, INetworkRequest, and IPlayerListener interfaces are described in the next section, as they provide the majority of the functionality aside from the actual emitting of events.
The core Java SDK relies heavily on callbacks, via implemented interfaces. These interfaces provide necessary metadata as well as core functionality that may be different depending on your Java environment.
IDeviceThe IDevice interface provides device-specific information to the core library, which is used as metadata attached to each view.
package com.mux.stats.sdk.muxstats;
public interface IDevice {
// Return the hardware name (e.g. Build.HARDWARE)
String getHardwareArchitecture();
// Return the OS (e.g. Android)
String getOSFamily();
// Return the OS version
String getOSVersion();
// Return the device manufacturer (e.g. Build.MANUFACTURER)
String getManufacturer();
// Return the model name (e.g. Build.MODEL)
String getModelName();
// Return the player version
String getPlayerVersion();
// Return a unique identifier for this device
String getDeviceId();
// Return the name of the running application
String getAppName();
// Return the version of the running application
String getAppVersion();
// Return the name of the plugin (e.g. exoplayer-mux)
String getPluginName();
// Return the version of the plugin
String getPluginVersion();
// Return the player software (e.g. 'ExoPlayer')
String getPlayerSoftware();
// Return the network connection type (e.g. 'wifi', 'cellular', 'ethernet')
String getNetworkConnectionType();
// Return milliseconds since epoch, ideally from a
// monotonically increasing clock. For instance, in
// ExoPlayer and Android, we suggest
// android.os.SystemClock.elapsedRealtime
long getElapsedRealtime();
// Return provide a mechanism to log an output, for instance to logcat
void outputLog(String tag, String msg);
}There must be an instance of a class that implements the IDevice interface, and this should be provided to MuxStats.setHostDevice prior to instantiating an instance of MuxStats.
You can see the implementation of IDevice within Mux's ExoPlayer integration within MuxBaseExoPlayer.java.
The INetworkRequest interface defines the methods that the Mux core SDK requires in order to make the necessary network requests.
package com.mux.stats.sdk.muxstats;
/**
* <b>MuxStats</b> will use this interface implementation to send events and metrics to the backend,
* overlaying player SDK need to implement this interface and set it to the <b>MuxStats</b> via
* {@link MuxStats#setHostNetworkApi(INetworkRequest)} method.
* Always set this interface before instantiating the <b>MuxStats</b> instance.
*/
public interface INetworkRequest {
/**
* This interface is used to get from the network implementation that
* {@link #postWithCompletion(String, String, String, Hashtable, IMuxNetworkRequestsCompletion)}
* have succeed or not.
*
* @deprecated please prefer {@link IMuxNetworkRequestsCompletion2}
*/
@Deprecated
interface IMuxNetworkRequestsCompletion {
/**
* Called by the implementation object when
* {@link #postWithCompletion(String, String, String, Hashtable,
* IMuxNetworkRequestsCompletion)} is called.
*
* @param result if post was completed successfully or not.
*/
void onComplete(boolean result);
}
interface IMuxNetworkRequestsCompletion2 {
void onComplete(boolean result, Map<String, List<String>> headers);
}
/**
* Perform a HTTP GET request.
*
* @param url url to send get request to.
*/
void get(URL url);
/**
* Perform HTTP POST request.
*
* @param url url to send post request to.
* @param body post request body.
* @param headers post request headers.
*/
void post(URL url, JSONObject body, Hashtable<String, String> headers);
/**
* Perform network request with confirmation callback, type of request is left to the
* implementation.
*
* @param domain domain to send beacons to.
* @param envKey backend key used to authenticate with backend.
* @param body request body.
* @param headers request headers.
* @param callback callback triggered after the request signalling the request status.
*/
void postWithCompletion(String domain, String envKey, String body,
Hashtable<String, String> headers, IMuxNetworkRequestsCompletion callback);
/**
* Perform a network request with the given completion handler. If implemented, the completion
* handler will also report the response headers for the call
*
* This method has a default implementation, which does not report response headers, and delegates
* to the other postWithCompletion
*
* @param domain domain to send beacons to.
* @param envKey backend key used to authenticate with backend.
* @param body request body.
* @param headers request headers.
* @param callback callback triggered after the request signalling the request status.
*/
default void postWithCompletion(String domain, String envKey, String body,
Hashtable<String, String> headers, IMuxNetworkRequestsCompletion2 callback) {
postWithCompletion(domain, envKey, body, headers, result -> callback.onComplete(result, null));
}
}There must be an instance of a class that implements the INetworkRequest interface, and this should be provided to MuxStats.setHostNetworkApi prior to instantiating an instance of MuxStats.
You can see the implementation of INetworkRequest within Mux's ExoPlayer integration within MuxNetworkRequests.java.
The IPlayerListener interface defines the callbacks that MuxStats will utilize to retrieve player state information.
package com.mux.stats.sdk.muxstats;
public interface IPlayerListener {
// Return the current playhead position in milliseconds
// The playhead position must be updated at least every 250 milliseconds,
// but can be updated more often than this.
long getCurrentPosition();
// Return the MIME type of the content being played (e.g. "video/mp4"
// or "application/x-mpegUrl" etc)
String getMimeType();
// Return the width of the source, in pixels
Integer getSourceWidth();
// Return the height of the source, in pixels
Integer getSourceHeight();
// Return the current advertised bitrate, in bits per second
Integer getSourceAdvertisedBitrate();
// Return the current advertised framerate
Float getSourceAdvertisedFramerate();
// Return the current codec string
String getSourceCodec();
// Return the source duration, in milliseconds
Long getSourceDuration();
// Return whether the player is currently paused (i.e. not actively
// trying to play the content). This should return true if the player
// is not actively playing, rebuffering, or starting up.
boolean isPaused();
// Return whether the player is currently buffering content (e.g. not
// playing back because the buffer is not full enough).
boolean isBuffering();
// Return the width of the player, in logical pixels
int getPlayerViewWidth();
// Return the height of the player, in logical pixels
int getPlayerViewHeight();
// Return the current playback position as based off of the PDT tags
Long getPlayerProgramTime();
// Return the time of the furthest position in the manifest as based
// off of the PDT tags in the stream
Long getPlayerManifestNewestTime();
// Return the configured holdback value for a live stream (ms)
Long getVideoHoldback();
// Return the configured holdback value for parts in a low latency live
// stream (ms)
Long getVideoPartHoldback();
// Return the configured target duration for parts in a low latency
// live stream (ms)
Long getVideoPartTargetDuration();
// Return the configured target duration for segments in a live
// stream (ms)
Long getVideoTargetDuration();
}The class that implements IPlayerListener serves as the interface between MuxStats and the actual player API, and is provided when creating an instance of MuxStats.
You can see the implementation of IPlayerListener within Mux's ExoPlayer integration within MuxBaseExoPlayer.java. This superclass is used to handle the base API interaction, and is subclassed by each individual MuxStatsExoPlayer.java to handle the varying APIs that ExoPlayer exposes with each of its minor versions (such as this one for r2.11.1).
For the Java core SDK, the Mux Playback Events are emitted via the dispatch method that is inherited from the EventBus class. In order to emit a given event, you must first instantiate an instance of the event class that you are trying to emit.
import com.mux.stats.sdk.core.events.EventBus;
import com.mux.stats.sdk.core.model.CustomerPlayerData;
import com.mux.stats.sdk.core.model.CustomerVideoData;
import com.mux.stats.sdk.muxstats.IPlayerListener;
import com.mux.stats.sdk.events.playback.PlayEvent;
public class PlayerListener extends EventBus implements IPlayerListener {
MuxStats muxStats;
PlayerListener(Context ctx, ExoPlayer player, String playerName, CustomerPlayerData customerPlayerData, CustomerVideoData customerVideoData) {
super();
this.player = new WeakReference<>(player);
state = PlayerState.INIT;
MuxStats.setHostDevice(new MuxDevice(ctx));
MuxStats.setHostNetworkApi(new MuxNetworkRequests());
muxStats = new MuxStats(this, playerName, customerPlayerData, customerVideoData);
addListener(muxStats);
}
// When the player begins trying to play back the video
public void onPlay() {
dispatch(new PlayEvent(null));
}
}While not necessary, each playback event can take an optional parameter of PlayerData, if certain information of the player has changed. This object has the following properties:
| Property | Description |
|---|---|
playerMuxPluginName | The name of the integration being built, as a string |
playerMuxPluginVersion | The version of the integration being built, as a string |
playerSoftwareName | The name of the player software (e.g. Exoplayer, etc) |
playerSoftwareLanguageCode | The language code (e.g. en-US) of the player UI localization |
playerWidth | The width of the player, in logical pixels |
playerHeight | The height of the player, in logical pixels |
playerIsFullscreen | Boolean of whether the player is currently displayed in full screen or not |
playerIsPaused | 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 milliseconds |
Most of these properties are pulled automatically via the IPlayerListener interface, so there is no need to provide these values. You will need to emit all required Playback Events in order to make a working integration.
Prior to v5.0.0, the SeekingEvent was not necessary. As of v5.0.0, this is now a required event to be emitted by the player integration.
Prior to v6.0.0, the RebufferStartEvent and RebufferEndEvent were not necessary. As of v6.0.0 and newer, these events must be emitted by the player integration.
There is an additional type of event that is permissible, the DataEvent. This event is emitted the same way (via EventBus.dispatch), but should be used when some metadata has changed outside of a playback event. Examples of this are when you may have any of the metadata within CustomerVideoData, CustomerPlayerData, EnvironmentData, VideoData, or ViewerData changes. This event likely will not be needed, but it is provided in the case that it might be useful. Mux does not use this at all within the ExoPlayer integration.
Values for Experiments can be tracked via the tags of an HLS stream's main playlist. The values in the SessionTags will override the values provided via objects like CustomerPlayerData or CustomerVideoData. When your player has loaded the experiment values (such as through and HLS stream's X-SESSION-DATA tags), you may pass them to MuxStats::setSessionData(List<SessionTag>)
For the bandwidth throughput and latency related events, the structure is slightly different. Rather than having a specific class for each event, there is one high level network event, the RequestBandwidthEvent. This event exposes a method, setBandwidthMetricData(BandwidthMetricData), which is used to provide all information about the event. In particular, the BandwidthMetricData class exposes a property (via a getter/setter) named requestEventType, which is a string that will match the event names as defined in Playback Events - Bandwidth Throughput Events.
The implementation of these events for the Mux ExoPlayer integration can be found here in this file, from the linked line until the end of the file. This can serve as a good example of how to implement these events, though they are not necessary for a functioning integration.
In the case that your player supports advertising, you should instrument the ad events that are defined in Mux Playback Events - Ad Events. Ad events are emitted just as normal events would be, but the ad events should have the ad metadata included via a ViewData instance that is attached to each event via setViewData. For instance, to emit an AdPlayEvent, you should do the following:
AdData adData = new AdData();
adData.setAdCreativeId(creativeId);
adData.setAdId(adId);
AdPlayEvent adPlayEvent = new AdPlayEvent(null);
adPlayEvent.setAdData(adData);
dispatch(adPlayEvent);The implementation of ad events within Mux's ExoPlayer integration, on top of Google's IMA SDK, can be found within AdsImaSDKListener.java, and can serve as a good example.
Rather than requiring an event to be emitted for changing the video, MuxStats exposes two helper methods: videoChange and programChange. These methods encapsulate the logic necessary to end a view and start a new one, and both take an instance of CustomerVideoData containing the metadata about the new video being played.
You should call one of these methods when a new video is being loaded into an already-tracked player.
There is one critical difference between videoChange and programChange - programChange is intended to be used in the case that the underlying video changes within the same stream. An example of this would be within live linear playback, where the underlying program changes without the player having to reload a new stream.
In the case that the player is loading a new HLS/Dash/MP4 video, you should use videoChange.
CustomerVideoData customerVideoData = new CustomerVideoData(null);
customerVideoData.setVideoTitle("New Video Title");
// Add other video metadata here
muxStats.videoChange(customerVideoData);Your custom integration is able to dispatch error events associated with the current view. These errors can get alerted on and are also visually indicated on the event timeline shown for that view.
When dispatching errors your custom integration can provide additional error metadata with Error Categorization. This section will cover several examples of dispatching errors using the Java SDK. You can find more general information on Error Categorization here.
This example illustates how to construct and send different categories of error events.
Any error categories specified by your custom integration can be configured to be overridden based on the player error code. See the Error Categorization guide for more details.
import com.mux.stats.sdk.core.events.EventBus;
import com.mux.stats.sdk.core.model.CustomerPlayerData;
import com.mux.stats.sdk.core.model.CustomerVideoData;
import com.mux.stats.sdk.muxstats.IPlayerListener;
import com.mux.stats.sdk.events.playback.PlayEvent;
import com.mux.stats.sdk.events.playback.ErrorEvent;
public class PlayerListener extends EventBus implements IPlayerListener {
MuxStats muxStats;
PlayerListener(Context ctx, ExoPlayer player, String playerName, CustomerPlayerData customerPlayerData, CustomerVideoData customerVideoData) {
super();
this.player = new WeakReference<>(player);
state = PlayerState.INIT;
MuxStats.setHostDevice(new MuxDevice(ctx));
MuxStats.setHostNetworkApi(new MuxNetworkRequests());
muxStats = new MuxStats(this, playerName, customerPlayerData, customerVideoData);
addListener(muxStats);
}
// When the player begins trying to play back the video
public void onPlay() {
dispatch(new PlayEvent(null));
}
// Call from onPlayerError() with parameters appropriate to your integration. Dispatches an error event that Mux will categorize as a fatal playback error by default
public void onPlaybackError(String errorCode, String errorMessage, String errorContext) {
PlayerData playerData = new PlayerData();
playerData.setErrorCode(errorCode);
playerData.setErrorMessage(errorMessage);
ErrorEvent errorEvent = new ErrorEvent(playerData, errorContext);
dispatch(errorEvent);
}
// Call from onPlayerError() with parameters appropriate to your integration. Dispatches an error event that Mux will categorize as a warning by default
public void onPlaybackWarning(String errorCode, String errorMessage, String errorContext) {
PlayerData playerData = new PlayerData();
playerData.setErrorCode(errorCode);
playerData.setErrorMessage(errorMessage);
ErrorEvent errorEvent = new ErrorEvent(playerData, errorContext, ErrorSeverity.ErrorSeverityWarning);
dispatch(errorEvent);
}
// Call from onPlayerError() with parameters appropriate to your integration. Dispatches an error event that Mux will categorize as a business exception by default
public void onBusinessException(String errorCode, String errorMessage, String errorContext) {
PlayerData playerData = new PlayerData();
playerData.setErrorCode(errorCode);
playerData.setErrorMessage(errorMessage);
// This method does not set an explicit error severity, see below for an example method that does.
ErrorEvent errorEvent = new ErrorEvent(playerData, errorContext);
errorEvent.setIsBusinessException(true);
dispatch(errorEvent);
}
// Call from onPlayerError() with parameters appropriate to your integration. Dispatches an error event that Mux will categorize as a business exception by default
public void onBusinessException(String errorCode, String errorMessage, String errorContext, ErrorSeverity severity) {
PlayerData playerData = new PlayerData();
playerData.setErrorCode(errorCode);
playerData.setErrorMessage(errorMessage);
ErrorEvent errorEvent = new ErrorEvent(playerData, errorContext, severity, true);
dispatch(errorEvent);
}
}There is no destroy event for the core Java SDK. Instead, the release method is exposed on MuxStats that cleans up all tracking and releases all references held within the core library. This method should be called when you release your player instance, and after calling release, the instance of muxStats will be unusable.
Fixes:
Fixes:
Fixes:
Fixes:
Updates:
enable and disable methods for pausing and resuming data collectionImprovements:
Fixes:
Improvements
Fixes:
ViewEnd event.Fixes:
Fixes:
Fixes:
Updates:
update() method for CustomerDataNew:
IPlayerListenerNew:
Improvements:
Improvements:
drmType to CustomerViewData so customers can override itx-litix-shard-id header populated with device IDNew:
CustomOptions for controlling beacon update interval. Very few cases require longBeaconDispatch.Fixes:
Improvements:
Improvements:
New:
Add AdEvent with AdData to represent data about individual, non-preroll ad events during play