note

iOS: HLS/Fairplay Downloads feature is available from iOS 10.3+. Android: The Player library supports download of both clear and DRM protected contents.

Downloads

This document provides a comprehensive guide to managing downloads using the rn-qp-nxg-player library. It covers creating, pausing, resuming, and purging download tasks, as well as handling offline playback and monitoring download progress.

Service based Downloads

From RN bridge v7.1.70 onwards, Media3 based Service is recommended for better reliability of downloads.

Benefits of using Media3 Service based implementation:

• Download tasks are handled in a separate process, ensuring that downloads continue even if the main application is killed.
• System optimizations for foreground services are leveraged, improving download reliability and performance.

To enable download service application follow below steps.

1. Add FOREGROUND_SERVICE_DATA_SYNC permission(When your apps target Android 14 and above, you’ll need to declare for foreground service)

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

2. Add DownloadService.

<service android:name="com.quickplay.vstb7.player.offline.service.DownloadService"
    android:exported="false"
    android:foregroundServiceType="dataSync">
      <intent-filter>
        <action android:name="androidx.media3.exoplayer.downloadService.action.RESTART"/>
        <category android:name="android.intent.category.DEFAULT"/>
      </intent-filter>
</service>

note

When your apps target Android 14 and above, you’ll need to declare for foreground service types that you use in a declaration on the App content page (Monitor and improve > App content) in Play Console.

You also require to provide a video demonstrating foreground service feature. The video should demonstrate the steps the user needs to take in your app in order to trigger the feature.

To disable the download service, simply omit the above permissions and service declaration from your AndroidManifest.xml file.

Get All Download Tasks

Retrieve all the download tasks currently managed.

  import { Download, downloadManager } from '@quickplay/rn-qp-nxg-player';
  await downloadManager.isInitialized();
  let dowloads = await downloadManager.getAllDownloads();

Get Current downloading Tasks

Retrieve all tasks that are currently in progress.

  let dowloadingTask = await downloadManager.getAllDownloads();

Create Download Task

Create and enqueue a new download task.

  import { Download, downloadManager } from '@quickplay/rn-qp-nxg-player';
  let request: DownloadRequest = {
    ...
    mediaURL: contentAuthToken?.contentURL,
    mediaType: Platform.OS === 'android' ? 'DASH' : 'HLS',
    id: assets.id,
    expiration: contentAuthToken?.rentalExpiryTime,
    skd: contentAuthToken?.skd
};
  await downloadManager.enqueueDownload(request);

Downloading All Audio and Text Tracks

To download all available audio and text tracks for the content, set both allAudioTracks and allTextTracks to true in your download request. When these options are enabled, the preferredAudioVariants and preferredTextVariants fields will be ignored, and all tracks will be downloaded automatically.

import { Download, downloadManager } from '@quickplay/rn-qp-nxg-player';
let request: DownloadRequest = {
  ...
  allAudioTracks: true,
  allTextTracks: true,
};
await downloadManager.enqueueDownload(request);

Downloading Only Preferred Tracks

If you want to download only specific audio and text tracks, set allAudioTracks and allTextTracks to false and specify your desired tracks in the preferredAudioVariants and preferredTextVariants arrays:

import { Download, downloadManager } from '@quickplay/rn-qp-nxg-player';
let request: DownloadRequest = {
  ...
  preferredAudioVariants: [
    {
      ...
      languageCode: 'en', // two or three letter code
      displayName: 'English',
      type: 'AUDIO',
    }
  ],
  preferredTextVariants: [
    {
      languageCode: 'en', // two or three letter code
      displayName: 'English',
      type: 'TEXT',
    }
  ],
  allAudioTracks: false,
  allTextTracks: false,
};
await downloadManager.enqueueDownload(request);

Note: For most use cases, we recommend setting both allAudioTracks and allTextTracks to true to ensure all available tracks are downloaded.

Pause All Download Task

Pause all active download tasks.

await downloadManager.pauseDownloads()

Resume All Download Task

Resume all paused download tasks.

await downloadManager.resumeDownloads()

Resume, Pause & Purge

Use the following methods to manage specific download tasks:

await downloadManager.retryDownload(Download.id)
await downloadManager.pauseDownload(Download.id)
await downloadManager.resumeDownload(Download.id)
await downloadManager.purgeDownload(Download.id)

Download Progress

The download task progress can be tracked through DownloadProgressListener in DownloadListener

Offline Playback

To play a downloaded content

import { createPlayer, PlayerConfig } from '@quickplay/rn-qp-nxg-player';

let playerConfig: PlayerConfig = { 
    ...
    deliveryType: 'DOWNLOAD',
}

let player = await createPlayer(playerConfig)

Auto Purge on Expiry

To Automatically remove expired downloads without manual cleanup.

await downloadManager.setAutoPurgeOnExpiry(true);

The download task removal can be tracked through DownloadRemovalListener in DownloadListener.

Offline Playback Behavior at Expiration (Auto-Purge Enabled)

Android: Playback stops immediately upon expiration, resulting in either a Media Source Failure (Error Code: 400208) or a DRM Failure (Error Code: 400205).

iOS: Ongoing playback is unaffected. However, if the user seeks after expiration, playback will fail with Error Code: 400208.

Offline Playback Behavior at Expiration (Auto-Purge Disabled)

Android: playback stops immediately upon expiration, resulting in either a Media Source Failure (Error Code: 400208) or a DRM Failure (Error Code: 400205).

iOS: Ongoing playback is not interrupted. Expiration only affects future playback sessions, which will fail with Error Code: 400208.

DownloadListener

Use DownloadListener to monitor various download-related events:

const downloadListener: DownloadListener = {
  onDownloadProgress(download: Download) {
    // Track progress of the download task
  },
  onDownloadRemoved(download: Download) {
    // Track when a download task is removed
  },
  onDownloadStateChanged(download: Download) {
    // Track changes in the download task's state (e.g., paused, resumed)
  },
  onDownloadExpirationChanged(download: Download) {
    // Track expiration changes (useful for dual expiry support)
  },
  onDownloadFailed(download: Download) {
    // Track download failures
  },
};

// Register the listener
await downloadManager.addListener(downloadListener);

// Remove the listener when it's no longer needed
await downloadManager.removeListener(downloadListener);

Enable Dual Expiry

Enable dual expiry support during the download request.

  import { Download, downloadManager } from '@quickplay/rn-qp-nxg-player';
  let contentAuthToken = await contentAuthorizer.authorizePlayback(platformAsset);
  let request: DownloadRequest = {
    ...
  
    playbackExpiryDuration: contentAuthToken?.playbackExpiryDuration,
};
  await downloadManager.enqueueDownload(request);

Monitor the expiration property for changes through DownloadProgressListener callback in DownloadExpiryChanged