Skip to main content

Anti-patterns (Common Mistakes)

This document covers common incorrect implementation cases (anti-patterns) that occur when integrating the Kollus iOS SDK, along with the correct solutions. Please review the following items before development to ensure a stable service implementation.

Generate JWT URL directly within a mobile app​

Anti-pattern

Implementing JWT signing logic that includes a security key directly in the mobile client app (iOS) source code

  • Problem: The security key can be exposed externally, creating a serious security vulnerability.
  • Correct approach: JWT must be issued on the customer's server and then delivered to the mobile app.

Mix loadContentURL and checkContentURL methods​

Anti-pattern

Calling the checkContentURL(_:) method instead of loadContentURL(_:) first when downloading new content

  • Problem: checkContentURL(_:) only checks whether the URL matches an already registered download link. If an unregistered URL is passed, it only throws an error and does not register the content information to download.
  • Correct approach: To download new content, you must call loadContentURL(_:) first to register the content information.

Misuse downloadCancelContent method for pausing​

Anti-pattern

Calling the downloadCancelContent method to pause a content download

  • Problem: downloadCancelContent cancels the download, which means the entire file must be downloaded from the beginning when resuming.
  • Correct approach: If partial resumption is required, track the progress state separately and verify the SDK's resume behavior directly.

Automatically re-download the entire file when DRM-expired content is played​

Anti-pattern

Implementing logic to re-download the video file itself when a DRM license has expired

  • Problem: This generates unnecessary network traffic and increases the user's download wait time.
  • Correct approach: Without re-downloading the video file, simply call the updateDownloadDRMInfo method to renew only the DRM license. For details, refer to the 6. DRM License Renewal document.

Assume setBackgroundDownload(true) also handles license renewal in the background​

Anti-pattern

Implementing under the assumption that enabling the setBackgroundDownload(true) option will also reliably sustain the license renewal process in the background

  • Problem: This option only maintains file downloads in the background and does not guarantee that license renewal operations will be performed in the background.
  • Correct approach: The most stable approach is to call license renewal synchronously (Sync) when the app enters the foreground (active state) or immediately before playback.

Misuse the player start method​

Anti-pattern

Calling the startWithNewPlayerID() method to start the player without a clear scenario

  • Problem: startWithNewPlayerID() forcibly creates a new unique player ID (playerID). This can break the connection with other content that was previously downloaded using the old ID.
  • Correct approach: startWithNewPlayerID() should only be used in limited, clearly defined recovery scenarios such as device changes or ID loss. In general situations, it is safer to use start() or startWithCheck().

applicationBundleID configuration mismatch in Info.plist​

Anti-pattern

The value set in KollusStorage.applicationBundleID does not match the actual CFBundleIdentifier (Bundle ID) of the iOS app project

  • Problem: The authentication information does not match, causing failures during SDK authentication and initialization.
  • Correct approach: Always verify that the two identifier values match. If you need to change the Bundle ID, contact the Account Manager(biz@catenoid.net) or Technical Support(tech_support@catenoid.net) to request a new SDK key.

Mistake folder nodes for content when calling the storage.contents() API​

Anti-pattern

Treating a folder node that contains child elements in the storage.contents() mapping data as a single media content item

  • Problem: The provided sample app creates and displays virtual nodes in folder form via KollusContent(directory:). Attempting to handle these as regular files will return nil for mediaContentKey, which can cause a runtime error.
  • Correct approach: When constructing the list, check the data's attributes and implement branching logic so that items where fileType == 1 are recognized as 'folders', not media files.