Lumen help

CDN Load Balancer plugin for ExoPlayer on Android

CDN Load Balancer can be easily integrated into your Android and Android TV app in just a few simple steps using our ExoPlayer plugin for Android.

The CDN Load Balancer SDK is player agnostic. You can use CDN Load Balancer with any player but you need to embed and connect several classes together to make it work. For most players, Lumen is providing the “glue” classes and how to connect them but that still leaves some integration on your side.

The CDN Load Balancer plugin for ExoPlayer is an Android Archive maven artifact that will automatically pull the right version of the SDK, the right version of ExoPlayer, and that will embed all the required classes. By using CDN Load Balancer via the plugin, you can avoid unwanted integration issues since it will automatically bind them all together, thus reducing the boilerplate and guaranting an up-to-date and compatible integration.

Not into tutorials?

Code Example

Plugin Installation

The easiest way to get the CDN Load Balancer plugin is to add it as a Gradle dependency. We assume you are using Android Studio with the latest tools updates as recommended by Google. If not, write to us at cdnsupport@lumen.com.

Add CDN Load Balancer's maven repository to the project settings in settings.gradle or project build.gradle depending on your repository declaration system.

                            dependencyResolutionManagement {
    repositories {
        maven { url 'https://sdk.streamroot.io/android' }
    }
}
            
        

Plugin versioning

For a given io.streamroot.lumen.delivery.client:orhcestrarot-plugin-exoplayer-2-18:22.09.1.0:

2-18 is the ExoPlayer MAJOR-MINOR => a specific plugin version will automatically take the last PATCH of ExoPlayer (ex: 2.18.1)
22.09.1.0 is the CDN Load Balancer SDK version (22.09.1) appended with a plugin version (.0) To summarize, one plugin version = one specific CDN Load Balancer SDK version + one specific MAJOR.MINOR ExoPlayer version. For that reason, it is recommended that you do not include ExoPlayer as a dependency by yourself but let the Plugin pull the right ExoPlayer version for you. Forcing a different ExoPlayer version may lead to runtime errors such as UnsatisfiedLinkError, ClassNotFoundException, etc.

Add CDN Load Balancer plugin for ExoPlayer dependency. Add in your module build.gradle (it often ends with .app)

                            // It is good practice to lock dependencies version
def dc_version = '22.09.1'
def exo_version = '2-18'
def plugin_patch = 0
implementation "io.streamroot.lumen.delivery.client:orchestrator-plugin-exoplayer-$exo_version:$dc_version.$plugin_patch"
            
        

List of pulled dependencies

ExoPlayer (using exo_version variable, newest patch)
CDN Load Balancer SDK (using dc_version variable)
org.jetbrains.kotlin:kotlin-reflect
org.jetbrains.kotlin:kotlin-stdlib-jdk8
org.jetbrains.kotling:kotlin-android-extensions-runtime
org.jetbrains.kotlinx:kotlinx-coroutines-android
com.getkeepsafe.relinker:relinker
androidx.annotation:annotation

Notes:

CDN Load Balancer SDK requires Android KitKat 4.4 <=> API 19. Make sure your minSdkVersion is set to 19 or higher.
If your minSdkVersion is strictly below API 21 (usually 19) and you encounter a maximum number of functions reached, you might need to setup a multidex application. Follow the following steps from the official android documentation

Configuration

Proguard

If you are obfuscating your code, add the following rules to your proguard

                            -keep class io.streamroot.** { *; }
-dontwarn io.streamroot.lumen.**

Declare permissions

In your AndroidManifest.xml add the following permissions

                            <uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

Network security

Make sure your application allows clear text traffic.

First, add an xml resource (called here network_security_config.xml) to your project that defines the network security configuration:

                            <?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="true">
        <trust-anchors>
            <certificates src="system" />
        </trust-anchors>
    </base-config>
</network-security-config>
            
        

Then add the following attributes in the application of your androidManifest.xml

                            <manifest ...>
    <application
        ...
        android:usesCleartextTraffic="true"
        android:networkSecurityConfig="@xml/network_security_config">
    </application>
</manifest>
            
        

