Lumen help
Introduction
CDN Load Balancer can be integrated into your android app using ExoPlayer in just a few simple steps and this article will guide you through them.
Not into tutorials?
To integrate the CDN Load Balancer SDK, we need:
The easiest way to get the CDN Load Balancer SDK 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
Next, add the CDN Load Balancer SDK dependency. Add in your module build.gradle
(it often ends with .app)
CDN Load Balancer SDK will be pulled, but also other dependencies. Here is an exhaustive list:
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:
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. )Bridge between your player and the LumenDeliveryClient
In order to work correctly, the SDK instance uses a PlayerInteractor
.
It is the component in charge of the interactions between the player and the SDK. It monitors Quality of Service (QoS) metrics and allows the SDK to behave accordingly.
To feed the SDK properly, this class has to meet the following requirements:
playerError()
method must be called whenever an error occurs.playerFrameDrop()
method must be called when a frame is dropped.playerStateChange()
method must be notified of each player state change.playerTrackSwitch()
method must be called when the player changes the current track.
The remaining methods should not be implemented as they are not used for CDN Load Balancer.
When integrating the SDK, you are free to implement this component but we provide an implementation example PlayerInteractor
that satisifies these requirements for ExoPlayer in ExoPlayerCDNLoadBalancer (Kotlin) or ExoPlayerCDNLoadBalancer (Java).
Instantiate a LumenDeliveryClient
Now that the SDK is initialized, you are able to create LumenDeliveryClient
instances.
You first need to create and setup your ExoPlayer instance. Then the following function shows you how to configure DC instances using a SimpleExoPlayer
:
Note: PlayerInteractor
is referencing the bridge class from the previous step. The name maybe different.
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.
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.
You can pass additional options when creating a LumenDeliveryClient
Troubleshooting
Enable logs for initialization
By default the log level is set to OFF
for initialization. It can be turned on before calling the initializeApp
:
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.