expo-notifications 0.29.5 → 0.29.7

package/CHANGELOG.md

@@ -10,6 +10,17 @@
 
 ### 💡 Others
 
+## 0.29.7 — 2024-11-13
+
+_This version does not introduce any user-facing changes._
+
+## 0.29.6 — 2024-11-10
+
+### 🎉 New features
+
+- [android] run notification tasks from killed state ([#32531](https://github.com/expo/expo/pull/32531) by [@vonovak](https://github.com/vonovak))
+- add `enableBackgroundRemoteNotifications` option to config plugin ([#32716](https://github.com/expo/expo/pull/32716) by [@vonovak](https://github.com/vonovak))
+
 ## 0.29.5 — 2024-11-07
 
 ### 🛠 Breaking changes

package/android/build.gradle

@@ -2,7 +2,7 @@ apply plugin: 'com.android.library'
 apply plugin: 'kotlin-parcelize'
 
 group = 'host.exp.exponent'
-version = '0.29.5'
+version = '0.29.7'
 
 def expoModulesCorePlugin = new File(project(":expo-modules-core").projectDir.absolutePath, "ExpoModulesCorePlugin.gradle")
 apply from: expoModulesCorePlugin
@@ -15,7 +15,7 @@ android {
   namespace "expo.modules.notifications"
   defaultConfig {
     versionCode 21
-    versionName '0.29.5'
+    versionName '0.29.7'
     testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
   }
 

package/android/src/main/java/expo/modules/notifications/notifications/RemoteMessageSerializer.java

@@ -6,6 +6,7 @@ import com.google.firebase.messaging.RemoteMessage;
 
 import java.util.Map;
 
+import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
 
 /**
@@ -19,7 +20,7 @@ public class RemoteMessageSerializer {
    * @param message {@link RemoteMessage} to serialize
    * @return Serialized message
    */
-  public static Bundle toBundle(RemoteMessage message) {
+  public static @NonNull Bundle toBundle(RemoteMessage message) {
     Bundle serializedMessage = new Bundle();
     serializedMessage.putString("collapseKey", message.getCollapseKey());
     serializedMessage.putBundle("data", toBundle(message.getData()));

package/android/src/main/java/expo/modules/notifications/notifications/background/BackgroundRemoteNotificationTaskConsumer.java

@@ -6,6 +6,7 @@ import android.content.Context;
 import android.os.Bundle;
 import android.os.PersistableBundle;
 import android.util.Log;
+import androidx.annotation.NonNull;
 
 import org.json.JSONException;
 import org.json.JSONObject;
@@ -120,5 +121,9 @@ public class BackgroundRemoteNotificationTaskConsumer extends TaskConsumer imple
     return bundle;
   }
 
+  public void executeTask(@NonNull Bundle bundle) {
+    mTask.execute(bundle, null);
+  }
+
   //endregion
 }

package/android/src/main/java/expo/modules/notifications/service/delegates/ExpoHandlingDelegate.kt

@@ -45,7 +45,7 @@ class ExpoHandlingDelegate(protected val context: Context) : HandlingDelegate {
       }
 
       sListenersReferences[listener] = WeakReference(listener)
-      if (!sPendingNotificationResponses.isEmpty()) {
+      if (sPendingNotificationResponses.isNotEmpty()) {
         val responseIterator = sPendingNotificationResponses.iterator()
         while (responseIterator.hasNext()) {
           listener.onNotificationResponseReceived(responseIterator.next())
@@ -139,11 +139,11 @@ class ExpoHandlingDelegate(protected val context: Context) : HandlingDelegate {
     if (notificationResponse.action.opensAppToForeground()) {
       openAppToForeground(context, notificationResponse)
     }
-
-    if (getListeners().isEmpty()) {
+    val listeners = getListeners()
+    if (listeners.isEmpty()) {
       sPendingNotificationResponses.add(notificationResponse)
     } else {
-      getListeners().forEach {
+      listeners.forEach {
         it.onNotificationResponseReceived(notificationResponse)
       }
     }

package/android/src/main/java/expo/modules/notifications/service/delegates/FirebaseMessagingDelegate.kt

@@ -2,6 +2,7 @@ package expo.modules.notifications.service.delegates
 
 import android.content.Context
 import com.google.firebase.messaging.RemoteMessage
+import expo.modules.interfaces.taskManager.TaskServiceProviderHelper
 import expo.modules.notifications.notifications.RemoteMessageSerializer
 import expo.modules.notifications.notifications.background.BackgroundRemoteNotificationTaskConsumer
 import expo.modules.notifications.notifications.debug.DebugLogging
@@ -94,9 +95,16 @@ open class FirebaseMessagingDelegate(protected val context: Context) : FirebaseM
     val notification = createNotification(remoteMessage)
     DebugLogging.logNotification("FirebaseMessagingDelegate.onMessageReceived: notification", notification)
     NotificationsService.receive(context, notification)
-    // background tasks are separate from the main notification handling flow; they are executed through task-manager
+    runTaskManagerTasks(remoteMessage)
+  }
+
+  private fun runTaskManagerTasks(remoteMessage: RemoteMessage) {
+    // getTaskServiceImpl() has a side effect:
+    // the TaskService constructor calls restoreTasks which then constructs a BackgroundRemoteNotificationTaskConsumer,
+    // and the getBackgroundTasks() call below doesn't return an empty collection.
+    TaskServiceProviderHelper.getTaskServiceImpl(context.applicationContext)
     getBackgroundTasks().forEach {
-      it.scheduleJob(RemoteMessageSerializer.toBundle(remoteMessage))
+      it.executeTask(RemoteMessageSerializer.toBundle(remoteMessage))
     }
   }
 

package/build/registerTaskAsync.d.ts

@@ -1,9 +1,14 @@
 /**
- * When a notification is received while the app is backgrounded, using this function you can set a callback that will be run in response to that notification.
- * Under the hood, this function is run using `expo-task-manager`. You **must** define the task first, with [`TaskManager.defineTask`](./task-manager#taskmanagerdefinetasktaskname-taskexecutor).
- * Make sure you define it in the global scope. It is recommended to define only one task because running a task can have a high cost.
+ * Call `registerTaskAsync` to set a callback (task) that will run in response to when a notification is received while the app is in foreground, background, or terminated.
+ * When app is terminated, only a [data message](https://firebase.google.com/docs/cloud-messaging/concept-options#data_messages) (Android) / [background notification](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app#Create-a-background-notification) (iOS) triggers the task execution.
+ * However, the OS may decide not to deliver the notification to your app in some cases (e.g. when the device is in Doze mode on Android, or when you send too many notifications - Apple recommends to not ["send more than two or three per hour"](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app#overview)).
  *
- * The callback function you define with `TaskManager.defineTask` will receive an object with the following fields:
+ * Under the hood, this function is run using `expo-task-manager`. You **must** define the task first, with [`TaskManager.defineTask`](./task-manager#taskmanagerdefinetasktaskname-taskexecutor) and register it with `registerTaskAsync`.
+ *
+ * Make sure you define and register the task in the module scope of a JS module which is required early by your app (e.g. in the `index.js` file).
+ * `expo-task-manager` loads your app's JS bundle in the background and executes the task, as well as any side effects which may happen as a consequence of requiring any JS modules.
+ *
+ * The callback function you define with `TaskManager.defineTask` receives an object with the following fields:
  * - `data`: The remote payload delivered by either FCM (Android) or APNs (iOS). See [`PushNotificationTrigger`](#pushnotificationtrigger) for details.
  * - `error`: The error (if any) that occurred during execution of the task.
  * - `executionInfo`: JSON object of additional info related to the task, including the `taskName`.

package/build/registerTaskAsync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registerTaskAsync.d.ts","sourceRoot":"","sources":["../src/registerTaskAsync.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAA8B,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAM/E"}
+{"version":3,"file":"registerTaskAsync.d.ts","sourceRoot":"","sources":["../src/registerTaskAsync.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAA8B,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAM/E"}

package/build/registerTaskAsync.js

@@ -1,11 +1,16 @@
 import { UnavailabilityError } from 'expo-modules-core';
 import BackgroundNotificationTasksModule from './BackgroundNotificationTasksModule';
 /**
- * When a notification is received while the app is backgrounded, using this function you can set a callback that will be run in response to that notification.
- * Under the hood, this function is run using `expo-task-manager`. You **must** define the task first, with [`TaskManager.defineTask`](./task-manager#taskmanagerdefinetasktaskname-taskexecutor).
- * Make sure you define it in the global scope. It is recommended to define only one task because running a task can have a high cost.
+ * Call `registerTaskAsync` to set a callback (task) that will run in response to when a notification is received while the app is in foreground, background, or terminated.
+ * When app is terminated, only a [data message](https://firebase.google.com/docs/cloud-messaging/concept-options#data_messages) (Android) / [background notification](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app#Create-a-background-notification) (iOS) triggers the task execution.
+ * However, the OS may decide not to deliver the notification to your app in some cases (e.g. when the device is in Doze mode on Android, or when you send too many notifications - Apple recommends to not ["send more than two or three per hour"](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app#overview)).
  *
- * The callback function you define with `TaskManager.defineTask` will receive an object with the following fields:
+ * Under the hood, this function is run using `expo-task-manager`. You **must** define the task first, with [`TaskManager.defineTask`](./task-manager#taskmanagerdefinetasktaskname-taskexecutor) and register it with `registerTaskAsync`.
+ *
+ * Make sure you define and register the task in the module scope of a JS module which is required early by your app (e.g. in the `index.js` file).
+ * `expo-task-manager` loads your app's JS bundle in the background and executes the task, as well as any side effects which may happen as a consequence of requiring any JS modules.
+ *
+ * The callback function you define with `TaskManager.defineTask` receives an object with the following fields:
  * - `data`: The remote payload delivered by either FCM (Android) or APNs (iOS). See [`PushNotificationTrigger`](#pushnotificationtrigger) for details.
  * - `error`: The error (if any) that occurred during execution of the task.
  * - `executionInfo`: JSON object of additional info related to the task, including the `taskName`.

package/build/registerTaskAsync.js.map

@@ -1 +1 @@
-{"version":3,"file":"registerTaskAsync.js","sourceRoot":"","sources":["../src/registerTaskAsync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAExD,OAAO,iCAAiC,MAAM,qCAAqC,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,OAAO,CAAC,KAAK,UAAU,iBAAiB,CAAC,QAAgB;IAC9D,IAAI,CAAC,iCAAiC,CAAC,iBAAiB,EAAE;QACxD,MAAM,IAAI,mBAAmB,CAAC,eAAe,EAAE,mBAAmB,CAAC,CAAC;KACrE;IAED,OAAO,MAAM,iCAAiC,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC;AAC7E,CAAC","sourcesContent":["import { UnavailabilityError } from 'expo-modules-core';\n\nimport BackgroundNotificationTasksModule from './BackgroundNotificationTasksModule';\n\n/**\n * When a notification is received while the app is backgrounded, using this function you can set a callback that will be run in response to that notification.\n * Under the hood, this function is run using `expo-task-manager`. You **must** define the task first, with [`TaskManager.defineTask`](./task-manager#taskmanagerdefinetasktaskname-taskexecutor).\n * Make sure you define it in the global scope. It is recommended to define only one task because running a task can have a high cost.\n *\n * The callback function you define with `TaskManager.defineTask` will receive an object with the following fields:\n * - `data`: The remote payload delivered by either FCM (Android) or APNs (iOS). See [`PushNotificationTrigger`](#pushnotificationtrigger) for details.\n * - `error`: The error (if any) that occurred during execution of the task.\n * - `executionInfo`: JSON object of additional info related to the task, including the `taskName`.\n * @param taskName The string you passed to `TaskManager.defineTask` as the `taskName` parameter.\n *\n * @example\n * ```ts\n * import * as TaskManager from 'expo-task-manager';\n * import * as Notifications from 'expo-notifications';\n *\n * const BACKGROUND_NOTIFICATION_TASK = 'BACKGROUND-NOTIFICATION-TASK';\n *\n * TaskManager.defineTask(BACKGROUND_NOTIFICATION_TASK, ({ data, error, executionInfo }) => {\n *   console.log('Received a notification in the background!');\n *   // Do something with the notification data\n * });\n *\n * Notifications.registerTaskAsync(BACKGROUND_NOTIFICATION_TASK);\n * ```\n * @header inBackground\n */\nexport default async function registerTaskAsync(taskName: string): Promise<null> {\n  if (!BackgroundNotificationTasksModule.registerTaskAsync) {\n    throw new UnavailabilityError('Notifications', 'registerTaskAsync');\n  }\n\n  return await BackgroundNotificationTasksModule.registerTaskAsync(taskName);\n}\n"]}
+{"version":3,"file":"registerTaskAsync.js","sourceRoot":"","sources":["../src/registerTaskAsync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAExD,OAAO,iCAAiC,MAAM,qCAAqC,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAC,OAAO,CAAC,KAAK,UAAU,iBAAiB,CAAC,QAAgB;IAC9D,IAAI,CAAC,iCAAiC,CAAC,iBAAiB,EAAE;QACxD,MAAM,IAAI,mBAAmB,CAAC,eAAe,EAAE,mBAAmB,CAAC,CAAC;KACrE;IAED,OAAO,MAAM,iCAAiC,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC;AAC7E,CAAC","sourcesContent":["import { UnavailabilityError } from 'expo-modules-core';\n\nimport BackgroundNotificationTasksModule from './BackgroundNotificationTasksModule';\n\n/**\n * Call `registerTaskAsync` to set a callback (task) that will run in response to when a notification is received while the app is in foreground, background, or terminated.\n * When app is terminated, only a [data message](https://firebase.google.com/docs/cloud-messaging/concept-options#data_messages) (Android) / [background notification](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app#Create-a-background-notification) (iOS) triggers the task execution.\n * However, the OS may decide not to deliver the notification to your app in some cases (e.g. when the device is in Doze mode on Android, or when you send too many notifications - Apple recommends to not [\"send more than two or three per hour\"](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app#overview)).\n *\n * Under the hood, this function is run using `expo-task-manager`. You **must** define the task first, with [`TaskManager.defineTask`](./task-manager#taskmanagerdefinetasktaskname-taskexecutor) and register it with `registerTaskAsync`.\n *\n * Make sure you define and register the task in the module scope of a JS module which is required early by your app (e.g. in the `index.js` file).\n * `expo-task-manager` loads your app's JS bundle in the background and executes the task, as well as any side effects which may happen as a consequence of requiring any JS modules.\n *\n * The callback function you define with `TaskManager.defineTask` receives an object with the following fields:\n * - `data`: The remote payload delivered by either FCM (Android) or APNs (iOS). See [`PushNotificationTrigger`](#pushnotificationtrigger) for details.\n * - `error`: The error (if any) that occurred during execution of the task.\n * - `executionInfo`: JSON object of additional info related to the task, including the `taskName`.\n * @param taskName The string you passed to `TaskManager.defineTask` as the `taskName` parameter.\n *\n * @example\n * ```ts\n * import * as TaskManager from 'expo-task-manager';\n * import * as Notifications from 'expo-notifications';\n *\n * const BACKGROUND_NOTIFICATION_TASK = 'BACKGROUND-NOTIFICATION-TASK';\n *\n * TaskManager.defineTask(BACKGROUND_NOTIFICATION_TASK, ({ data, error, executionInfo }) => {\n *   console.log('Received a notification in the background!');\n *   // Do something with the notification data\n * });\n *\n * Notifications.registerTaskAsync(BACKGROUND_NOTIFICATION_TASK);\n * ```\n * @header inBackground\n */\nexport default async function registerTaskAsync(taskName: string): Promise<null> {\n  if (!BackgroundNotificationTasksModule.registerTaskAsync) {\n    throw new UnavailabilityError('Notifications', 'registerTaskAsync');\n  }\n\n  return await BackgroundNotificationTasksModule.registerTaskAsync(taskName);\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-notifications",
-  "version": "0.29.5",
+  "version": "0.29.7",
   "description": "Provides an API to fetch push notification tokens and to present, schedule, receive, and respond to notifications.",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -55,5 +55,5 @@
     "react": "*",
     "react-native": "*"
   },
-  "gitHead": "c0899e56c5be08b0142f06f05aa7bac8d6bc18b8"
+  "gitHead": "2c50bd7f0abaefb6fabcfd6d3935066724990b33"
 }

package/plugin/build/withNotifications.d.ts

@@ -28,6 +28,14 @@ export type NotificationsPluginProps = {
      * @platform ios
      */
     mode?: 'development' | 'production';
+    /**
+     * Whether to enable background remote notifications, as described in [Apple documentation](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app).
+     *
+     * This sets the `UIBackgroundModes` key in the `Info.plist` to include `remote-notification`.
+     * @default false
+     * @platform ios
+     */
+    enableBackgroundRemoteNotifications?: boolean;
 };
 declare const _default: ConfigPlugin<void | NotificationsPluginProps>;
 export default _default;

package/plugin/build/withNotificationsIOS.d.ts

@@ -1,9 +1,6 @@
 import { ConfigPlugin, XcodeProject } from 'expo/config-plugins';
 import { NotificationsPluginProps } from './withNotifications';
 export declare const withNotificationsIOS: ConfigPlugin<NotificationsPluginProps>;
-export declare const withNotificationSounds: ConfigPlugin<{
-    sounds: string[];
-}>;
 /**
  * Save sound files to the Xcode project root and add them to the Xcode project.
  */

package/plugin/build/withNotificationsIOS.js

@@ -1,21 +1,42 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.setNotificationSounds = exports.withNotificationSounds = exports.withNotificationsIOS = void 0;
+exports.setNotificationSounds = exports.withNotificationsIOS = void 0;
 const config_plugins_1 = require("expo/config-plugins");
 const fs_1 = require("fs");
 const path_1 = require("path");
 const ERROR_MSG_PREFIX = 'An error occurred while configuring iOS notifications. ';
-const withNotificationsIOS = (config, { mode = 'development', sounds = [] }) => {
+const withNotificationsIOS = (config, { mode = 'development', sounds = [], enableBackgroundRemoteNotifications }) => {
     config = (0, config_plugins_1.withEntitlementsPlist)(config, (config) => {
         if (!config.modResults['aps-environment']) {
             config.modResults['aps-environment'] = mode;
         }
         return config;
     });
-    config = (0, exports.withNotificationSounds)(config, { sounds });
+    config = withNotificationSounds(config, { sounds });
+    config = withBackgroundRemoteNotifications(config, enableBackgroundRemoteNotifications);
     return config;
 };
 exports.withNotificationsIOS = withNotificationsIOS;
+const withBackgroundRemoteNotifications = (config, enableBackgroundRemoteNotifications) => {
+    if (!(enableBackgroundRemoteNotifications === undefined ||
+        typeof enableBackgroundRemoteNotifications === 'boolean')) {
+        throw new Error(ERROR_MSG_PREFIX +
+            `"enableBackgroundRemoteNotifications" has an invalid value: ${enableBackgroundRemoteNotifications}. Expected a boolean.`);
+    }
+    if (!enableBackgroundRemoteNotifications) {
+        return config;
+    }
+    return (0, config_plugins_1.withInfoPlist)(config, (config) => {
+        if (!Array.isArray(config.modResults.UIBackgroundModes)) {
+            config.modResults.UIBackgroundModes = [];
+        }
+        const notificationBackgroundMode = 'remote-notification';
+        if (!config.modResults.UIBackgroundModes.includes(notificationBackgroundMode)) {
+            config.modResults.UIBackgroundModes.push(notificationBackgroundMode);
+        }
+        return config;
+    });
+};
 const withNotificationSounds = (config, { sounds }) => {
     return (0, config_plugins_1.withXcodeProject)(config, (config) => {
         setNotificationSounds(config.modRequest.projectRoot, {
@@ -26,7 +47,6 @@ const withNotificationSounds = (config, { sounds }) => {
         return config;
     });
 };
-exports.withNotificationSounds = withNotificationSounds;
 /**
  * Save sound files to the Xcode project root and add them to the Xcode project.
  */

package/plugin/src/withNotifications.ts

@@ -34,6 +34,15 @@ export type NotificationsPluginProps = {
    * @platform ios
    */
   mode?: 'development' | 'production';
+
+  /**
+   * Whether to enable background remote notifications, as described in [Apple documentation](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app).
+   *
+   * This sets the `UIBackgroundModes` key in the `Info.plist` to include `remote-notification`.
+   * @default false
+   * @platform ios
+   */
+  enableBackgroundRemoteNotifications?: boolean;
 };
 
 const withNotifications: ConfigPlugin<NotificationsPluginProps | void> = (config, props) => {

package/plugin/src/withNotificationsIOS.ts

@@ -4,6 +4,7 @@ import {
   IOSConfig,
   withXcodeProject,
   XcodeProject,
+  withInfoPlist,
 } from 'expo/config-plugins';
 import { copyFileSync } from 'fs';
 import { basename, resolve } from 'path';
@@ -14,7 +15,7 @@ const ERROR_MSG_PREFIX = 'An error occurred while configuring iOS notifications.
 
 export const withNotificationsIOS: ConfigPlugin<NotificationsPluginProps> = (
   config,
-  { mode = 'development', sounds = [] }
+  { mode = 'development', sounds = [], enableBackgroundRemoteNotifications }
 ) => {
   config = withEntitlementsPlist(config, (config) => {
     if (!config.modResults['aps-environment']) {
@@ -23,10 +24,42 @@ export const withNotificationsIOS: ConfigPlugin<NotificationsPluginProps> = (
     return config;
   });
   config = withNotificationSounds(config, { sounds });
+  config = withBackgroundRemoteNotifications(config, enableBackgroundRemoteNotifications);
+
   return config;
 };
 
-export const withNotificationSounds: ConfigPlugin<{ sounds: string[] }> = (config, { sounds }) => {
+const withBackgroundRemoteNotifications: ConfigPlugin<boolean | undefined> = (
+  config,
+  enableBackgroundRemoteNotifications
+) => {
+  if (
+    !(
+      enableBackgroundRemoteNotifications === undefined ||
+      typeof enableBackgroundRemoteNotifications === 'boolean'
+    )
+  ) {
+    throw new Error(
+      ERROR_MSG_PREFIX +
+        `"enableBackgroundRemoteNotifications" has an invalid value: ${enableBackgroundRemoteNotifications}. Expected a boolean.`
+    );
+  }
+  if (!enableBackgroundRemoteNotifications) {
+    return config;
+  }
+  return withInfoPlist(config, (config) => {
+    if (!Array.isArray(config.modResults.UIBackgroundModes)) {
+      config.modResults.UIBackgroundModes = [];
+    }
+    const notificationBackgroundMode = 'remote-notification';
+    if (!config.modResults.UIBackgroundModes.includes(notificationBackgroundMode)) {
+      config.modResults.UIBackgroundModes.push(notificationBackgroundMode);
+    }
+    return config;
+  });
+};
+
+const withNotificationSounds: ConfigPlugin<{ sounds: string[] }> = (config, { sounds }) => {
   return withXcodeProject(config, (config) => {
     setNotificationSounds(config.modRequest.projectRoot, {
       sounds,

package/src/registerTaskAsync.ts

@@ -3,11 +3,16 @@ import { UnavailabilityError } from 'expo-modules-core';
 import BackgroundNotificationTasksModule from './BackgroundNotificationTasksModule';
 
 /**
- * When a notification is received while the app is backgrounded, using this function you can set a callback that will be run in response to that notification.
- * Under the hood, this function is run using `expo-task-manager`. You **must** define the task first, with [`TaskManager.defineTask`](./task-manager#taskmanagerdefinetasktaskname-taskexecutor).
- * Make sure you define it in the global scope. It is recommended to define only one task because running a task can have a high cost.
+ * Call `registerTaskAsync` to set a callback (task) that will run in response to when a notification is received while the app is in foreground, background, or terminated.
+ * When app is terminated, only a [data message](https://firebase.google.com/docs/cloud-messaging/concept-options#data_messages) (Android) / [background notification](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app#Create-a-background-notification) (iOS) triggers the task execution.
+ * However, the OS may decide not to deliver the notification to your app in some cases (e.g. when the device is in Doze mode on Android, or when you send too many notifications - Apple recommends to not ["send more than two or three per hour"](https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app#overview)).
  *
- * The callback function you define with `TaskManager.defineTask` will receive an object with the following fields:
+ * Under the hood, this function is run using `expo-task-manager`. You **must** define the task first, with [`TaskManager.defineTask`](./task-manager#taskmanagerdefinetasktaskname-taskexecutor) and register it with `registerTaskAsync`.
+ *
+ * Make sure you define and register the task in the module scope of a JS module which is required early by your app (e.g. in the `index.js` file).
+ * `expo-task-manager` loads your app's JS bundle in the background and executes the task, as well as any side effects which may happen as a consequence of requiring any JS modules.
+ *
+ * The callback function you define with `TaskManager.defineTask` receives an object with the following fields:
  * - `data`: The remote payload delivered by either FCM (Android) or APNs (iOS). See [`PushNotificationTrigger`](#pushnotificationtrigger) for details.
  * - `error`: The error (if any) that occurred during execution of the task.
  * - `executionInfo`: JSON object of additional info related to the task, including the `taskName`.