1. ダウンロードの準備

SDK の初期化および認証、ストレージ権限の確認、デバイスの利用可能容量チェックなど、コンテンツダウンロードに必要な準備手順について説明します。

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

`KollusStorage` の初期化

サンプルアプリケーションは、内部および外部ストレージの管理のために MultiKollusStorage インスタンスを作成し、SD カードの Mount/Unmount 状態変化イベントに対応します。開発プロジェクトへの組み込み時も、同じ構造パターンの構成を推奨します。

// BaseActivity.java

mMultiStorage = MultiKollusStorage.getInstance(getApplicationContext());

mMultiStorage.setCertification(
    KollusConstants.KEY,           // SDK key issued by Catenoid
    KollusConstants.EXPIRE_DATE,   // Set authentication expiration date (e.g., "2050/12/31")
    isTablet);                     // Device type (true: tablet, false: mobile)

int nRet = mMultiStorage.getErrorCode();
if (nRet != ErrorCodes.ERROR_OK) {
    // If an error such as ERROR_INCORRECT_AUTH_KEY occurs, notify the user of key expiration or incorrect input, then terminate the process
}

// Register listener callbacks for event detection
mMultiStorage.registerKollusStorageListener(mKollusStorageListener);
mMultiStorage.registerKollusPlayerDRMListener(mKollusPlayerDRMListener);
mMultiStorage.registerSDStateChangeListener(mSDCardStateChangeListener);

setCertification メソッドが呼び出されると、SDK によって以下の処理が順番に実行されます。

KollusStorage.initialize(key, expireDate, packageName) の呼び出しによる SDK キーの検証
登録された各ストレージパスに対して storage.setDevice(path, isTablet) を通じたデバイスバインディング

ストレージ権限と容量の確認

コンテンツダウンロード処理を進めるために、アプリケーション仕様マニフェストおよびシステムランタイム環境に有効な権限の明示とディスク利用可能残容量の確認を行う必要があります。

外部ストレージアクセス権限: AndroidManifest.xml に READ_EXTERNAL_STORAGE 権限を宣言します。API 33 以上の環境では、メディア別の詳細権限である READ_MEDIA_VIDEO などを処理する必要があります。
フォアグラウンドサービス権限: アプリがバックグラウンドに移行した状態でもダウンロードおよび再生状態を維持するためのフォアグラウンド(Foreground)制御権限を設定します。
デバイスの利用可能容量確認: Utils.getAvailableMemorySize(path) メソッドを呼び出して、残りのディスク容量を確認します。
ダウンロード拒否しきい値の設定: サンプルアプリガイドの基準として MIN_FREE_SIZE = 150 MB 定数を定義します。コンテンツファイルサイズ + 150MB より現在のディスク空き容量が少ない場合は ERROR_STORAGE_FULL を返し、処理を拒否します。
ダウンロード状態維持ロック制御: ダウンロード中の省電力モードへの移行および Wi-Fi 切断を防止するため、PowerManager.WakeLock と WifiManager.WifiLock を使用します。

フォアグラウンドサービス権限の設定

1. マニフェストへの権限明示

フォアグラウンドサービスを使用するには、AndroidManifest.xml に以下のように権限を明示する必要があります。

<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />

FOREGROUND_SERVICE_MEDIA_PLAYBACK: 再生フォアグラウンドサービス（MoviePlayerService など）
FOREGROUND_SERVICE_DATA_SYNC: ダウンロードフォアグラウンドサービス（DownloadService など）

2. ダウンロードフォアグラウンドサービス登録パターン

バックグラウンド実行制限ポリシーによる強制終了を防ぐため、長時間実行されるタスクは必ず Service（例：DownloadService）内で実装することを推奨します。 Android 10(API 29)以上のビルドターゲットの場合、ダウンロードコンポーネントの実行パターン構成時に FOREGROUND_SERVICE_TYPE_DATA_SYNC サービス属性の定義が必須となります。

// DownloadService.java

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
    startForeground(
        KollusConstants.SERVICE_DOWNLOAD,
        notificationBuilder.build(),
        ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC);
} else {
    startForeground(KollusConstants.SERVICE_DOWNLOAD, notificationBuilder.build());
}

また、同様に AndroidManifest.xml のサービス宣言部にも一致するタイプを合わせて定義する必要があります。

<service
    android:name=".download.DownloadService"
    android:foregroundServiceType="dataSync" />

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

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

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

KollusStorage の初期化​

ストレージ権限と容量の確認​

フォアグラウンドサービス権限の設定​

1. マニフェストへの権限明示​

2. ダウンロードフォアグラウンドサービス登録パターン​

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