Skip to content

Download Documentation

Swift Version Platform CocoaPods Compatible Carthage Compatible Swift Package Manager

Requirements

  • iOS 12.0+ (FairPlay requires iOS 10.0+)
  • Swift 5.0+
  • Xcode 13.2+

Framework dependencies:

Installation

The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift compiler. Once you have your Swift package set up, adding iOSClientExposureDownload as a dependency is as easy as adding it to the dependencies value of your Package.swift.

dependencies: [
    .package(url: "https://github.com/EricssonBroadcastServices/iOSClientExposureDownload", from: "3.5.2")
]

CocoaPods

CocoaPods is a dependency manager for Cocoa projects. For usage and installation instructions, visit their website. To integrate iOSClientExposureDownload into your Xcode project using CocoaPods, specify it in your Podfile:

pod 'iOSClientExposureDownload', '~>  3.5.2'

Carthage

Carthage is a decentralized dependency manager that builds your dependency graph without interfering with your Xcode project setup. CI integration through fastlane is also available.

Install Carthage through Homebrew by performing the following commands:

$ brew update
$ brew install carthage

Once Carthage has been installed, you need to create a Cartfile that specifies your dependencies. Please consult the artifacts documentation for in-depth information about Cartfiles and the other artifacts created by Carthage.

github "EricssonBroadcastServices/iOSClientExposureDownload"

Running carthage update will fetch your dependencies and place them in /Carthage/Checkouts. You can then build the .framework files and drag them into your Xcode project or attach the fetched projects to your Xcode workspace.

Finally, make sure to add the .framework files to your target's General -> Embedded Binaries section.

Usage

Client applications can use the ExpoureDownload by confirming EnigmaDownloadManager to any class:

class MyTestViewController: UIViewController, EnigmaDownloadManager {
    // After confirming, client applications can use the `enigmaDownloadManager` instance to perform any download-related tasks.
}

Identify Downloadable Assets

All assets might not be downloadable even if a customer supports download. There can be a restriction on blocking downloads for a specific user. ExposureDownload provides an API (isAvailableToDownload()) to check if an Asset is available to download. Client applications can perform the download check by passing the assetId and the sessionToken.

enigmaDownloadManager.isAvailableToDownload(assetId: assetId, environment: environment, sessionToken: SessionToken) { _ in
    // Handle Response (true / false)
}

Identify What Can be Downloaded for a Specific Asset

When a user selects an actually downloadable asset, ExposureDownload provides an option to check what can be downloadable for that asset (audios, videos, subtitles).

enigmaDownloadManager.getDownloadableInfo(assetId: assetId, environment: environment, sessionToken: session) { downloadInfo in
    // Handle Response
    // downloadInfo.audios, downloadInfo.videos, downloadInfo.subtitles
}

Downloading Assets

To download an Asset, client applications can create a downloadTask by passing the assetId. The task can be prepared and resumed to start downloading the asset. Tasks can be suspended and canceled.

let task = enigmaDownloadManager.download(assetId: assetId, using: session, in: environment)
task.prepare()
task.resume()
task.suspend()
task.cancel()

downloadTask publishes several events that the client applications can listen to.

task.onPrepared { _ in
    print("📱 Media Download prepared")
    // task.resume()
}
.onCanceled { task, url in
    print("📱 Media Download canceled", task.configuration.identifier, url)
}
.onSuspended { _ in
    print("📱 Media Download Suspended")
}
.onResumed { _ in
    print("📱 Media Download Resumed")
}
.onProgress { _, progress in
    print("📱 Percent", progress.current * 100, "%")
}
.onError { _, url, error in
    print("📱 Download error: \(error)")
}
.onCompleted { _, url in
    print("📱 Download completed: \(url)")
}

Downloading Additional Media

To download additional media such as audios and subtitles, client applications can use the same downloadTask.

task.addAllAdditionalMedia() // will download all additional media

Downloading Specific Media

To download a specific media, pass the bit rate to downloadTask.

task.use(bitrate: _)

Check if Downloaded Asset has Expired

Client applications can check if a downloaded asset has expired using the isExpired method provided by the enigmaDownloadManager. This method allows client applications to determine whether a downloaded asset has expired. The method

If there is an internet connection , SDK will try to fetch the download asset's publicationEnd value from downloadverified and compare it with the playTokenExpiration & use the smallest value, Then compares the samllest with Date() (Today) to check if an asset is expired or not.

