Skip to main content

1. Download Preparation

This document describes the preparation steps for content download, including SDK initialization and authentication, storage permission checks, and device available capacity checks.

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

Kollusstorage initialization​

The sample application creates a MultiKollusStorage instance for internal and external storage management, and responds to SD card mount/unmount state change events. The same structural pattern is recommended when integrating with your development project.

// 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);

When the setCertification method is called, the SDK sequentially performs the following tasks.

  1. SDK key validation via a KollusStorage.initialize(key, expireDate, packageName) call
  2. Device binding via storage.setDevice(path, isTablet) for each registered storage path

Storage permission and capacity check​

To proceed with content download tasks, you must declare valid permissions in the application manifest and system runtime environment, and check the remaining available disk capacity.

  • External storage access permission: Declare the READ_EXTERNAL_STORAGE permission in AndroidManifest.xml. For API 33 and above, you must handle media-specific permissions such as READ_MEDIA_VIDEO.
  • Foreground service permission: Configure foreground service control permissions to maintain download and playback state even when the app is in the background.
  • Device available capacity check: Call the Utils.getAvailableMemorySize(path) method to check the remaining disk capacity.
  • Download rejection threshold setting: Define the constant MIN_FREE_SIZE = 150 MB based on the sample app guide. If the current free disk space is less than content file size + 150MB, return ERROR_STORAGE_FULL and reject the task.
  • Download state lock control: Use PowerManager.WakeLock and WifiManager.WifiLock to prevent sleep mode and Wi-Fi disconnection during download.

Configure foreground service permissions​

1. declare manifest permissions​

To use foreground services, you must declare the following permissions in 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: Playback foreground service (e.g., MoviePlayerService)
  • FOREGROUND_SERVICE_DATA_SYNC: Download foreground service (e.g., DownloadService)

2. download foreground service registration pattern​

To prevent forced termination due to background execution restriction policies, it is strongly recommended to implement long-running tasks inside a Service (e.g., DownloadService). For build targets of Android 10 (API 29) or higher, defining the FOREGROUND_SERVICE_TYPE_DATA_SYNC service attribute is mandatory when configuring the download component execution pattern.

// 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());
}

In addition, the matching type must also be declared in the service declaration in AndroidManifest.xml.

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

Content download URL and security considerations​

The download target URL generally has 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 can introduce security vulnerabilities.
  • SDK handling method: The mobile app passes the URL received from the customer's server to the SDK's load(url, ...) method without modification.