Background Downloads

By default, downloads run in the application process and are not equivalent to Android system-managed background downloads. But, let’s also understand how to configure optional foreground-service support so long-running offline map downloads can continue when the application moves to the background.

To continue long-running transfers after the app enters the background, the host must implement DownloadForegroundHook and provide notification, Service, and Android-version compatibility logic.

Register the hook:

1
class App : Application() {
2
    override fun onCreate() {
3
        super.onCreate()
4
        // Nextbillion and RegionalOffline initialization omitted.
5
        RegionalOffline.setDownloadForegroundHook(AppDownloadForegroundHook)
6
    }
7
}
8
object AppDownloadForegroundHook : DownloadForegroundHook {
9
    override fun startForegroundService(context: Context) {
10
        RegionalDownloadService.start(context)
11
    }
12

13
    override fun stopForegroundService(context: Context) {
14
        RegionalDownloadService.stop(context)
15
    }
16

17
    override fun isForegroundEstablished(): Boolean =
18
        RegionalDownloadService.foregroundEstablished
19
}

At minimum, declare the following in the manifest:

1
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
2
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
3
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
4

5
<application ...>
6
    <service
7
        android:name=".RegionalDownloadService"
8
        android:exported="false"
9
        android:foregroundServiceType="dataSync" />
10
</application>

The hook's start/stop operations must be idempotent. isForegroundEstablished() must wait until the Service has successfully called Android startForeground() before returning true. The application must also handle notification permission, foreground Service start timing, and background-start restrictions for the target Android version.

If no hook is registered, transfers are interrupted when the system terminates the application process. Task records are restored the next time the application starts. Tasks that were in-progress, when interrupted, are normalized to a paused state, and the UI should prompt the user to call RESUME.