@capacitor/background-runner - npm Package Compare versions

Comparing version 1.0.1-dev-20230807T230144.0 to 1.0.1-dev-20230809T182239.0

package.json

 {
   "name": "@capacitor/background-runner",
-  "version": "1.0.1-dev-20230807T230144.0",
+  "version": "1.0.1-dev-20230809T182239.0",
   "description": "Capacitor Background Runner",
@@ -83,3 +83,3 @@ "main": "dist/plugin.cjs.js",
   },
-  "gitHead": "0c7dde163121b218b5599b4aa072527daa37a771"
+  "gitHead": "e512c827056b1efb2be4da995d04b2755d86717e"
 }

README.md

@@ -13,9 +13,10 @@ # @capacitor/background-runner
 Background Runner has support for various device APIs that require permission from the user prior to use.
+
 ## iOS
 
-On iOS you must enable the Background Modes capability. 
+On iOS you must enable the Background Modes capability.
 
 ![Enable Background Mode Capability in Xcode](https://github.com/ionic-team/capacitor-background-runner/raw/main/docs/enable_background_mode_capability.png)
 
-Once added, you must enable the `Background fetch` and `Background processing` modes at a minimum to enable the ability to register and schedule your background tasks.  
+Once added, you must enable the `Background fetch` and `Background processing` modes at a minimum to enable the ability to register and schedule your background tasks.
 
@@ -30,3 +31,3 @@ If you will be making use of Geolocation or Push Notifications, enable `Location updates` or `Remote notifications` respectively.
 func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
-    
+
     // ....
@@ -42,2 +43,3 @@ BackgroundRunnerPlugin.registerBackgroundTask()
 To allow the Background Runner to handle remote notifications, add the following:
+
 ```swift
@@ -58,2 +60,3 @@ func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
 ### Geolocation
+
 Apple requires privacy descriptions to be specified in `Info.plist` for location information:
@@ -69,2 +72,3 @@
 ### Geolocation
+
 This API requires the following permissions be added to your `AndroidManifest.xml`:
@@ -82,4 +86,5 @@
 ### Local Notifications
-Android 13 requires a permission check in order to send notifications.  You are required to call `checkPermissions()` and `requestPermissions()` accordingly.
 
+Android 13 requires a permission check in order to send notifications. You are required to call `checkPermissions()` and `requestPermissions()` accordingly.
+
 On Android 12 and older it won't show a prompt and will just return as granted.
@@ -98,58 +103,67 @@
 ## Using Background Runner
-Background Runner is an event based JavaScript environment that emits events to a javascript runner file that you designate in your `capacitor.config.ts` file.  If the runner finds a event handler corresponding to incoming event in your runner file, it will execute the event handler, then shutdown once `details.completed()` is called (or if the OS force kills your process).
 
+Background Runner is an event based JavaScript environment that emits events to a javascript runner file that you designate in your `capacitor.config.ts` file. If the runner finds a event handler corresponding to incoming event in your runner file, it will execute the event handler, then shutdown once `resolve()` or `reject()` are called (or if the OS force kills your process).
+
 #### Example Runner JS File
 
 ```js
-addEventListener("myCustomEvent", (details) => {
-  console.log("do something to update the system here");
-  details.completed();
+addEventListener('myCustomEvent', (resolve, reject, args) => {
+  console.log('do something to update the system here');
+  resolve();
 });
 
-addEventListener("myCustomEventWithReturnData", (details) => {
-  console.log("accepted this data: " + JSON.stringify(details.user));
+addEventListener('myCustomEventWithReturnData', (resolve, reject, args) => {
+  try {
+    console.log('accepted this data: ' + JSON.stringify(args.user));
 
-  const updatedUser = details.user;
-  updatedUser.firstName = updatedUser.firstName + " HELLO";
-  updatedUser.lastName = updatedUser.lastName + " WORLD";
+    const updatedUser = args.user;
+    updatedUser.firstName = updatedUser.firstName + ' HELLO';
+    updatedUser.lastName = updatedUser.lastName + ' WORLD';
 
-  details.completed(updatedUser);
+    resolve(updatedUser);
+  } catch (err) {
+    reject(err);
+  }
 });
 
-addEventListener("remoteNotification", (details) => {
-  console.log("received silent push notification");
+addEventListener('remoteNotification', (resolve, reject, args) => {
+  try {
+    console.log('received silent push notification');
 
-  CapacitorNotifications.schedule([
-    {
+    CapacitorNotifications.schedule([
+      {
         id: 100,
-        title: "Enterprise Background Runner",
-        body: "Received silent push notification",
-    },
-  ]);
+        title: 'Enterprise Background Runner',
+        body: 'Received silent push notification',
+      },
+    ]);
 
-  details.completed();
+    resolve();
+  } catch (err) {
+    reject();
+  }
 });
-
 ```
-Calling `details.completed()` is **required** within every event handler called by the runner.  Failure to do this could result in your runner being killed by the OS if your event is called while the app is in the background.  If the app is in the foreground, async calls to `dispatchEvent` may not resolve.
 
+Calling `resolve()` \ `reject()` is **required** within every event handler called by the runner. Failure to do this could result in your runner being killed by the OS if your event is called while the app is in the background. If the app is in the foreground, async calls to `dispatchEvent` may not resolve.
+
 ## Configuring Background Runner
-On load, Background Runner will automatically register a background task that will be scheduled and ran once your app is backgrounded.  The settings for this behavior is defined in your `capacitor.config.ts` file:
 
+On load, Background Runner will automatically register a background task that will be scheduled and ran once your app is backgrounded. The settings for this behavior is defined in your `capacitor.config.ts` file:
+
 ```ts
 const config: CapacitorConfig = {
-    plugins: {
-        BackgroundRunner: {
-            label: "com.example.background.task",
-            src: "background.js",
-            event: "myCustomEvent",
-            repeat: true,
-            interval: 2,
-            autoStart: false,
-        },
+  plugins: {
+    BackgroundRunner: {
+      label: 'com.example.background.task',
+      src: 'background.js',
+      event: 'myCustomEvent',
+      repeat: true,
+      interval: 2,
+      autoStart: false,
     },
-}
+  },
+};
 ```
 
-
 ## JavaScript API
@@ -162,9 +176,9 @@
 - [console](https://developer.mozilla.org/en-US/docs/Web/API/console)
-    - only `info`, `log`, `warn`, `error` , and `debug` are available
+  - only `info`, `log`, `warn`, `error` , and `debug` are available
 - [TextDecoder](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder)
-    - only `decode` is available
+  - only `decode` is available
 - [TextEncoder](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder)
-    - only `encode` is available
+  - only `encode` is available
 - [addEventListener](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener)
-    - Event Listener options and `useCapture` not supported
+  - Event Listener options and `useCapture` not supported
 - [setTimeout](https://developer.mozilla.org/en-US/docs/Web/API/setTimeout)
@@ -176,16 +190,15 @@ - [setInterval](https://developer.mozilla.org/en-US/docs/Web/API/setInterval)
 - [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
-    - Request object not yet supported
-    - Only `method`, `headers` and `body` supported in options object
+  - Request object not yet supported
+  - Only `method`, `headers` and `body` supported in options object
 
 In addition to the standard Web APIs, Background Runner also supports a number of [custom Capacitor APIs](#capacitor-api) custom APIs that expose relevant mobile device functionality
 
-
-
 ## Runner Lifetimes
 
-Currently, the runners are designed for performing periodic bursts of work while your app is in the background, or for executing asynchronous work in a separate thread from your UI while your app is in the foreground.  As a result, runners are not long lived.  State is not maintained between calls to events in the runner.  Each call to `dispatchEvent()` creates a new context in with your runner code is loaded and executed, and once `completed()` is called, the context is destroyed.
+Currently, the runners are designed for performing periodic bursts of work while your app is in the background, or for executing asynchronous work in a thread separate from your UI while your app is in the foreground. As a result, runners are not long lived. State is not maintained between calls to events in the runner. Each call to `dispatchEvent()` creates a new context in which your runner code is loaded and executed, and once `resolve()` or `reject()` is called, the context is destroyed.
 
 ## Android Battery Optimizations
-Some Android vendors offer built-in battery optimization settings that go beyond what stock Android provides.  Some of these optimizations must be disabled by your end users in order for your background tasks to work properly.
 
+Some Android vendors offer built-in battery optimization settings that go beyond what stock Android provides. Some of these optimizations must be disabled by your end users in order for your background tasks to work properly.
+
 Visit [Don't kill my app!](https://dontkillmyapp.com) for more information on the affected manufacturers and steps required by your users to adjust the settings.
@@ -195,3 +208,3 @@
 
-It’s not possible to run persistent, always running background services on mobile operating systems.  Due to the limitations imposed by iOS and Android designed to reduce battery and data consumption, background tasks are constrained with various limitations that you must keep in mind while designing and implementing your background task.
+It’s not possible to run persistent, always running background services on mobile operating systems. Due to the limitations imposed by iOS and Android designed to reduce battery and data consumption, background tasks are constrained with various limitations that you must keep in mind while designing and implementing your background task.
 
@@ -201,3 +214,3 @@ ### iOS
 - Each invocation of your task has approximately up to 30 seconds of runtime before you must call `completed()` or your task is killed.
-- While you can set an interval to define when your task runs after the app is backgrounded, or how often it should run, this is not guaranteed.  iOS will determine when and how often you task will ultimately run, determined in part by how often you app is used.
+- While you can set an interval to define when your task runs after the app is backgrounded, or how often it should run, this is not guaranteed. iOS will determine when and how often you task will ultimately run, determined in part by how often you app is used.
 
@@ -207,3 +220,3 @@ ### Android
 - Your task has a maximum of 10 minutes to perform work, but to keep your task cross platform compatible, you should limit your work to 30 seconds at most.
-- Repeating background tasks have a minimal interval of at least 15 minutes.  Similar to iOS, any interval you request may not be hit exactly - actual execution time is subject to OS battery optimizations and other heuristics.
+- Repeating background tasks have a minimal interval of at least 15 minutes. Similar to iOS, any interval you request may not be hit exactly - actual execution time is subject to OS battery optimizations and other heuristics.
 
@@ -319,4 +332,4 @@ ## API
 
+## Capacitor API
 
-## Capacitor API
 <capacitor-api-docs>
@@ -420,2 +433,2 @@
 
-</capacitor-api-docs>
+</capacitor-api-docs>

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

2475444

increased by0.58%

Number of lines in readme file

421

increased by3.44%

No dependency changes