Agama has a long history when it comes to device integrations. For more than a decade we’ve dealt with projects of all sizes/lengths. With every completed milestone, and even more with every obstacle, we’ve been steadily building up the knowledge required to succeed.
What are the plugins?
One of the key parts of understanding the satisfaction of your users is to assess the quality of experience for the services they consume, their engagement, the type of content they like to watch etc. Agama has an excellent track record in providing such insights, in fact, this is the core of what we do.
The implementations of these important KPIs historically included, among others, the following steps: agreement on the desired metrics set, investigation of the available metrics in the target platform, and integration of these metrics towards the Agama core agent. A lot of these steps were unique for every integration. This was partially due to different wishes from different customers, but mostly due to the unique characteristics of each of the target platforms.
With the growing popularity of OTT platforms and the rise of players such as ExoPlayer, Shaka Player or AV Player, the target platforms became increasingly similar between integrations. The shift from “everything is custom” to “common platforms and players” enabled Agama to step outside its domain. We started actively investigating players and platforms, gathering knowledge about them, assessing what could be possible and feasible, and defining an absolute base of metrics that would benefit every customer. These are all implemented in what we call ‘’Player plugins”.
The player plugins follow a few basic principles:
- Agama develops and maintains the plugins
- The plugins provide a good set of metrics, making them usable directly
- No Agama domain knowledge is required for plugin integration – just a few, stable APIs are necessary
- Ability to pass custom metrics to the plugin
Agama develops and maintains player plugins for most of the popular players, such as ExoPlayer, Shaka Player, AVPlayer, and for platforms such as Android, FireOS, iOS, tvOS, Chromecast, Browsers, WebOS, Tizen etc.
While the complete list of metrics differs slightly between plugins, they all share most of the metrics. Some of the features they have in common are:
- QoS and QoE metrics
- Device properties
- Ability to understand asset consumption
- Ability to understand playback errors (for instance, DRM errors)
Integration – keep it simple
Let’s take a closer look at what it takes to integrate Agama into your application. To make it as realistic as possible, let’s use ExoPlayer as the target player and Android as the target platform.
ExoPlayer is currently one of the most popular players for Android. It is extremely customizable and flexible, yet easy to start with. Therefore, it comes as no surprise that it is used by everyone, from hobby enthusiasts to video operators and even YouTube.
Requirements
Let’s start by describing what requirements and dependencies are needed to use the plugin in the first place. Players evolve quickly and so do their capabilities and APIs, and this truly applies to the ExoPlayer. Therefore, the plugin comes in multiple variants associated with various ExoPlayer minor versions. By using a relatively modern version, plugin-player compatibility should not be a problem.
Some metrics implemented by the plugin can be subject to platform permissions. These are not critical to have in any sense, but more on the good-to-have side and will only be included if permissions are granted. Also related to privacy issues, the plugin can be configured to skip certain sensitive metrics. Such information can be, for example, the collection of the device’s longitude and latitude position.
Lastly, the plugin is to be included in the project as any other 3rd party library. And the empclient must be included in the same way as well.
Initialization and configuration steps
Initialize the plugin as early as possible. The plugin’s lifetime shall reflect the application’s lifetime. To initialize it, one needs an Agama configuration string. It is passed on to the Agama core agent – empclient, and includes information such as report heartbeat and the operator id. The configuration string is typically provided by Agama. The application properties such as the applications name and version are needed during initialization.
String agamaConfig =
“emp_service=https://cdm1.company123.se/report;report_interval=60;id_report_interval=240;operator_id=fooSoo;”;
String appName = “Company 123 Play App”;
String appVersion= “2.1”;
// Initialize the plugin
EmpStats.getInstance().init(agamaConfig, Definitions.LogLevel.DEBUG, appName, appVersion, ExoPlayerLibraryInfo.VERSION, getApplicationContext());
Once the plugin instance is created, an account associated with the user should be set as well. This will enable (among other things) to find the customer in the Agama system by its account id.
// Set user account id for user John Doe
EmpStats.getInstance().setUserAccountId(“johdo28”);
Monitoring video
Now the plugin is initialized, configured and sending data to the Agama backend. It’s time to start monitoring the consumed assets. The user has switched to a new channel, started up an asset from the catchup library or simply opened a new episode of their favorite TV series. Opening any new asset shall be signaled to the plugin.
// Load asset & play
String assetUri= “https://demo.agamatech.se/Manifest.m3u8”;
EmpStats.getInstance().sessionOpen(assetUri, Definitions.AssetType.VOD, “Sintel”, player);
URI uri = uri.parse(assetUri);
player.setMediaItem(MediaItem.fromUri(uri), false);
player.prepare();
Analog to signaling the intent to start playing content, one needs to signal playback termination as well. There are two common ways of doing this: the user switched to a new channel or left the playback completely. For the former, one can simply signal to the plugin that a new asset will be opened. It will implicitly close the tracking of the previous one. For the latter, there is a dedicated API to exit.
// Stop the playback activity
public void onStop() {
super.onStop();
EmpStats.getInstance().sessionClose();
}
Video properties
Besides tracking what assets are consumed, the metadata associated with them plays an important role in enriching the data. There are many possible metadata one can associate with an asset, from setting duration and description of the content to tracking which CDN provided an asset and to which service (live, catchup, avod,..) does the asset belong to.
Wrapping up
That’s it! Time to build the application and test it out. During an integration, Agama will provide a test system to use for verification of the data, making the process easy for both the customer and Agama. That system is a natural meeting point for all parties involved.
About Matic Hajdinjak
Matic is a Team Lead at Agama, responsible for developing the Client Device Monitoring range of products. He has 10+ years of experience in software development and is an expert in high-performance client device integrations. With a strong technical background, he loves to work together with his team down to the code level to build new products and solutions.