enigmaDownloadManager.isExpired(assetId: asset.assetId, environment: environment, sessionToken: session) { expired, error in
    if let error = error {
        // Handle the error, e.g., network issue or authentication problem
        print("Error: \(error.localizedDescription)")
    } else {
        // Handle the expiration status
        if expired {
            print("Asset has expired.")
            // Perform actions for an expired asset
        } else {
            print("Asset is still valid.")
            // Perform actions for a valid asset
        }
    }
}

Client developers can also fetch the expiryTime of a downloaded asset using getExpiryTime(assetId: String, environment: Environment, sessionToken: SessionToken).

enigmaDownloadManager.getExpiryTime(assetId: asset.assetId, environment: environment, sessionToken: session) { expiryTime, error in
    // expiryTime
}

Renew License

If the license has expired, you can renew the licenses by using the following API:

let _ = enigmaDownloadManager.renewLicense(assetId: assetId, sessionToken: session, environment: environment) { offlineMediaAsset, error in
    // print("Updated offline media asset \(offlineMediaAsset)")
}

Playback of a Downloaded Asset

Client applications can get an offlineMediaAsset (downloaded asset) by using the EnigmaDownloadManager.

To get all downloads related to a given assetId:

let downloadedAsset = enigmaDownloadManager.getDownloadedAssets(assetId: assetId)

To get all downloads related to a given userId:

let downloadedAsset = enigmaDownloadManager.getDownloadedAssets(userId: userId)

Or client applications can get AllDownloadedAssets by using getDownloadedAssets().

let allDownloadedAssets = enigmaDownloadManager.getDownloadedAssets()

Then developers can create an OfflineMediaPlayable and pass it to the player to play any downloaded asset. However, when playing downloaded MP3 files, AVPlayer sometimes doesn't work. In such cases, client application developers are encouraged to use AVAudioPlayer or AVAudioEngine to play offline MP3 files. Check the SDK Sample application for an example implementation (https://github.com/EricssonBroadcastServices/iOSClientSDKSampleApp).

OfflineMediaPlayable has the attribute format that will pass the format of the downloaded file.

let downloadedAsset = enigmaDownloadManager.getDownloadedAsset(assetId: assetId)

if let entitlement = downloadedAsset?.entitlement, let urlAsset = downloadedAsset?.urlAsset, let format = downloadedAsset?.format {

    if format == "MP3" || format == "mp3" {
        // Create `AVAudioPlayer` or `AVAudioFile` and pass to `AVAudioEngine`
    } else {
        let offlineMediaPlayable = OfflineMediaPlayable(assetId: assetId, entitlement: entitlement, url: urlAsset.url)

        // Play downloaded asset
        player.startPlayback(offlineMediaPlayable: offlineMediaPlayable)
    }
}

Deleting Downloaded Asset

To delete a downloaded asset, developers can use removeDownloadedAsset(assetId:).

let _ = enigmaDownloadManager.removeDownloadedAsset(assetId: assetId)

State of a Downloaded Asset

Client applications can get the download state of an offlineMediaAsset (downloaded asset) by using the getDownloadState().

let downloadedAsset = enigmaDownloadManager.getDownloadedAsset(assetId: assetId)
let downloadState = downloadedAsset.getDownloadState()

switch downloadState {
    case .completed:
        // Completed
    case .cancel:
        // Canceled
    case .notDownloaded:
        // Not downloaded
    case .suspend:
        // Suspended
    case .started:
        // Download has started
    case .downloading:
        // In some cases, `offlineMediaAsset` can have the state of `downloading` even when there is no ongoing active download task.
        // In this case, it is recommended to check the playable state of the `offlineMediaAsset`

        let _ = downloadedAsset.state { playableState in
            switch playableState {
                case .completed(entitlement: let entitlement, url: let url):
                    self.downloadState = .downloaded
                case .notPlayable(entitlement: let entitlement, url: _):
                    self.downloadState = .suspended
            }
        }
}

Fairplay Integration

SDK provides an out-of-the-box implementation for downloading FairPlay protected assets. Client applications can create a downloadTask and start downloading. SDK will download the relevant FairPlay licenses and keys and will use them when you are trying to play a FairPlay protected downloaded asset using ExposurePlayBack.