Docs | iOS

Offline DRM Assets

This guide shows how to use offline (downloaded) DRM-protected assets. For how to download, see Offline Assets.

On this page:

• LocalAssetsManager
  • LocalDataStore
  • Create an instance
  • Register a new asset
  • Unregister an asset
  • Renew asset license
  • Check asset status
• Known Issue
• HLS Playlist setup
• More info

LocalAssetsManager

The class that manages offline assets is called LocalAssetsManager.

LocalDataStore

LocalDataStore is a protocol used by LocalAssetsManager to persist license data. The default implementation stores the licenses as files in the standard Library directory.

Applications should only customize LocalDataStore if they need to store the license files in another path or in a db.

Create an instance

To create an instance of the manager, call the static factory method managerWithDefaultDataStore(). It returns a LocalAssetsManager configured for DRM.

The manager needs to be stored in a property (or a singleton).

Register a new asset

Registering a downloaded asset includes connecting to the DRM server to acquire a FairPlay license (CKC) and securely storing that license locally for later.

Call the following method

registerDownloadedAsset(location: URL, mediaSource: PKMediaSource, callback: (Error?) -> Void)

• location: a URL (NSURL) that points to the downloaded asset (master playlist file).
• mediaSource: a PKMediaSource object with full parameters of the original (remote) file. Must contain a drmData array with a FairPlayDRMParams object
• callback: a block that will be called upon success or failure of the registration process. The callback takes one parameter - an Error. If error is nil, it means the registration was successful. Otherwise, it contains the error reason.

Unregister an asset

Before deleting an asset from storage, the application should tell LocalAssetsManager to remove the license linked with it. This is done by calling:

unregisterDownloadedAsset(location: URL, callback: (Error?) -> Void)

• location: the URL that was passed to registerDownloadedAsset(). The asset must still exist at this point
• callback: a block that will be called upon success or failure of the unregistration process. The callback takes one parameter - an Error. If the error is nil, it means the unregistration was successful. Otherwise, it contains the error reason.

Renew asset license

If the backend allows it, the asset license can be renewed (extended).

renewDownloadedAsset(location: URL, mediaSource: PKMediaSource, callback: @escaping (Error?) -> Void)

• location: the URL that was passed to registerDownloadedAsset()
• mediaSource: a PKMediaSource object like the one passed to registerDownloadedAsset(), with fresh DRM params
• callback: a block that will be called upon success or failure of the renew process. The callback takes one parameter - an Error. If the error is nil, it means the renew was successful. Otherwise, it contains the error reason.

Check asset status

To check the validity and expiration of a downloaded asset, the app can call the following function:

getLicenseExpirationInfo(location: URL) -> FPSExpirationInfo?

• location: the URL that was passed to registerDownloadedAsset()

The return value has a Date (NSDate) property named expirationDate. After that date/time, the asset can’t be played and the license has to be renewed.

Known Issue

It’s not possible to register/renew a specific license twice in the same application run. In other words, the following scenario will fail:

1. Download asset X - OK
2. Register the asset - OK
3. Delete asset - OK
4. Download asset X again - OK
5. Register the asset again - FAIL

However, if the application is closed and reopened before step #5 (for example, before downloading again), that second registration will succeed.

Likewise, if the offline license duration is very short and it expires in the same application session in which it was registered, renew will fail.

1. Download and register asset - OK
2. License duration is 5 minutes
3. After 6 minutes try to renew - FAIL.

HLS Playlist setup

NOTE: If the asset is FairPlay-protected, the master playlist MUST contain a EXT-X-SESSION-KEY tag with the asset’s skd URL. Without it, LocalAssetsManager won’t be able to install a FairPlay license. Example (replace ASSET_ID below with the actual id):
#EXT-X-SESSION-KEY:METHOD=SAMPLE-AES,URI="skd://ASSET_ID",KEYFORMAT="com.apple.streamingkeydelivery",KEYFORMATVERSIONS="1"
In Kaltura’s backend, this is done by enabling “Allow Fairplay Offline” in the VOD_PACKAGER_HLS delivery profile. See screenshot.

More info

For more info on offline assets and downloading, see Offline Assets and Download to Go.