Downloading as a service

This enables downloads to exist outside of an activity and is a more robust way to handle potentially long-running downloads. This page assumes some knowledge of Android services; see https://developer.android.com/guide/components/services.

Permissions

For Android 9 (API 28) upwards, the app should request the FOREGROUND_SERVICE , as well as POST_NOTIFICATIONS and WRITE_EXTERNAL_STORAGE permissions for Android 13 (API 33) in the manifest:

XML

<manifest>    
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <application>
    <!--...-->
    </application>
</manifest>

Managing downloads

The OTVDownloadManager class handles threading, so the service needs to manage a reference to the OTVDownloadManager instance and relay intents to it, as well as provide notifications on download state.

The OTVDownloadManager only needs to be instantiated once and shared over an application and service lifecycle. The example code shows a way to allow access to a single download manager by sub-classing the Android application class and providing a getter.

JAVA

public class DemoApplication extends Application {
  private OTVDownloadManager mDownloadManager;

  /**
   * @return An application wide download manager instance.
   */
  public OTVDownloadManager getDownloadManager() {
    if (mDownloadManager == null) {
      mDownloadManager = new OTVDownloadManager(this);
    }
    return  mDownloadManager;
  }
  
  //...
}

The download manager will be linked to the application lifecycle, but the service may persist beyond that. To keep the download manager accessible, the service has to run in the foreground; see https://developer.android.com/guide/components/services#StartingAService.

Notifications

You will need to provide actionable notifications to allow users to interact with the downloads without a foreground application. The example code demonstrates how to provide persistent notifications with an attached cancel action to stop downloads while they are in progress.

From Android 8 (API 26), all notifications must be attached to an explicit channel; see https://developer.android.com/training/notify-user/channels.