Monitor ExoPlayer

This documents integration instructions for Google's ExoPlayer library, version 2.x. ExoPlayer versions before 2.0 are not supported. As of version 120.0 of Mux's integration with ExoPlayer, only versions of ExoPlayer greater than or equal to 2.9.x are supported.

The Mux integration with ExoPlayer is built on top of Mux's core Java SDK, and the full code can be seen here: muxinc/mux-stats-sdk-exoplayer.

1Install the Mux Data SDK

Include the Mux SDK for your project by downloading the appropriate AAR for your version of ExoPlayer from our GitHub repo and including it in your project. It is important to use the version of the AAR that matches the version of ExoPlayer that you are using, as ExoPlayer introduces breaking changes often.

We recommend using Android Studio's new module tool which can be accessed via File > New > New Module.... Select the Import .JAR/.AAR Package and then select the mux.aar that you downloaded from our GitHub repo. This should correctly configure the IDE as well as modify your build configuration (Gradle/Maven).

For an example integration, you can see the demo application within muxinc/mux-stats-sdk-exoplayer which integrates Mux into the ExoPlayer demo application.

2Initialize the monitor with your Exoplayer instance

Get your ENV_KEY from the Mux environments dashboard.

First, create the CustomerPlayerData and CustomerVideoData objects as appropriate for your current playback, and be sure to set your ENV_KEY.

copy
import com.mux.stats.core.model.CustomerPlayerData;
import com.mux.stats.core.model.CustomerVideoData;
import com.mux.stats.core.model.CustomerViewData;
// ...
CustomerPlayerData customerPlayerData = new CustomerPlayerData();
customerPlayerData.setEnvironmentKey("ENV_KEY");
CustomerVideoData customerVideoData = new CustomerVideoData();
customerVideoData.setVideoTitle("The most epic video ever");
CustomerViewData customerViewData = new CustomerViewData();
customerViewData.setViewSessionId("A26C4C2F-3C8A-46FB-885A-8D973F99A998");  

Next, create the MuxStatsExoPlayer object by passing your Android Context (typically your Activity), the ExoPlayer instance, a player name, and the customer data objects. Note: Mux prefers that you pass an instance of SimpleExoPlayer, though you can pass an instance of base ExoPlayer; in the latter case, however, some metrics and errors may not be available, such as upscaling metrics.

copy
import com.mux.stats.sdk.muxstats.MuxStatsExoPlayer;
...
// Make sure to monitor the player before calling `prepare` on the ExoPlayer instance
muxStatsExoPlayer = new MuxStatsExoPlayer(ctx, player, "demo-player", customerPlayerData, customerVideoData, customerViewData);  

In order to correctly monitor if the player is full-screen, provide the screen size to the MuxStatsExoPlayer instance.

copy
Point size = new Point();
getWindowManager().getDefaultDisplay().getSize(size);
muxStatsExoPlayer.setScreenSize(size.x, size.y);  

In order to determine a number of viewer context values as well as track the size of the video player, set the player view.

copy
muxStatsExoPlayer.setPlayerView(simpleExoPlayerView.getVideoSurfaceView());  

Depending on the version of ExoPlayer you are using, you may need to attach some listeners to the player and ChunkSource/MediaSource objects.

copy
// MuxStatsExoPlayer automatically registers itself as an
// `AnalyticsListener`, and there is no additional calls
// you need to make for this step.

// In order to track throughput metrics in your application,
// you will need to tell Mux what format you are using for
// adaptive playback, via `muxStatsExoPlayer.setStreamType`

// Example in the ExoPlayer demo application:
@SuppressWarnings("unchecked")
private MediaSource buildMediaSource(Uri uri, @Nullable String overrideExtension) {
  @ContentType int type = Util.inferContentType(uri, overrideExtension);
  // Set the type appropriately.
  muxStats.setStreamType(type);
  switch (type) {
    case C.TYPE_DASH:
      return new DashMediaSource.Factory(...)
        .setManifestParser(...)
        .createMediaSource(uri);
    case C.TYPE_SS:
      return new SsMediaSource.Factory(...)
        .setManifestParser(...)
        .createMediaSource(uri);
    case C.TYPE_HLS:
      return new HlsMediaSource.Factory(...)
        .setPlaylistParser(...)
        .createMediaSource(uri);
    case C.TYPE_OTHER:
      return new ExtractorMediaSource.Factory(...)
        .createMediaSource(uri);
    default: {
      throw new IllegalStateException("Unsupported type: " + type);
    }
  }
}  

