后台运行器提供了一个基于事件的独立 JavaScript 环境，用于在WebView之外执行您的 JavaScript 代码。

npm install @jigra/background-runner
npx jig sync

后台运行器支持各种需要用户在使用前授予权限的设备 API。

在 iOS 上，您必须启用后台模式功能。

一旦添加，您至少必须启用 后台检索 和 后台处理 模式，以启用注册和安排后台任务的能力。

如果您将使用地理位置或推送通知，请分别启用 位置更新 或 远程通知。

在启用后台模式功能后，将以下内容添加到应用程序的 AppDelegate.swift

在文件顶部，在 import Jigra 下方添加

import JigraBackgroundRunner

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    // ....
    BackgroundRunnerPlugin.registerBackgroundTask()
    BackgroundRunnerPlugin.handleApplicationDidFinishLaunching(launchOptions: launchOptions)
    // ....

    return true
}

为了允许后台运行器处理远程通知，添加以下内容

func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
        // ....
        BackgroundRunnerPlugin.dispatchEvent(event: "remoteNotification", eventArgs: userInfo) { result in
            switch result {
            case .success:
                completionHandler(.newData)
            case .failure:
                completionHandler(.failed)
            }
        }
    }

Apple 要求在 Info.plist 中指定对地理位置信息的隐私描述

• NSLocationAlwaysUsageDescription (隐私 - 总是使用位置描述)
• NSLocationWhenInUseUsageDescription (隐私 - 使用时使用位置描述)

有关在 配置 Info.plist 的更多信息，请访问 iOS 指南

将以下行插入到 android/app/build.gradle

...

repositories {
    flatDir{
        dirs '../jigra-cordova-android-plugins/src/main/libs', 'libs'
+		dirs '../../node_modules/@jigra/background-runner/android/src/main/libs', 'libs'
    }
}
...

如果您是从现有 Android 项目中升级到 1.0.0，请确保从 android/src/main/libs 中删除 android-js-engine-release.aar。

此 API 需要在您的 AndroidManifest.xml 中添加以下权限

<!-- Geolocation API -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-feature android:name="android.hardware.location.gps" />

前两个权限请求位置数据，精细和粗糙，最后一行是可选但必要的，如果您的应用程序 需要 GPS 来运行。您可以不添加它，但请记住，这意味着您的应用程序可能安装在缺乏 GPS 硬件的设备上。

Android 13 需要进行权限检查才能发送通知。您必须相应地调用 checkPermissions() 和 requestPermissions()。

在 Android 12 及更早版本中，将不会显示提示，直接返回为已授予。

从 Android 12 开始，除非在您的 AndroidManifest.xml 中添加此权限，否则计划的通知不会非常精确。

<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />

请注意，即使权限存在，用户仍然可以从应用设置中禁用精确通知。

有关在 设置权限 的更多信息，请参阅 Android 指南

在构建复杂应用程序的过程中，有时需要在应用不在前台时执行工作。标准 Jigra 应用程序的一个挑战是，当这些后台事件发生时，WebView 不可用，这要求您编写本地代码来处理这些事件。这就是后台运行器插件发挥作用的地方。

背景运行器让编写JavaScript代码处理本地后台事件变得简单。您只需要创建自己的运行器JavaScript文件，并在定义配置后，背景运行器插件将自动配置和安排一个根据您配置和平台规则的本地后台任务。不需要修改您的UI代码。

背景运行器包含一个无头JavaScript环境，在您的jigra.config.ts文件中指定的JavaScript文件中调用事件处理器。如果运行器在您的运行器文件中找到对应于传入事件的处理器，它将执行事件处理器，然后在调用resolve()或reject()后关闭（或在操作系统强制终止您的进程时）。

addEventListener('myCustomEvent', (resolve, reject, args) => {
  console.log('do something to update the system here');
  resolve();
});

addEventListener('myCustomEventWithReturnData', (resolve, reject, args) => {
  try {
    console.log('accepted this data: ' + JSON.stringify(args.user));

    const updatedUser = args.user;
    updatedUser.firstName = updatedUser.firstName + ' HELLO';
    updatedUser.lastName = updatedUser.lastName + ' WORLD';

    resolve(updatedUser);
  } catch (err) {
    reject(err);
  }
});

addEventListener('remoteNotification', (resolve, reject, args) => {
  try {
    console.log('received silent push notification');

    JigraNotifications.schedule([
      {
        id: 100,
        title: 'Enterprise Background Runner',
        body: 'Received silent push notification',
      },
    ]);

    resolve();
  } catch (err) {
    reject();
  }
});

