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 とセキュリティ上の注意事項​