# Monitor THEOplayer
This guide walks through integration with the THEOplayer Android SDK to collect video performance metrics with Mux data.
This documents integration instructions for [THEO Technologies' `THEOplayer` library](https://www.theoplayer.com/sdk/android)
The Mux integration with `THEOplayer` is built on top of Mux's core Java SDK, and the full code can be seen here: [muxinc/mux-stats-sdk-theoplayer-android](https://github.com/muxinc/mux-stats-sdk-theoplayer-android).
## Features
The following data can be collected by the Mux Data SDK when you use the \{featureDef.name} SDK, as described
below.
```md
- Engagement metrics
- Quality of Experience Metrics
- Available for deployment from a package manager
- Custom Dimensions
- Average Bitrate metrics and `renditionchange` events
- Ads metrics
```
Notes:
```md
`renditionchange` events are tracked, bitrate metrics are not available
```
## 1. Install the Mux Data SDK
Add the Mux SDK to your project using one of the following approaches:
## Add Gradle dependency on the Mux THEOplayer SDK (preferred)
Add the Mux Maven repository to your Gradle file:
```text
repositories {
maven {
url "https://muxinc.jfrog.io/artifactory/default-maven-release-local"
}
}
```
Next, add a dependency on the Mux Data THEOplayer SDK.
The latest version of our SDK can be found [here](https://github.com/muxinc/mux-stats-sdk-theoplayer-android/releases/latest)
```groovy
implementation 'com.mux.stats.sdk.muxstats:muxstatssdktheoplayer:[CurrentVersion]'
```
## 2. Initialize the monitor with your THEOplayer instance
Get your `ENV_KEY` from the [Mux environments dashboard](https://dashboard.mux.com/environments).
`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.
First, create the `CustomerPlayerData` and `CustomerVideoData` objects as appropriate for your current playback, and be sure to set your `ENV_KEY`.
```java
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.core.model.CustomData;
import com.mux.stats.sdk.core.model.CustomerData;
CustomerPlayerData customerPlayerData = new CustomerPlayerData();
customerPlayerData.setEnvironmentKey("YOUR_ENVIRONMENT_KEY_HERE");
CustomerVideoData customerVideoData = new CustomerVideoData();
customerVideoData.setVideoTitle(intent.getStringExtra("YOUR_VIDEO_TITLE"));
CustomerViewData customerViewData = new CustomerViewData();
customerViewData.setViewSessionId("A26C4C2F-3C8A-46FB-885A-8D973F99A998");
CustomData customData = new CustomData();
customData.setCustomData1("YOUR_CUSTOM_STRING_HERE");
CustomerData customerData = new CustomerData(customerPlayerData, customerVideoData, customerViewData);
customerData.setCustomData(customData);
```
Next, create the `MuxStatsSDKTHEOPlayer` object by passing your Android `Context` (typically your `Activity`), a `THEOplayerView` instance, a player name, and the customer data objects.
```java
import com.mux.stats.sdk.muxstats.MuxStatsSDKTHEOPlayer;
...
// Make sure to monitor the player before calling `prepare` on the THEOplayer instance
muxStatsTHEOplayer = new MuxStatsSDKTHEOPlayer(
this, player, "demo-player", customerData);
```
In order to correctly monitor if the player is full-screen, provide the screen size to the `MuxStatsSDKTHEOPlayer` instance.
```java
Point size = new Point();
getWindowManager().getDefaultDisplay().getSize(size);
muxStatsTHEOPlayer.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.
```java
muxStatsTHEOplayer.setPlayerView(theoPlayerView);
```
Finally, when you are destroying the player, call the `MuxStatsSDKTHEOPlayer.release()` function.
```
muxStatsTHEOplayer.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.
## 3. Add Metadata
In the Java SDK, options are provided via the objects within the `CustomerData` object.
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.
For more information, see the [Metadata Guide](/docs/guides/make-your-data-actionable-with-metadata).
## 4. Advanced
## 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 `muxStatsTHEOplayer.videoChange(CustomerVideoData)` which will remove all previous video data and reset all metrics for the video view. See [Metadata](/docs/guides/make-your-data-actionable-with-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 `muxStatsTHEOplayer.programChange(CustomerVideoData)`. This will remove all previous video data and reset all metrics for the video view, creating a new video view. See [Metadata](/docs/guides/make-your-data-actionable-with-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`.
## Detect when a video is being played full-screen
For most use cases, the SDK is capable of detecting whether or not a video is being played full-screen. Specifically, it can do so in the case where the player view is the same size as the device display (excepting ActionBars and other framework window decoration).
For other uses cases (non-overlaid controls, window decoration via plain `View`s, etc) you may need to tell the SDK when the user switches to full-screen.
```java
@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState)
// If you are using SimplePlayerView, StyledPlayerView, etc
theoPlayerView = findViewById(R.id.my_player_view);
theoPlayerView.getFullscreenManager().addFullscreenChangeListener(new FullscreenChangeListener() {
@Override
public void onEnterFullscreen() {
muxStatsTHEOplayer.presentationChange(MuxSDKViewPresentation.FULLSCREEN);
}
@Override
public void onExitFullscreen() {
muxStatsTHEOPlayer.presentationChange(MuxSDKViewPresentation.PORTRAIT);
}
});
}
```
## Error tracking
By default, Mux's integration with THEOplayer automatically tracks fatal errors as thrown by THEOplayer. If a fatal error happens outside the context of THEOplayer and you want to track it with Mux, you can call `muxStatsTHEOplayer.error` like this:
```java
// 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);
muxStatsTHEOplayer.error(error);
```
Note that `muxStatsTHEOplayer.error(MuxErrorException e)` can be used with or without automatic error tracking. If your application has retry logic that attempts to recover from THEOplayer errors then you may want to disable automatic error tracking like this:
```java
muxStatsTHEOplayer.setAutomaticErrorTracking(false)
```
It is important that you only trigger an error when the playback has to be abandoned or aborted in an unexpected manner, as Mux tracks fatal playback errors only.
### Current release
#### v0.4.2
Updates:
* update: rename library artifact to `muxstatssdktheoplayer`
### Previous releases
#### v0.4.1
Improvements:
* Use "Android TV" osFamily on tv devices
#### v0.4.0
Improvements:
* Update to Core 8.1.0
#### v0.3.0
Improvements:
* Add support for THEOplayer v7
Fixes:
* fix: NullPointerException with getPlayerData() inside MuxStats (#29)
#### v0.2.0
Updates:
* Support THEOPlayer v5 and higher
#### v0.1.3
Fixes:
* Update THEOplayer to 2.92.0 (#18)
#### v0.1.2
Improvements:
* Update to MuxCore 7.0.10
MuxCore Fixes:
* Fix event-handling errors in rare cases
#### v0.1.1
* Initial release