Lumen help
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?
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.
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
)
List of pulled dependencies
exo_version
variable, newest patch)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:relinke
randroidx.annotation:annotation
Notes:
minSdkVersion
is set to 19 or higher.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 documentationConfiguration
Proguard
If you are obfuscating your code, add the following rules to your proguard
Declare permissions
In your AndroidManifest.xml
add the following permissions
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:
Then add the following attributes in the application of your androidManifest.xml
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.
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.
Application
( or MultiDexApplication
if your code base is big and you support API level 19 or 20. )Instantiate a LumenDeliveryClientPlugin
The plugin creation is divided in two phases:
ExoPlayer
instance. This uses a builder pattern.orchestratorOptions
continuation method which allows you to add extra parameters for CDN Load Balancer.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:
LoadControl
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.
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.
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.
If you need to interact with the BandwidthController
you can use us or subclass an ExoPlayerBandwidthMeter
object:
Any other interaction with the ExoPlayer.Builder
class should be safe to use as Lumen does not interact with anything else (including DRM, etc.)
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.
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.
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.
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:
Stop the SDK instance
Once the video is done playing, you have to stop the SDK you created earlier.
Compact integration example
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:
Or during orhcestratorOptions
:
Note:
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.