在运行器调用的每个事件处理器中，调用resolve() \ reject()是必需的。如果没有这么做，如果在应用处于后台时事件被调用，操作系统可能会终止您的运行器。如果应用处于前台，异步的dispatchEvent调用可能不会解析。

在加载时，背景运行器将自动注册一个后台任务，当您的应用进入后台时，将安排和运行此任务。

在jigra.config.json

{
  "plugins": {
    "BackgroundRunner": {
      "label": "com.example.background.task",
      "src": "runners/background.js",
      "event": "myCustomEvent",
      "repeat": true,
      "interval": 15,
      "autoStart": true
    }
  }
}

在jigra.config.ts

/// <reference types="@jigra/background-runner" />

import { JigraConfig } from '@jigra/cli';

const config: JigraConfig = {
  plugins: {
    BackgroundRunner: {
      label: "com.example.background.task",
      src: "runners/background.js",
      event: "myCustomEvent",
      repeat: true,
      interval: 15,
      autoStart: true,
    },
  },
};

export default config;

背景运行器不在浏览器或web视图中执行您的JavaScript代码，因此您可能习惯的典型Web API可能不可用。这包括DOM API以及与您的应用DOM交互的能力。

以下是背景运行器提供的可用Web API列表

• 控制台
  • 仅支持info、log、warn、error和debug
• TextDecoder
  • 仅支持decode
• TextEncoder
  • 仅支持encode
• addEventListener
  • 不支持事件监听器选项和useCapture
• setTimeout
• setInterval
• clearTimeout
• clearInterval
• crypto
• fetch
  • 请求对象尚不支持
  • 在选项对象中仅支持method、headers和body

除了标准Web API之外，背景运行器还支持一些自定义Jigra API，这些API可以公开相关的移动设备功能。

目前，运行器是为在应用后台执行周期性工作负载，或在应用处于前台时在不同于UI的线程中执行异步工作而设计的。因此，运行器不会长时间存活。状态在调用运行器的事件之间不会保留。每次调用dispatchEvent()都会创建一个新的上下文，用于加载和执行运行器代码，并在调用resolve()或reject()后销毁上下文。

一些安卓设备厂商提供了超越原生安卓功能的内置电池优化设置。其中一些优化设置必须由最终用户禁用，以确保您的后台任务能够正常工作。

访问不要杀了我的应用！以获取有关受影响厂商和用户调整设置所需的步骤的更多信息。

在移动操作系统上无法运行持续运行的后台服务。由于iOS和Android为减少电池和数据消耗而设定的限制，后台任务受限于各种限制，您在设计和实施后台任务时必须牢记。

• 您的任务每次调用前的执行时间大约为30秒，之后您必须调用completed()或者您的任务将被终止。
• 虽然您可以为任务设置一个间隔以定义后台开始运行的时间，或者它应该运行的频率，但这并不保证。iOS将决定任务最终何时以及多频繁运行，部分取决于您使用应用频率。
• 后台任务在模拟器中不会执行。

• 您的任务有最多10分钟的时间来执行工作，但为了保持跨平台兼容性，您应该限制工作在30秒以内。
• 重复后台任务的间隔至少为15分钟。类似iOS，您请求的任何间隔可能不会完全满足实际执行时间，这取决于操作系统电池优化和其他启发式算法。

• checkPermissions()
• requestPermissions(...)
• dispatchEvent(...)
• 接口
• 类型别名

checkPermissions() => any

检查各种Jigra设备API权限。

返回： any

自 1.0.0

requestPermissions(options: RequestPermissionOptions) => any

请求显示本地通知权限。

返回： any

自 1.0.0

dispatchEvent<T = void>(options: DispatchEventOptions) => any

向配置的运行器发送事件。

返回： any

自 1.0.0

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

'geolocation' | 'notifications'

<!

获取有关设备的信息，如网络连接和电池状态。

基于iOS的UserDefaults和Android的Shared Preferences的一个简单的字符串键/值存储。

发送基本本地通知。

获取设备位置信息访问权限。

与与此应用配对的智能手表进行交互

sendMessage、transferUserInfo和updateApplicationContext是WCSession代理方法的原生路由，但在JigraWatch智能手表应用程序中目前没有效果。如果开发了一个原始的智能手表应用程序作为Jigra应用程序的伴侣程序，则可以实现这些功能。