Finally, when you are destroying the player, call the MuxStatsExoPlayer.release() function.

copy
muxStatsExoPlayer.release()  

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.

3Add Metadata

In the Java SDK, options are provided via the CustomerPlayerData, CustomerVideoData, and CustomerViewData objects.

All metadata details except for envKey are optional, however you'll be able to compare and see more interesting results as you include more details. This gives you more metrics and metadata about video streaming, and allows you to search and filter on important fields like the player version, CDN, and video title.

There is one caveat with ExoPlayer; ExoPlayer does not provide an API to retrieve the current source URL from the player. Due to this, CustomerVideoData has a method allowing you to set via CustomerVideoData.setVideoSourceUrl(String url). Setting this value will allow you to see the source URL as well as the dimension Source Hostname within the dashboard.

For more information, see the Metadata Guide.

4Advanced

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 secondly 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 muxStatsExoPlayer.videoChange(CustomerVideoData) which will remove all previous video data and reset all metrics for the video view. See Metadata for the list of video details you can provide. You can include any metadata when changing the video but you should only need to update the values that start with video.

It's best to change the video info immediately after telling the player which new source to 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 muxStatsExoPlayer.programChange(CustomerVideoData). This will remove all previous video data and reset all metrics for the video view, creating a new video view. See Metadata for the list of video details you can provide. You can include any metadata when changing the video but you should only need to update the values that start with video.

Error tracking

By default, Mux's integration with ExoPlayer automatically tracks fatal errors as thrown by ExoPlayer. If a fatal error happens outside the context of ExoPlayer and you want to track it with Mux, you can call muxStatsExoPlayer.error like this:

copy
// Error code: integer value for the generic type of error that
// occurred.
// Error message: String providing more information on the error
// that occurred.
// For an example, the HTML5 video element uses the
// following: https://developer.mozilla.org/en-US/docs/Web/API/MediaError
// for codes and messages. Feel free to use your own codes and messages
int errorCode = 1;
String errorMessage = "A fatal error was encountered during playback";
MuxErrorException error = new MuxErrorException(errorCode, errorMessage);
muxStatsExoPlayer.error(error);  

Note that muxStatsExoPlayer.error(MuxErrorException e) can be used with or without automatic error tracking. If your application has retry logic that attempts to recover from ExoPlayer errors then you may want to disable automatic error tracking like this:

copy
muxStatsExoPlayer.setAutomaticErrorTracking(false)  

Usage with Google Interactive Media Ads (IMA)

If you are using Google's IMA SDK to play back ads within your Android application, you can configure Mux to monitor the ad performance by passing your instance of AdsLoader to muxStatsExoPlayer.monitorImaAdsLoader(adsLoader).

r2.12.x

copy
// For example, within the r2.12.x demo application
// PlayerActivity.getAdsLoader
adsLoader = new ImaAdsLoader.Builder(/* context= */ this)
    /*
     * This replaces `monitorImaAdsLoader` method because in r2.12.x ImaAdsLoader
     * will create google.v3.AdsLoader on adRequest, which means that monitorImaAdsLoader
     * Will always receive null pointer and will be unable to recieve add events.
     */
    .setAdErrorListener(muxStats.getAdErrorEventListener())
    .setAdEventListener(muxStats.getAdEventListener())
    .build();  

pre-r2.12.x

copy
// Within setting up the AdsMediaSource
sdkFactory = ImaSdkFactory.getInstance();
adsLoader = sdkFactory.createAdsLoader(this);
muxStatsExoPlayer.monitorImaAdsLoader(adsLoader);  

As of version 1.3.0 and later, the Mux SDK for ExoPlayer supports firing an event when the playback orientation changes. You can trigger this by calling muxStatsExoPlayer.orientationChange(MuxSDKViewOrientation orientation), passing either MuxSDKViewOrientation.LANDSCAPE or MuxSDKViewOrientation.PORTRAIT depending on the current orientation of the player.

Sentry

