@ capacor/ 背景运行器

背景 Runner 提供了一个基于事件的独立 JavaScript 环境,用于在网络视图外执行您的 Javascript 代码.

安装

npm install @capacitor/background-runner
npx cap sync

背景跑者支持在使用前需要用户许可的各种设备API.

iOS系统

在 iOS 上, 您必须启用背景模式能力 .

一旦加入,您必须启用 Background fetch 财务报告和审定财务报表 Background processing 模式,以便至少能够登记和安排背景任务.

如果您将使用地理定位或按下通知, 请启用 Location updates 或者说 Remote notifications 页:1.

您还需要在您的 Info.plist 文件 :

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
  <string>com.example.background.task</string>
</array>

阅读 配置 Info.plist 输入 iOS 指南 在 Xcode 中设置 iOS 权限的更多信息.

确定您使用与您使用的相同的ID BGTaskSchedulerPermittedIdentifiers (例如"com.example.background.task")) 于"中国互联网档案馆的存檔,存档日期2011-12-21 label 字段在插件配置中.

在启用背景模式能力后, 在您的应用程序中添加以下内容 AppDelegate.swift数字 :

在档案的顶端,下 import Capacitor 添加:

import CapacitorBackgroundRunner

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)
            }
        }
    }

地理位置

苹果公司要求在其中指定隐私描述 Info.plist 地点信息:

• NSLocationAlwaysUsageDescription (单位:千美元)Privacy - Location Always Usage Description(中文(简体) )
• NSLocationWhenInUseUsageDescription (单位:千美元)Privacy - Location When In Use Usage Description(中文(简体) )

机器人

不需要额外设置.

如果您正在升级一个已有的Android项目,则早期版本的以下剩余部分将不再被使用并可以被删除:

• 内 android/app/build.gradle,则 dirs '../../node_modules/@capacitor/background-runner/android/src/main/libs', 'libs' 线条 flatDir 块
• android/src/main/libs/android-js-engine-release.aar,如果从1.0.5或更早升级

地理位置

此 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() 相应.

12岁及更年长的Android上,它不会显示一个快活的,而且会照常返回.

从Android 12开始 计划通知将是不准确的 除非这个许可被添加到您身上 AndroidManifest.xml数字 :

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

注意,即使权限存在,用户仍然可以禁用应用程序设置中准确的通知.

阅读 设置权限 输入 安卓指南 用于获取关于设置Android权限的更多信息.

关于背景运行器

在构建复杂应用的过程中,它有时在应用不在前期时需要进行工作. 标准Capacitor应用程序的挑战是,当这些背景事件发生时,网页视图不可用,需要您写出本地代码来处理这些事件. 这是背景运行器插件进入的地方 .

背景 Runner 使 JavaScript 代码容易处理本地背景事件. 您只需要创建您的运行 JavaScript 文件 定义您的配置,然后背景运行器插件将自动配置和安排本地背景任务,这些任务将根据您的配置和平台规则执行。 无需修改您的用户界面代码 .

使用背景运行器

背景运行器包含一个无头的 JavaScript 环境,在您指定的 Javascript 文件中调用事件处理器 capacitor.config.ts 文档。 如果运行者在您的运行文件中找到一个事件处理器, 它会执行事件处理器, 然后关闭一次 resolve() 或者说 reject() 被调用(或者如果OS部队杀死了您的进程).

实例运行者 JS 文件

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');

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

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

通话 resolve() \ reject() 实值 所需经费 在每一个事件处理者 由跑者召唤。 不这样做可能导致您的跑者被操作系统所杀, 如果您的事件被调用而应用程序处于背景 。 如果应用程序位于前方,则Async呼叫 dispatchEvent 可能无法解决问题.

对于使用背景运行器的更真实的世界实例,请检查 背景运行器测试 App。 。 。 .

配置背景运行器

装入时, 背景运行器会自动注册一个 一旦您的应用程序被安排并运行的背景任务 有背景介绍.

实例

单位 capacitor.config.json数字 :

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

单位 capacitor.config.ts数字 :

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

import { CapacitorConfig } from '@capacitor/cli';

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

export default config;

Java 脚本 API

背景 Runner 不在浏览器或网页视图中执行您的 Javascript 代码, 因此您可能使用的典型 Web API 可能无法使用 。 包括DOM API 或与您的应用程序的DOM交互能力.

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

