1. Download Preparation

Notice

This document is a machine-translated draft and is currently undergoing review. Some content may be inaccurate or differ from the original Korean version. For the most precise information, refer to the Korean documentation.

This document describes the preparation steps for content download, including SDK initialization and authentication, selecting a start method (start), configuring background downloads, and checking available device storage.

All example code in this document is based on the official sample app, kollus_player_ios.

`Kollusstorage` initialization

The sample application implements and uses a StorageManager class for SDK authentication and management. We recommend following the same structural pattern when integrating with your development project.

import UIKit
// import KollusSDK  (or exposed via Bridging Header)

class StorageManager: NSObject {
    static let shared = StorageManager()
    let storage: KollusStorage

    override init() {
        storage = KollusStorage()
        super.init()

        storage.applicationKey      = "SDK_KEY"  // SDK key issued by Catenoid
        storage.applicationBundleID = "com.yourcompany.yourapp" // App's Bundle ID

        // Set authentication expiration date
        let formatter = DateFormatter()
        formatter.dateFormat = "yyyy/MM/dd"
        formatter.calendar   = Calendar(identifier: .gregorian)
        storage.applicationExpireDate = formatter.date(from: "2030/12/31")

        // (Optional) Keychain group: used when sharing data with multiple apps or app extensions
        // storage.keychainGroup = "com.yourcompany.shared"

        // (Optional) Set dynamic DRM parameters
        // storage.extraDrmParam = "..."
    }

    public func validateSDK() {
        do {
            try storage.start()
            storage.setBackgroundDownload(true)
        } catch {
            // Classify error situations using (error as NSError).code value
            print(error.localizedDescription)
        }
    }
}

Select a start method

In a typical environment, use the start() or startWithCheck() method. If recovery due to a lost playerID is needed, you can use the startWithNewPlayerID() method.

Method	Behavior
`start()`	Starts the engine in a typical environment.
`start(withFirst: Bool)`	Starts by explicitly passing the first-run flag after the application is installed.
`startWithCheck()`	If acquiring a `playerID` from the keychain fails, automatically generates a new one and retries. Generates a new one on first launch; returns an error if it fails 3 or more times in subsequent runs.
`startWithNewPlayerID()`	Forcibly generates a new `playerID`, registers it in the system keychain, and starts.

Enable background download

storage.setBackgroundDownload(true)

When this option is enabled, content downloads continue even after the app transitions to the background. However, the process may be suspended after a certain period due to iOS system policies and network conditions. To increase the likelihood of completing downloads, it is recommended to also review the Background Configuration pattern for URLSession.

Query storage information

You can directly query the path and status metadata of the designated local storage through the KollusStorage instance.

Property	Return information and description
`storage.storagePath`	Path of the storage folder used by the SDK (`NSString`)
`storage.storageSize`	Total size of downloaded content (bytes)
`storage.cacheDataSize`	Total size of streaming cache data (bytes)
`storage.applicationDeviceID`	Device ID
`storage.applicationVersion`	Kollus SDK version
`storage.appUserAgent`	User-Agent information in the system header used for internal SDK communication
`storage.deviceType`	Device type (`kp-mobile`: mobile, `kp-tablet`: tablet)

Register a storage delegate

storage.delegate = self

For a description of the KollusStorageDelegate protocol, refer to the 8. Download Events/Callbacks document.

Check available device storage

Before starting a download, verify that the available device storage is at least the sum of the content file size and minimum free space (e.g., 150MB).

let free = DiskStatus.freeDiskSpaceInBytes

Content download URL and security considerations

The download target URL generally follows a one-time URL structure such as https://v.kr.kollus.com/s?jwt=....

Server-to-server integration required: Since the JWT issuance logic contains a security key, it must be performed on the customer's backend server. The mobile app client must not generate JWTs directly, as this may introduce security vulnerabilities.
SDK handling: The mobile app passes the URL received from the customer's server to the SDK's loadContentURL(_:) method without modification. For more details, refer to the 3. Content Download document.

Kollusstorage initialization​

Select a start method​

Enable background download​

Query storage information​

Register a storage delegate​

Check available device storage​

Content download URL and security considerations​