In order to improve our SDKs, Mux utilizes Sentry to track exceptions that our SDK may throw. No personal data is captured by Mux's SDK in these error reports, but if you want to disable this functionality, you can. There are two constructors for MuxStatsExoPlayer, one of which exposes a final boolean parameter that allows you to disable any reporting of crashes to Sentry.

copy
// To disable reporting to Sentry, pass `false` as the last parameter to the constructor
muxStatsExoPlayer = new MuxStatsExoPlayer(ctx, player, "demo-player", customerPlayerData, customerVideoData, false);  

Release notes

Current release

v2.4.8

• Reset internal state when calling videochange, fixing an issue where rebuffering may be reported incorrectly after calling videochange

Previous Releases

v2.4.7

• Fix an issue where metrics weren't tracked correctly sometimes when playback starts with a seek event
• Upgrade MuxCore to 6.3.0, which includes:
  • Reset error-tracking state when loading a new video.
• [Internal] Fix automated tests for r2.13.1

v2.4.5

• Add support for ExoPlayer r2.13.x

v2.4.4

• Removed all content from res directory under MuxExoPlayer, ensuring smaller build size
• [Internal] Added test for playback end events and view end event
• [Maintenance] Reformat code with Google Java style
• Upgrade MuxCore to 6.2.0, which includes:
  • Added viewEnd event on player release.

v2.4.3

• Fix an issue where customerViewData was not propagated correctly through all constructors

v2.4.2

• Fix an issue where customerViewData was not propagated correctly through constructors

v2.4.1

• Fix an issue where detection of rebuffering after seeking was not working at times
• Use a random UUID stored in shared preferences for mux_viewer_id
• Fix an issue where view_session_id wasn't sent correctly

v2.4.0

• Fix an issue where additional icons and image files were included
• Fix an issue where the application would crash on Android 11
• Expose additional fatal playback errors

v2.3.1

• Fix an issue where AAR file size was too large due to inadvertent inclusion of a video file

v2.3.0

• Fix an issue where logical resolution was calculated incorrectly
• Report wired instead of ethernet for certain connection types
• [internal] Integrate automated integration tests

v2.2.0

• Upgrade to Android Studio 4.1
• Upgrade to Gradle 6.1.1
• Update dockerfile and build script for new tooling
• Support back to minAPI 16 via multidexing support

v2.1.0

• Support ExoPlayer r2.12.x flavors
• Expose CustomerViewData through ProGuard
• Ensure packages are scoped to com.mux.stats.sdk in ProGuard
• Update version reported by the plugin (v2.0.0 reported v1.5.0 unintentionally, now will report v2.1.0)
• Fix an issue where accessing ad integration could cause a crash
• Bump to MuxCore v6.0.0
• Fix invalid rebuffering reported for audio-only and playback
• Ensure that events are sent in a more timely manner (some events are held after a PauseEvent until the next active event)

v2.0.0

• Bump to v5.0.0 of MuxCore
  • Update ad handling logic to ensure that ad metrics and dimensions are tracked correctly
  • Retry sending failed beacons, rather than letting them drop
  • Fix issue where we were incorrectly calculating scaling metrics when screen or video resolution was negative
  • Fix an issue where watch time is incorrectly increasing after certain events
  • Make sure that time to first frame is not tracked for views that result from programchange
  • Add support for viewer_connection_type, which is a breaking change for IDevice, as it adds another method that must be implemented
  • Add support for view_session_id, which includes an additional CustomerViewData class. This changes the constructor for creating a MuxStats instance
• Drop support for ExoPlayer r2.7.x and r2.8.x
• Implement SeekingEvent directly in MuxStatsExoPlayer
• Fix issue where source type could be null and cause a crash
• Fix an issue where ad events are sent out of order in some cases
• Add connection type detection
• Report logical sizes for player size, rather than physical size
• Fix an issue where time to first frame was incorrectly measured in some cases, such as mid- or post-roll ad playback without a pre-roll
• Add support for CustomerViewData, including setViewSessionId

v1.5.0

• Fix an issue where if you were using muxStatsExoPlayer.setPlayerSize(width, height) those values were not used correctly. Note: If you call this, you must update the player size whenever that changes, as the SDK will no longer pull those values automatically.

v1.4.0