• 控制台
  • 仅限 info, (中文(简体) ), log, (中文(简体) ), warn, (中文(简体) ), error ,以及 debug 备有
• 文本解析器
  • 仅限 decode 可用
• 文本编码器
  • 仅限 encode 可用
• 添加事件倾听器
  • 事件倾听者选项和 useCapture 不支持
• 设置时间
• 设置间距
• 清除超时
• 清除间隔
• 密码
• 获取
  • 尚未支持的请求对象
  • 仅 method, (中文(简体) ), headers 财务报告和审定财务报表 body 选项对象中支持

除了标准的Web API,背景运行器还支持一些 自定义控制器 API 显示相关移动设备功能的自定义 API

运行时间

目前,跑步者被设计为在您的应用处于后台时进行周期性连续工作,或者在您的应用处于前台时执行与您的UI分离的线程中的同步工作. 因此,跑步者寿命不长. 竞技场的赛事不设状态。 每次打给 dispatchEvent() 创建一个新上下文,用于您运行的代码被装入并执行,一次 resolve() 或者说 reject() 称为,上下文被破坏.

Android 电池优化

一些Android小贩提供内置电池优化设置,这些设置超越了Android的库存. 其中一些优化必须被您的终端用户禁用,以便您的背景任务正常工作.

访问 别杀我的应用程序! 用于了解受影响的制造商和用户调整设置所需步骤的更多信息.

背景任务的限制

无法在移动操作系统中运行持续,总是运行背景服务. 由于iOS和Android为了减少电池和数据消耗而设计的限制,背景任务受到各种限制的限制,在设计和实施你的背景任务时必须记住这些限制.

iOS系统

• 每次引用你的任务 大约有30秒的运行时间 completed() 或者你的任务被杀死.
• 尽管您可以设定一个间隔来定义您的任务在应用程序背景之后运行的时间, 或者它应该运行多少次, 但这并不能保证 。 iOS将决定您的任务最终运行的时间和频率,部分由您应用的频率决定.
• 模拟器中没有执行背景任务 .

机器人

• 您的任务执行时间最长为10分钟,但为了保持您的任务交叉平台相容,您应当将工作限制在最多为30秒.
• 重复的背景任务最小间隔至少为15分钟. 与iOS类似,任何你要求的间隔都可能不会被精确地击中——实际执行时间受OS电池优化和其他heuristics的限制.

API 密码

• checkPermissions()
• requestPermissions(...)
• dispatchEvent(...)
• addListener('backgroundRunnerNotificationReceived', ...)
• removeNotificationListeners()
• 接口
• 类型异名

检查( )

checkPermissions() => any

检查各种 Capacitor 设备 API 的权限 .

回返情况: any

自: 1.0.0 (单位:千美元)

请求(...)

requestPermissions(options: RequestPermissionOptions) => any

请求显示本地通知的权限 .

回返情况: any

自: 1.0.0 (单位:千美元)

调度事件(...)

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

向配置的跑者发送事件 .

回返情况: any

自: 1.0.0 (单位:千美元)

添加 listener ("背景运行通知收到",...)

addListener(eventName: 'backgroundRunnerNotificationReceived', listenerFunc: (event: NotificationActionEvent) => void) => any

为通知动作添加一个收听器 .

回返情况: any

自: 2.1.1 国家

删除通知听众( )

removeNotificationListeners() => any

删除此插件的通知动作听器 .

回返情况: any

自: 2.1.1 国家

接口

权限状态

请求允许选项

调度事件选项

通知行动活动

插件听筒

类型异名

权限状态

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

API 密码

'geolocation' | 'notifications'

API 电源

接口

电容设备

获取设备信息,如网络连接和电池状态等.

电池状况

网络状态

电源KV

一个简单的字符串密钥/由用户Defaults在iOS和共享首选项在Android上支持的值商店.

电容

发送基本的本地通知 .

通知列表选项

通知选项

电源定位

获取设备位置信息 .

获取当前选项

电容监视器

与该应用程序对齐的手表互动

发送Message, transfer UserInfo并更新应用 Context 是 WCSession 代表方法的原始路径,但目前没有效果 电容监视器 观察应用. 如果开发本地手表应用作为Capacitor应用的配套应用,它们就可以被使用

电源App

状态

应用信息