More info can be found in the Android documentation.

Set the delivery client key

deliveryClientKey refers to your Lumen unique identifier that you will find in the Account section of the CDN Load Balancer Dashboard. If you don't have a deliveryClientKey, you can ask for a free trial on our website.

In your AndroidManifest.xml add the Delivery Client Key in the application node.

                            <meta-data
android:name="io.streamroot.lumen.delivery.client.DeliveryClientKey"
android:value="<delivery-client-key>"
/>
            
        

Note: We strongly recommend setting the delivery client key in your AndroidManifest.xml. However, if it is not possible, you can specify it when instantiating a LumenDeliveryClient

Code Integration

SDK Initialization

SDK initialization is done preferably in an application context subclass.

Create subclass of Application ( or MultiDexApplication if your code base is big and you support API level 19 or 20. )
Initialize the SDK

                            class Application: MultiDexApplication() {

    override fun onCreate() {
        super.onCreate()
        /* If you could not add your Delivery Client Key in your AndroidManifest.xml
         * Call instead: LumenDeliveryClient.initializeApp(this, "<delivery-client-key>")
         */
        LumenDeliveryClient.initializeApp(this)
        ...
    }
}
            
        

Point to your custom application subclass in the AndroidManifest.xml

                android:name=".Application"

Instantiate a LumenDeliveryClientPlugin

The plugin creation is divided in two phases:

A plugin configuration phase which needs to interact with an ExoPlayer instance. This uses a builder pattern.
A orchestratorOptions continuation method which allows you to add extra parameters for CDN Load Balancer.

Plugin configuration

The plugin is always the one that will transform an ExoPlayer.Builder into an ExoPlayer instance. The keyword this in this section refers to an Android Context or any subclass.

Plugin is interacting with:

The LoadControl
The BandwidthMeter

Note: The plugin is always configuring things last so be warned that any custom modification with these classes will be overridden.

If you do not need to interact with the ExoPlayer instance before its construction with ExoPlayer.Builder then you can leave the SDK in charge of its creation.

                val builder = LumenDeliveryClientPlugin.Builder(this, manifestUrl)

If you need to interact with the ExoPlayer.Builder you can either create the ExoPlayer.Builder yourself or hook into one created by the plugin.

                            // Pre created
val exoPlayerBuilder = ExoPlayer.Builder(this)
val pluginBuilder = LumenDeliveryClientPlugin.Builder(this, manifestUrl).exoPlayerBuilder(exoPlayerBuilder)

// Using hook
val pluginBuilder = LumenDeliveryClientPlugin.Builder(this, manifestUrl).exoPlayerBuilder { exoPlayerBuilder ->  
    // Work with exoPlayerBuilder
}
            
        

If you need to override the LoadControl you can also either give it to us or hook to it. The LoadControl needs to be a DefaultLoadControl as this guarantees maximum efficiency.

                            // Pre created
val loadControlBuilder = DefaultLoadControl.Builder()
val pluginBuilder = LumenDeliveryClientPlugin.Builder(this, manifestUrl).loadControlBuilder(loadControlBuilder)

// Hook
val pluginBuilder = LumenDeliveryClientPlugin.Builder(this, manifestUrl).loadControlBuilder { defaultLoadControlBuilder ->
    // Work with defaultLoadControlBuilder
}
            
        

If you need to interact with the BandwidthController you can use us or subclass an ExoPlayerBandwidthMeter object:

                            val pluginBuilder = LumenDeliveryClientPlugin.Builder(this, manifestUrl).bandwidthMeterCustomFactory { exoPlayerBuilder ->
    ExoPlayerBandwidthMeter(this, exoPlayerBuilder)
}
            
        

Any other interaction with the ExoPlayer.Builder class should be safe to use as Lumen does not interact with anything else (including DRM, etc.)

CDN Load Balancer Delivery configuration

