Menu

Lumen help

CDN Load Balancer SDK for iOS, iPadOS & tvOS

CDN Load Balancer can be easily integrated into your iOS and tvOS app in just a few simple steps using our SDK for iOS. In this guide, we will show you how to integrate CDN Load Balancer using AVPlayer on iOS.

Not into tutorials?  

Code Example

Note: AVPlayer is part of AVFoundation framework of the iOS family and provides the interface to control the playback and timing of a media asset using only the HLS format. Learn more about it from te AVPlayer documentation.

Project Setup

CocoaPods

Note: Cocoapods 1.9.0 + is recommended

To integrate CDN Load Balancer SDK into your Xcode project using CocoaPods, specify this in your Podfile:

                target 'MyApp' do
  use_frameworks!
  pod 'LumenOrchestratorSDK'
end

Configuration

Disable app transport security

 

In the Project Navigator, right click on "Info.plist", and "Open as" → "Source Code". Add the following lines with the right parameters values.

                <key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsArbitraryLoads</key>
  <true/>
</dict>

Set the client delivery key


In the Project Navigator, right click on the main target "Info.plist", and "Open as" → "Source Code".
 

Add the following lines with the values of the right parameters:

                <key>DeliveryClient</key>
<dict>
  <key>Key</key>
  <string><delivery-client-key></string>
</dict>

Here, the key element contained in DeliveryClient refers to the deliveryClientKey that you will find in the Account section of the CDN Load Balancer Dashboard. If you don't have a DeliveryClientKey, you can register for a free trial account on our website.

 

We strongly recommend to set the delivery client key in Info.plist. However, if not possible, it is also possible to pass your delivieryClientKey during the initialization step.

Code integration

First, import the SDK.

                import LumenOrchestratorSDK

SDK initialization


Initialize the CDN Load Balancer SDK from the AppDelegate.

                @main
class AppDelegate: UIResponder, UIApplicationDelegate {
  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    /*
     * If you can not add your Delivery Client Key in Info.plist
     * Call instead: LMDeliveryClient.initializeApp(withDeliveryKey: "<delivery-client-key>")
     */
    LMDeliveryClient.initializeApp()
    ...
  }

  ...
}

Bridge between your player and the LMDeliveryClient

 

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 needs to inherit from LMPlayerInteractorBase and meet the following requirements:
 

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

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

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

  • The trackSwitchOccurred() 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 AVPlayer  in PlayerInteractor.swift.

Instantiate a LMDeliveryClient


Now that the SDK is initialized, you are able to create LMDeliveryClient instances. They can be easily configured as such:

                func createDeliveryClient() -> LMDeliveryClient {
  return LMDeliveryClientBuilder.clientBuilder()
         /*
          * Set the player interactor to use
          * Check the bridge section to know more
          *
          * param: an instance of a class subclassing LMPlayerInteractorBase.
          */
         .playerInteractor(PlayerInteractor())
         /*
          * Build a LumenDeliveryClient instance
          *
          * param: String. The video stream url
          */
         .build(url)
}

Note: PlayerInteractor is referencing the bridge class from the previous step. The name maybe different, but it must subclass LMPlayerInteractorBase

Start the SDK instance and get the final URL


Calling the start() method on the LMDeliveryClient 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.

                var deliveryClient = createDeliveryClient()
deliveryClient.start();

guard let deliveryUrl = deliveryClient.localManifestURL else {
  fatalError("Local url manifest could not be generated")
}

let playerItem = AVPlayerItem(asset: AVURLAsset(url: deliveryUrl))

Play the stream


Start the player with the new URL provided by the LMDeliveryClient and link it with  PlayerInteractor:

                let player = AVPlayer(playerItem: playerItem)
playerInteractor.linkPlayer(player!)

player?.play()

Stop the SDK

 

Make sure to stop the LMDeliveryClient once you are done with the video. We recommend to put it in the viewDidDisappear(:bool) or any callback terminating the player lifecycle.

                self.deliveryClient.stop()

Additional options

You can pass additional options during the creation of a LMDeliveryClient

                func createDeliveryClient() -> LMDeliveryClient {
  return LMDeliveryClientBuilder.clientBuilder()
         /*
          * Set the player interactor to use
          * Check the bridge section to know more
          *
          * param: an instance of a class subclassing LMPlayerInteractorBase.
          */
         .playerInteractor(PlayerInteractor())
         /*
          * Set Orchestrator property
          *
          * param: String
          */
         .orchestratorProperty("MY_PROPERTY")
         /*
          * Set the Delivery Client Key
          * Is only required if it was not set in Info.plist
          * Will override the Info.plist DeliveryClientKey value
          *
          * param: String
          */
         .deliveryClientKey("<delivery-client-key>")
         /*
          * Set the log level
          * See the "How to investigate?" to know more
          *
          * param: LumenLogLevel
          */
         .logLevel(.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 a LumenDeliveryClient instance
          *
          * param: String. The video stream url
          */
         .build(url)
}

Troubleshooting

Enable logs


By default the log level is set to OFF. it can be overridden during a LMDeliveryClient Creation: 

                func createDeliveryClient() -> LMDeliveryClient {
  return LMDeliveryClientBuilder.clientBuilder()
         .playerInteractor(PlayerInteractor())
         .logLevel(.warning)
         .build(url)
}

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 iOS to best suit your needs