Menu

Lumen help

Integrate with CDN Load Balancer SDK for Android & Android TV

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?  

Code Example

Prequisite

To integrate the CDN Load Balancer SDK, we need:

 

  • A Valid Delivery Client Key (also called Streamroot Key). It is available in the 'Account' section of your dashboard.

  • The CDN Load Balancer SDK installed.

  • ExoPlayer versions supported by this sample are 2.18.1

SDK Installation

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

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

Next, add the CDN Load Balancer SDK 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"

implementation "io.streamroot.lumen.delivery.client:orchestrator-sdk:$dc_version"

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:
 

  • 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)
        ...
    }
}
            
                public class Application extends MultiDexApplication {
    @Override
    public void 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"
            
                android:name=".Application"

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:
 

  • The playerError() method must be called whenever an error occurs.

  • The playerFrameDrop() method must be called when a frame is dropped.

  • The playerStateChange() method must be notified of each player state change.

  • The 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 :

                private fun createDeliveryClient(
    player: ExoPlayer,
    loadControl: DefaultLoadControl,
    bandwidthMeter: ExoPlayerBandwidthMeter
) : LumenDeliveryClient {
    val playerInteractor = PlayerInteractor(player, loadControl, bandwidthMeter)
    return LumenDeliveryClient.orchestratorBuilder(this) //< applicationContext
            /*
             * Set the player interactor that will be used by the SDK
             * Check the bridge section to know more
             *
             * param: an instance of a class subclassing LumenPlayerInteractorBase.
             */
            .playerInteractor(playerInteractor)
            /*
             * Build a LumenDeliveryClient instance
             *
             * param: String. The video stream url
             */
            .build(manifestUrl)
}
            
                private LumenDeliveryClient createDeliveryClient(ExoPlayer player, DefaultLoadControl loadControl, PlayerInteractor.ExoPlayerBandwidthMeter bandwidthMeter) {
    final PlayerInteractor playerInteractor = new PlayerInteractor(player, loadControl, bandwidthMeter);

    return LumenDeliveryClient
            .orchestratorBuilder(this)
            /*
             * Set the player interactor that will be used by the SDK
             * Check the bridge section to know more
             *
             * param: an instance of a class subclassing LumenPlayerInteractorBase.
             */
            .playerInteractor(playerInteractor)
            /*
             * Build a LumenDeliveryClient instance
             *
             * param: String. The video stream url
             */
            .build(manifestUrl);
}

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.

                deliveryClient.start()
val finalUrl = deliveryClient.localUrl()
            
                deliveryClient.start()
final String finalUrl = deliveryClient.localUrl();

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(Uri.parse(finalUrl))
            
                MediaItem mediaItem = MediaItem.fromUri(Uri.parse(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
deliveryClient.stop()
            
                // Calling stop will finish ongoing tasks and release all resources used
deliveryClient.stop();

Additional Options

You can pass additional options when creating a LumenDeliveryClient

                private fun createDeliveryClient(
    player: ExoPlayer,
    loadControl: DefaultLoadControl,
    bandwidthMeter: ExoPlayerBandwidthMeter
) : LumenDeliveryClient {
    val playerInteractor = PlayerInteractor(player, loadControl, bandwidthMeter)   return LumenDeliveryClient
            .orchestratorBuilder(applicationContext)
            .playerInteractor(playerInteractor)
            .options {
                /*
                * 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 content id
                * A string that identifies your content
                * By default, it uses the stream url
                *
                * param: String
                */
                contentId("MY_CONTENT_ID")
                /*
                * Set the log level
                * See the "How to investigate?" to know more
                *
                * param: LumenLogLevel
                */
                logLevel(LumenLogLeven.INFO)
                /*
                * Set latency in seconds
                *
                * param: Int
                */
                latency(3)
                /*
                * 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")
            }
            .build(manifestUrl)
}
            
                private LumenDeliveryClient createDeliveryClient(ExoPlayer player, DefaultLoadControl loadControl, PlayerInteractor.ExoPlayerBandwidthMeter bandwidthMeter) {
    final PlayerInteractor playerInteractor = new PlayerInteractor(player, loadControl, bandwidthMeter);

    return LumenDeliveryClient
            .orchestratorBuilder(this)
            .playerInteractor(playerInteractor)
            .options(o -> {
                /*
                * Set Orchestrator property
                *
                * param: String
                */
                o.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
                */
                o.deliveryClientKey("<delivery-client-key>");
                /*
                * Set the content id
                * A string that identifies your content
                * By default, it uses the stream url
                *
                * param: String
                */
                o.contentId("MY_CONTENT_ID");
                /*
                * Set the log level
                * See the "How to investigate?" to know more
                *
                * param: LumenLogLevel
                */
                o.logLevel(LumenLogLeven.INFO);
                /*
                * Set latency in seconds
                *
                * param: Int
                */
                o.latency(3);
                /*
                * Set a proxy server
                * Allows the use of a proxy server in the middle
                * Format is host:port
                *
                * params: String
                */
                o.proxyServer("MY_PROXY_HOST:PORT");

                return null;
            }).build(manifestUrl);
}

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 :

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

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