@zykeco/expo-background-task 1.0.0

package/.eslintrc.js

@@ -0,0 +1,2 @@
+// @generated by expo-module-scripts
+module.exports = require('expo-module-scripts/eslintrc.base.js');

package/CHANGELOG.md

@@ -0,0 +1,185 @@
+# Changelog
+
+## Unpublished
+
+### 🛠 Breaking changes
+
+### 🎉 New features
+
+### 🐛 Bug fixes
+
+### 💡 Others
+
+## 55.0.8 — 2026-02-25
+
+_This version does not introduce any user-facing changes._
+
+## 55.0.7 — 2026-02-20
+
+_This version does not introduce any user-facing changes._
+
+## 55.0.6 — 2026-02-16
+
+_This version does not introduce any user-facing changes._
+
+## 55.0.5 — 2026-02-08
+
+_This version does not introduce any user-facing changes._
+
+## 55.0.4 — 2026-02-03
+
+_This version does not introduce any user-facing changes._
+
+## 55.0.3 — 2026-01-27
+
+_This version does not introduce any user-facing changes._
+
+## 55.0.2 — 2026-01-26
+
+_This version does not introduce any user-facing changes._
+
+## 55.0.1 — 2026-01-22
+
+_This version does not introduce any user-facing changes._
+
+## 55.0.0 — 2026-01-21
+
+_This version does not introduce any user-facing changes._
+
+## 1.0.10 - 2025-12-05
+
+_This version does not introduce any user-facing changes._
+
+## 1.0.9 - 2025-11-17
+
+_This version does not introduce any user-facing changes._
+
+## 1.0.8 - 2025-09-18
+
+### 🎉 New features
+
+- [iOS] Added support for task expiration handler on iOS. ([#39773](https://github.com/expo/expo/pull/39773) by [@chrfalch](https://github.com/chrfalch))
+
+### 🐛 Bug fixes
+
+- [iOS] Fixed timing issue where background task iOS handler was not registered when we try to schedule a task. ([#39769](https://github.com/expo/expo/pull/39769) by [@chrfalch](https://github.com/chrfalch))
+
+## 1.0.7 — 2025-09-11
+
+_This version does not introduce any user-facing changes._
+
+## 1.0.6 — 2025-09-02
+
+_This version does not introduce any user-facing changes._
+
+## 1.0.5 — 2025-08-31
+
+_This version does not introduce any user-facing changes._
+
+## 1.0.4 — 2025-08-27
+
+_This version does not introduce any user-facing changes._
+
+## 1.0.3 — 2025-08-25
+
+_This version does not introduce any user-facing changes._
+
+## 1.0.2 — 2025-08-16
+
+_This version does not introduce any user-facing changes._
+
+## 1.0.1 — 2025-08-15
+
+_This version does not introduce any user-facing changes._
+
+## 1.0.0 — 2025-08-13
+
+### 🐛 Bug fixes
+
+- [iOS] Rethrow obj-c exception as swift error. ([#38714](https://github.com/expo/expo/pull/38714) by [@jakex7](https://github.com/jakex7))
+
+## 0.2.8 - 2025-07-01
+
+### 💡 Others
+
+- Remove "Please" from warnings and errors ([#36862](https://github.com/expo/expo/pull/36862) by [@brentvatne](https://github.com/brentvatne))
+
+## 0.2.7 — 2025-05-08
+
+### 💡 Others
+
+- Exposed testing method for background tasks on both iOS and Android ([#36732](https://github.com/expo/expo/pull/36732) by [@chrfalch](https://github.com/chrfalch))
+- Simplified how workers are started and stopped. Removed battery constraint on Android. ([#36705](https://github.com/expo/expo/pull/36705) by [@chrfalch](https://github.com/chrfalch))
+
+## 0.2.6 — 2025-04-30
+
+_This version does not introduce any user-facing changes._
+
+## 0.2.5 — 2025-04-25
+
+### 💡 Others
+
+- Removed throwing an exception if registerTaskAsync/unregisterTaskAsync is called on a task that is already registered/unregistered ([#36393](https://github.com/expo/expo/pull/36393) by [@chrfalch](https://github.com/chrfalch))
+
+## 0.2.4 — 2025-04-14
+
+_This version does not introduce any user-facing changes._
+
+## 0.2.3 — 2025-04-11
+
+### 💡 Others
+
+- Added warning about Background Tasks not being supported in Expo Go ([#36063](https://github.com/expo/expo/pull/36063) by [@chrfalch](https://github.com/chrfalch))
+
+## 0.2.2 — 2025-04-09
+
+_This version does not introduce any user-facing changes._
+
+## 0.2.1 — 2025-04-08
+
+### 🐛 Bug fixes
+
+- [android] added expo-background-task to Expo Go's configuration ([#36000](https://github.com/expo/expo/pull/36000) by [@chrfalch](https://github.com/chrfalch))
+
+## 0.2.0 — 2025-04-04
+
+_This version does not introduce any user-facing changes._
+
+## 0.1.4 - 2025-04-02
+
+### 🐛 Bug fixes
+
+- [Android] added proguard rules for background-task consumer ([#35816](https://github.com/expo/expo/pull/35816) by [@chrfalch](https://github.com/chrfalch))
+
+### 💡 Others
+
+- added error handling when registering/unregistering invalid tasks with the TaskManager. ([#35734](https://github.com/expo/expo/pull/35734) by [@chrfalch](https://github.com/chrfalch))
+
+## 0.1.3 - 2025-03-14
+
+### 💡 Others
+
+- added throwing an exception if registerTask is run on an iOS Simulator or a device without background modes enabled ([#35350](https://github.com/expo/expo/pull/35350) by [@chrfalch](https://github.com/chrfalch))
+- [apple] Migrate remaining `expo-module.config.json` to unified platform syntax. ([#34445](https://github.com/expo/expo/pull/34445) by [@reichhartd](https://github.com/reichhartd))
+
+## 0.1.2 - 2025-02-14
+
+_This version does not introduce any user-facing changes._
+
+## 0.1.1 - 2025-01-31
+
+### 💡 Others
+
+- [Android] Started using expo modules gradle plugin. ([#34431](https://github.com/expo/expo/pull/34431) by [@chrfalch](https://github.com/chrfalch))
+
+## 0.0.1 — 2025-01-21
+
+### 💡 Others
+
+- Update README description
+
+## 0.0.0 — 2025-01-21
+
+### 🎉 New features
+
+- Added expo-background-task package ([#33438](https://github.com/expo/expo/pull/33438) by [@chrfalch](https://github.com/chrfalch))

package/README.md

@@ -0,0 +1,115 @@
+# expo-background-task
+
+Expo Android and iOS module for Background Task APIs
+
+# API documentation
+
+- [Documentation for the latest stable release](https://docs.expo.dev/versions/latest/sdk/background-task/)
+- [Documentation for the main branch](https://docs.expo.dev/versions/unversioned/sdk/background-task/)
+
+# Installation in managed Expo projects
+
+For [managed](https://docs.expo.dev/archive/managed-vs-bare/) Expo projects, please follow the installation instructions in the [API documentation for the latest stable release](https://docs.expo.dev/versions/latest/sdk/background-task/).
+
+# Installation in bare React Native projects
+
+For bare React Native projects, you must ensure that you have [installed and configured the `expo` package](https://docs.expo.dev/bare/installing-expo-modules/) before continuing.
+
+### Add the package to your npm dependencies
+
+```
+npx expo install expo-background-task
+```
+
+### Configure for Android
+
+No additional set up necessary.
+
+### Configure for iOS
+
+Run `npx pod-install` after installing the npm package.
+
+In order to use `BackgroundTask` API in standalone, detached and bare apps on iOS, your app has to include the background task identifier in the `Info.plist` file. You can do this by adding the following XML snippet to your `Info.plist` file:
+
+```xml
+<key>BGTaskSchedulerPermittedIdentifiers</key>
+<array>
+  <string>com.expo.modules.backgroundtask.processing</string>
+</array>
+```
+
+# iOS Task Types
+
+On iOS, background tasks are powered by Apple's BGTaskScheduler framework, which offers two distinct task types. You can choose between them using the `iosTaskType` option.
+
+## `'refresh'` (default)
+
+Uses `BGAppRefreshTaskRequest`. This is the recommended choice for most apps.
+
+```ts
+await BackgroundTask.registerTaskAsync('myTask', {
+  minimumInterval: 15, // minutes
+  // iosTaskType: 'refresh', — this is the default, no need to specify
+});
+```
+
+**When to use:**
+- Periodic content syncs (e.g. fetching new messages, updating a feed)
+- Lightweight data updates that complete quickly
+- Any task that should run frequently in the background
+
+**Characteristics:**
+- Aggressive scheduling — iOS typically runs these every ~15–30 minutes when conditions allow
+- ~30 second execution limit
+- Only supports `earliestBeginDate` (via `minimumInterval`) — no network/power constraints
+- Requires `fetch` in `UIBackgroundModes` (added automatically by the config plugin)
+
+## `'processing'`
+
+Uses `BGProcessingTaskRequest`. Use this for heavy, deferrable work.
+
+```ts
+await BackgroundTask.registerTaskAsync('heavyTask', {
+  minimumInterval: 60,
+  iosTaskType: 'processing',
+  requiresNetworkConnectivity: true,
+  requiresExternalPower: false,
+});
+```
+
+**When to use:**
+- Large database migrations or cleanup
+- ML model training or inference
+- Bulk data sync or media processing
+- Any work that takes more than 30 seconds and can be deferred
+
+**Characteristics:**
+- iOS defers execution at its own discretion (hours to days)
+- Several minutes of execution time allowed
+- Supports `requiresNetworkConnectivity` and `requiresExternalPower` constraints
+- Requires `processing` in `UIBackgroundModes` (added automatically by the config plugin)
+
+## Quick comparison
+
+| | `'refresh'` | `'processing'` |
+|---|---|---|
+| **Scheduling** | Aggressive (~15–30 min) | Deferred (hours/days) |
+| **Execution limit** | ~30 seconds | Several minutes |
+| **Best for** | Periodic syncs, content updates | Heavy work, migrations, ML |
+| **Network constraint** | Not supported | Supported |
+| **External power constraint** | Not supported | Supported |
+
+## Additional options
+
+| Option | Platforms | Default | Description |
+|---|---|---|---|
+| `minimumInterval` | iOS, Android | 720 (12h) | Minimum interval in minutes between task executions |
+| `iosTaskType` | iOS only | `'refresh'` | Which BGTask type to use |
+| `requiresNetworkConnectivity` | iOS, Android | `true` | Whether the task needs network access |
+| `requiresExternalPower` | iOS only | `false` | Whether the task needs external power (only for `'processing'`) |
+
+> **Note:** On Android, `iosTaskType` is ignored. Android uses WorkManager for all background work, which handles scheduling uniformly regardless of task complexity. The `requiresNetworkConnectivity` option does work on Android and controls the WorkManager network constraint.
+
+# Contributing
+
+Contributions are very welcome! Please refer to guidelines described in the [contributing guide](https://github.com/expo/expo#contributing).

package/android/build.gradle

@@ -0,0 +1,21 @@
+plugins {
+  id 'com.android.library'
+  id 'expo-module-gradle-plugin'
+}
+
+group = 'host.exp.exponent'
+version = '55.0.8'
+
+android {
+  namespace "expo.modules.backgroundtask"
+  defaultConfig {
+    versionCode 23
+    versionName "55.0.8"
+    consumerProguardFiles("proguard-rules.pro")
+  }
+}
+
+dependencies {
+  implementation 'androidx.work:work-runtime-ktx:2.9.1'
+  implementation 'com.facebook.react:react-android'
+}

package/android/proguard-rules.pro

@@ -0,0 +1 @@
+-keep class expo.modules.backgroundtask.** { *; }

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/java/expo/modules/backgroundtask/BackgroundTaskConsumer.kt

@@ -0,0 +1,60 @@
+package expo.modules.backgroundtask
+
+import android.content.Context
+import android.util.Log
+import expo.modules.interfaces.taskManager.TaskConsumer
+import expo.modules.interfaces.taskManager.TaskConsumerInterface
+import expo.modules.interfaces.taskManager.TaskExecutionCallback
+import expo.modules.interfaces.taskManager.TaskInterface
+import expo.modules.interfaces.taskManager.TaskManagerUtilsInterface
+
+class BackgroundTaskConsumer(context: Context?, taskManagerUtils: TaskManagerUtilsInterface?) :
+  TaskConsumer(context, taskManagerUtils), TaskConsumerInterface {
+
+  companion object {
+    private const val BACKGROUND_TASK_TYPE = "expo-background-task"
+    private val TAG = BackgroundTaskConsumer::class.java.simpleName
+  }
+
+  private var task: TaskInterface? = null
+
+  override fun taskType(): String {
+    return BACKGROUND_TASK_TYPE
+  }
+
+  /**
+   * Exposing the execute task function so that the BackgroundTaskWork (WorkManager Work unit)
+   * can execute the inner task. A task is only executed if the app is in the background.
+   * This only applies when the app is in release mode.
+   */
+  fun executeTask(callback: TaskExecutionCallback) {
+    Log.d(TAG, "Executing task '${task?.name}'")
+    taskManagerUtils.executeTask(task, null, callback)
+  }
+
+  override fun didRegister(task: TaskInterface) {
+    Log.d(TAG, "didRegister: ${task.name}")
+    this.task = task
+
+    val intervalMinutes = getIntervalMinutes()
+    val requiresNetwork = getRequiresNetwork()
+    BackgroundTaskScheduler.registerTask(context, intervalMinutes, requiresNetwork)
+  }
+
+  override fun didUnregister() {
+    Log.d(TAG, "didUnregister: ${task?.name}")
+    this.task = null
+    BackgroundTaskScheduler.unregisterTask(context)
+  }
+
+  private fun getIntervalMinutes(): Long {
+    val options = task?.options as? Map<String, Any?>
+    return (options?.get("minimumInterval") as? Number)?.toLong()
+      ?: BackgroundTaskScheduler.DEFAULT_INTERVAL_MINUTES
+  }
+
+  private fun getRequiresNetwork(): Boolean? {
+    val options = task?.options as? Map<String, Any?>
+    return options?.get("requiresNetworkConnectivity") as? Boolean
+  }
+}

package/android/src/main/java/expo/modules/backgroundtask/BackgroundTaskExceptions.kt

@@ -0,0 +1,13 @@
+package expo.modules.backgroundtask
+
+import expo.modules.kotlin.exception.CodedException
+
+internal class MissingContextException : CodedException(message = "Application context not found")
+
+internal class MissingTaskServiceException : CodedException(message = "TaskService not available.")
+
+internal class MissingAppScopeKey : CodedException(message = "Could not find required appScopeKey in worker.")
+
+internal class TaskMangerInterfaceNotFoundException : CodedException(message = "TaskManagerInterface not found")
+
+internal class TestMethodNotAvailableInProductionBuild : CodedException(message = "Background tasks cannot be triggered in production builds")

package/android/src/main/java/expo/modules/backgroundtask/BackgroundTaskModule.kt

@@ -0,0 +1,56 @@
+package expo.modules.backgroundtask
+
+import android.util.Log
+import com.facebook.react.common.build.ReactBuildConfig
+import expo.modules.interfaces.taskManager.TaskManagerInterface
+import expo.modules.kotlin.functions.Coroutine
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+class BackgroundTaskModule : Module() {
+  companion object {
+    private val TAG = BackgroundTaskModule::class.java.simpleName
+  }
+
+  private val _taskManager by lazy { appContext.legacyModule<TaskManagerInterface>() }
+  private val taskManager: TaskManagerInterface
+    get() = _taskManager ?: throw TaskMangerInterfaceNotFoundException()
+
+  override fun definition() = ModuleDefinition {
+    Name("ExpoBackgroundTask")
+
+    AsyncFunction("getStatusAsync") {
+      return@AsyncFunction 2 // WorkManager is always available on Android.
+    }
+
+    AsyncFunction("triggerTaskWorkerForTestingAsync") Coroutine { ->
+      if (ReactBuildConfig.DEBUG) {
+        Log.d(TAG, "Triggering tasks for testing")
+        appContext.reactContext?.let {
+          val appScopeKey = it.packageName
+          return@Coroutine BackgroundTaskScheduler.runTasks(it, appScopeKey)
+        } ?: throw MissingContextException()
+      } else {
+        throw TestMethodNotAvailableInProductionBuild()
+      }
+    }
+
+    AsyncFunction("registerTaskAsync") { taskName: String, options: Map<String, Any?> ->
+      Log.d(TAG, "registerTaskAsync: $taskName with options $options")
+      taskManager.registerTask(taskName, BackgroundTaskConsumer::class.java, options)
+    }
+
+    AsyncFunction("unregisterTaskAsync") { taskName: String ->
+      Log.d(TAG, "unregisterTaskAsync: $taskName")
+      taskManager.unregisterTask(taskName, BackgroundTaskConsumer::class.java)
+    }
+
+    OnActivityEntersForeground {
+      BackgroundTaskScheduler.inForeground = true
+    }
+
+    OnActivityEntersBackground {
+      BackgroundTaskScheduler.inForeground = false
+    }
+  }
+}