Once the plugin is configured, you can optionally call the method orchestratorOptions() on it. Inside that scope you can call one or multiple methods to configure CDN Load Balancer.

                            LumenDeliveryClientPlugin.Builder(this, manifestUrl).orchestratorOptions {
    /*
    * Set Orchestrator property
    *
    * param: String
    */
    orchestratorProperty("MY_PROPERTY")
    /*
    * Set the Delivery Client Key
    * Is only required if it was not set in AndroidManifest.xml
    * Will override the AndroidManifest.xml DeliveryClientKey
    *
    * param: String
    */
    deliveryClientKey("<delivery-client-key>")
    /*
    * Set the log level
    * See the "How to investigate?" to know more
    *
    * param: LumenLogLevel
    */
    logLevel(LumenLogLeven.INFO)
    /*
    * Set latency in seconds
    *
    * param: Int
    */
    latency(25)
    /*
    * Set a proxy server
    * Allows the use of a proxy server in the middle
    * Format is host:port
    *
    * params: String
    */
    proxyServer("MY_PROXY_HOST:PORT")
}
            
        

CDN Load Balancer plugin resolution

Once resolved the plugin keeps a strong reference on all used items and gives access to most of it including:

DeliveryClient (private)
ExoPlayer (public)
Context (public)
BandwidthMeter (public)
PlayerInteractor (public) (it’s a glue class that the plugin took care of embedding and configuring)
LoadControl (public)
originalUri (public)
finalUri (public)

You can access and use them, though the ExoPlayer instance and finalUri are definetely the mandatory ones.

                            // If you have no plugin config or orchestrator config steps
val plugin = LumenDeliveryClientPlugin.Builder(this, manifestUrl).build()

// Plugin configuration + orchestratorOptions (empty)
val plugin = LumenDeliveryClientPlugin.Builder(this, manifestUrl).loadControlBuilder{}.orchestratorOptions{}.build()

We recommend that you keep a strong reference to the plugin instance as this will keep strong refs of everything and you will be interacting with the plugin directly.

Start the SDK instance and get the final URL

Calling the start() method on the LumenDeliveryClient instance will start the SDK. Once you have a running instance of the SDK, you must retrieve the final URL and input it to your player instead of your original one.

                            plugin.start()
val finalUrl = plugin.finalUri

For convenience, you can also call start() directly on a DeliveryClientPlugin.Builder, it will resolve the plugin and pass it back in your provided lambda (skips .build() call).

Give your player the final URL

To maximize compatibility with the SDK we strongly encourage you to allow HTTP <-> HTTPS cross protocol redirects in your ExoPlayer media sources.

With finalUrl you can create the mediaItem for ExoPlayer, like this:

                val mediaItem = MediaItem.fromUri(finalUrl)

Stop the SDK instance

Once the video is done playing, you have to stop the SDK you created earlier.

                            // Calling stop will finish ongoing tasks and release all resources used
plugin.stop()

Compact integration example

                            LumenDeliveryClientPlugin.Builder(this, manifestUrl).orchestratorOptions {
    logLevel(LumenLogLevel.INFO)
}.start().apply {
    plugin = this // plugin is stocked in the activity as a field

    bindings.playerView.player = exoPlayer
    showStatsView(this) // see the StatsView section to understand this

    exoPlayer.playWhenReady = true
    exoPlayer.addMediaItem(MediaItem.fromUri(Uri.parse(finalUri)))
    exoPlayer.repeatMode = Player.REPEAT_MODE_ALL
    exoPlayer.prepare()
}
            
        

Troubleshooting

Enable logs

By default the log level is set to OFF, It can be overridden either at initialization which will propagate to all LumenDeliveryClient instances:

                            LumenDeliveryClient.setLogLevel(LumenLogLevel.INFO)
LumenDeliveryClient.initializeApp(this)

Or during orhcestratorOptions:

                            LumenDeliveryClientPlugin.Builder(this, manifestUrl).orchestratorOptions {
    logLevel(LumenLogLevel.INFO)
}
            
        

Note:

Valid value for LumenLogLevel are TRACE, CRITICAL, ERROR, WARNING, INFO, DEBUG or OFF.

You can also use LumenStatsView, a utils library that allows the display of CDN Load Balancer information on the device. For more information, please follow the Monitoring Tools documentation.

Learn how you can configure CDN Load Balancer for Android to best suit your needs

Explore CDN services