Exposure Download

• Features

• License

• Requirements

• Installation

• Usage

  • Downloading Assets
  • Identify Downloadable Assets
  • Playback of a downloaded Asset
  • Deleting downloaded Asset
  • Fairplay Integration
  • Error Handling

• Release Notes

• Upgrade Guides

• Roadmap

• Contributing

Features

• ☑ Download through Exposure
• ☑ Playback of Downloaded Assets

Requirements

• iOS 11.0+ (FairPlay requires iOS 10.0+)

• Swift 5.0+

• Xcode 10.2+

• Framework dependencies

  • Download
  • Exposure
  • Exact versions described in Cartfile

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.2.0")
]

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.2.0'

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 which 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 either build the .frameworks and drag them in your Xcode or attach the fetched projects to your Xcode workspace.

Finally, make sure you add the .frameworks to your targets 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 `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 restriction of blocking downloads for a specific user. ExposureDownload provides an API (isAvailableToDownload()) to check if an Asset is available to download.

Then client applications can perform the download check by passing the assetId & 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 select 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 . Task can be prepare & resume to start downloading the asset. task.suspend() will temporary suspend the downloading task. Suspended task can be resume.
task.cancel() will cancel the task.

    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 & subtitles client applications can use the same downloadTask.

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

    // .addAudios(hlsNames: ["French", "German"])
    // .addSubtitles(hlsNames: ["French"])

Refresh licence

Client applications can use enigmaDownloadManager check if the license for a download asset has expired by passing the assetId

    enigmaDownloadManager.isExpired(assetId: asset.assetId) // true / false 

If the license has expired , you need to use the downloadTask to refresh the licenses.

    task.refreshLicence()
    task.onError {_, url, error in
        print("📱 RefreshLicence Task failed with an error: \(error)",url ?? "")
    }
    .onCompleted { _, url in
        print("📱 RefreshLicence Task completed: \(url)")
    }

Playback of a downloaded Asset

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

All downloads related to given assetId

    let downloadedAsset = enigmaDownloadManager.getDownloadedAssets(assetId: assetId)

All downloads related to 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 a OfflineMediaPlayable & pass it to the player to play any downloaded asset.

    let downloadedAsset = enigmaDownloadManager.getDownloadedAsset(assetId: assetId)
    
    if let entitlement = downloadedAsset?.entitlement, let urlAsset = downloadedAsset?.urlAsset {
    
        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, developer can use removeDownloadedAsset(assetId:)

    let _ = enigmaDownloadManager.removeDownloadedAsset(assetId: assetId)

Fairplay Integration

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

Release Notes

Release specific changes can be found in the CHANGELOG.

Upgrade Guides

The procedure to apply when upgrading from one version to another depends on what solution your client application has chosen to integrate Exposure.

Major changes between releases will be documented with special Upgrade Guides.

Carthage

Updating your dependencies is done by running carthage update with the relevant options, such as --use-submodules, depending on your project setup. For more information regarding dependency management with Carthage please consult their documentation or run carthage help.

Roadmap

No formalised roadmap has yet been established but an extensive backlog of possible items exist. The following represent an unordered wish list and is subject to change.

Contributing