• Move MuxSDKViewOrientation to com.mux.stats.sdk.core.MuxSDKViewOrientation and expose it publicly

v1.3.0

• Add support for RenditionChangeEvent, which is tracked automatically
• Add support for OrientationChangeEvent, which can be triggered by calling muxStatsExoPlayer.orientationChange(MuxSDKViewOrientation orientation). Supported orientations are MuxSDKViewOrientation.LANDSCAPE and MuxSDKViewOrientation.PORTRAIT.
• Fix an issue where fullscreen tracking was not working correctly

v1.2.0

• Add support for ExoPlayer 2.11.x
• Note: there is a known issue right now with ExoPlayer r2.11.x where ads are not tracked correctly. This is under development.

v1.1.0

• Add support for additional debug logging. See muxStatsExoPlayer.enableMuxCoreDebug(Boolean enable, Boolean verbose)
• Add the ability to update customerVideoData and customerPlayerData mid-stream, in cases that certain metadata may not be available at the beginning of playback. See muxStatsExoPlayer.updateCustomerData(CustomerPlayerData customerPlayerData, CustomerVideoData customerVideoData)
• Fix an issue where if MuxStatsExoPlayer is initialized too late, the stream is not tracked correctly
• Fix an issue where Mux Plugin Version is reported incorrectly
• Fix an issue where the EndedEvent is not sent to the backend
• Fix an issue where tracking playback is not correct when playWhenReady is set to false (i.e. non-autoplay playback)
• Fix an issue where events could be sent after playback completes, forcing the view to be active for longer than it actually was
• Utilize more accurate client timestamps for event timing

v1.0.0

• Add support for ExoPlayer 2.9.x
• Add support for ExoPlayer 2.10.x
• Fix issue where ExoPlayer versions 2.9.x and greater would log messages about accessing the player on the wrong thread
• breaking change Removed support for ExoPlayer 2.6.x and older (due to changes in build pipeline and Gradle configurations)
• Support Gradle 3.5.2

v0.5.1

• Clean up demo application
• Allow disabling of Sentry reporting for exceptions.

v0.5.0

• Deprecated method muxStatsExoPlayer.getImaSDKListener in favor of muxStatsExoPlayer.monitorImaAdsLoader(adsLoader). The previous method will still work, but you should migrate to the new method as the deprecated method will be removed with the next major version.
• Fix an issue where Google IMA SDK was a hard requirement unintentionally.

v0.4.5

• Introduce support for tracking ads with Google's IMA SDK.

v0.4.3

• Fix an issue where a NullPointerException may occur during playback of a video while tracking bandwidth metrics.

v0.4.2

• Added API method programChange(CustomerVideoData customerVideoData), for use when inside of a single stream the program changes. For instance, in a 24/7 live stream, you may have metadata indicating program changes which should be tracked as separate views within Mux. Previously, videoChange might have been used for this case, but this would not work correctly, and you would not necessarily have seen the subsequent views show up.
• Fixed a bug where under poor network conditions, an exception raised as a result of a network request could result in not tracking the view correctly subsequently (such as missing rebuffer tracking after this point).

v0.4.1

• Remove the listeners on the ExoPlayer object when release is called.
  • This fixes and issue where the application may crash after calling release if the ExoPlayer instance is removed while the SDK is still listening to it.

v0.4.0

• [feature] Support bandwidth throughput metrics on video segment download for HLS and Dash streaming.
• breaking change The signature for getAdaptiveMediaSourceEventListener and getExtractorMediaSourceEventListener has been changed. These methods are used to enable throughput metrics tracking for ExoPlayer versions before r2.8.0, and now require that the streaming protocol type is passed as the first parameter. The type is the same as is returned from this ExoPlayer API call.

v0.3.0

• breaking change The signature for the MuxStatsExoPlayer constructor has changed, and now requires an additional parameter (the first) to be and Android Context reference.
• abstract more core logic into mux-stats-sdk-java
• [build] rename and copy build artifacts

v0.2.2

• add back in previously missing methods to MuxStatsExoPlayer:
  • videoChange
  • setPlayerSize
  • error
  • setAutomaticErrorTracking

v0.2.1

• add support for ExoPlayer r2.7.x
• add support for ExoPlayer r2.8.x
• update to v2.1.0 of mux-stats-sdk-java