1. ダウンロード準備

SDK 初期化および認証、スタートメソッド(start)の選択、バックグラウンドダウンロード設定、デバイスの利用可能容量チェックなど、コンテンツダウンロードのための準備段階について説明します。

このドキュメントのすべてのサンプルコードは、公式サンプルアプリ kollus_player_ios をもとに作成されています。

KollusStorage の初期化

サンプルアプリケーションは、SDK 認証および管理のために StorageManager クラスを実装して使用します。 開発プロジェクトへの連携時も、同様の構造的パターン構成を推奨します。

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)
        }
    }
}

スタートメソッドの選択

一般的な環境では start() または startWithCheck() メソッドを使用します。 playerID の紛失による復旧が必要な場合は、startWithNewPlayerID() メソッドを使用できます。

メソッド	動作
start()	一般的な環境でエンジンを起動します。
start(withFirst: Bool)	アプリケーションインストール後の初回起動フラグを明示的に渡して起動します。
startWithCheck()	キーチェーンから playerID の取得に失敗した場合、自動生成および再試行を行います。初回起動時は新規生成し、以降の起動で 3 回以上失敗するとエラーを返します。
startWithNewPlayerID()	playerID を強制的に新規生成した後、システムキーチェーンに登録して起動します。

バックグラウンドダウンロードの有効化

storage.setBackgroundDownload(true)

このオプションを有効にすると、アプリがバックグラウンド状態に移行した後もコンテンツのダウンロードが継続されます。 ただし、iOS システムポリシーおよびネットワーク環境により、一定時間後にプロセスが一時停止される場合があります。ダウンロード完了の可能性を高めるには、URLSession のバックグラウンド設定(Background Configuration)パターンを併せて検討することを推奨します。

ストレージ情報の照会

KollusStorage インスタンスを通じて、指定されたローカルストレージのパスおよびステータスメタデータを直接照会できます。

プロパティ	返却情報および説明
storage.storagePath	SDK が使用するストレージフォルダのパス(NSString)
storage.storageSize	ダウンロードコンテンツの総容量(bytes)
storage.cacheDataSize	ストリーミングキャッシュデータの総容量(bytes)
storage.applicationDeviceID	デバイス ID
storage.applicationVersion	Kollus SDK バージョン
storage.appUserAgent	SDK 内部通信時のシステムヘッダーの User-Agent 情報
storage.deviceType	デバイスタイプ（kp-mobile：モバイル、kp-tablet：タブレット）

ストレージデリゲートの登録

storage.delegate = self

KollusStorageDelegate プロトコルについては、8. ダウンロードイベント/コールバック ドキュメントを参照してください。

デバイスの利用可能容量の確認

ダウンロード開始前に、デバイスの利用可能容量がコンテンツファイルサイズと最小空き容量（例：150MB）の合計値以上であることを確認します。

let free = DiskStatus.freeDiskSpaceInBytes

コンテンツダウンロード URL とセキュリティ上の注意事項

ダウンロード対象の URL は、一般的に https://v.jp.kollus.com/s?jwt=... のような一回限り(One-time)の URL 構造を持ちます。

• サーバー間連携が必須: JWT 発行ロジックにはセキュリティキーが含まれるため、必ずお客様のバックエンドサーバーで実行する必要があります。セキュリティ上の脆弱性が生じる可能性があるため、モバイルアプリクライアントで、JWTを直接生成しないでください。
• SDK の処理方式: モバイルアプリはお客様のサーバーから受け取った URL を変更せずそのまま SDK の loadContentURL(_:) メソッドに渡して使用します。詳細については、3. コンテンツダウンロード ドキュメントを参照してください。