《React Native实时活动手册：如何开发iOS实时应用及Android 16版本的实时更新功能》

“实时活动”功能是指在配送员接近时，该功能会自动显示在锁屏界面上，并且无需你打开应用程序就能进行更新。苹果在iOS 16.1版本中推出了这一API；而谷歌则在Android 16版本中提供了自己的实现方案，称为“实时更新”功能。

这两个平台上的产品需求是相同的，但相应的开发协议却截然不同。

在iOS系统中，Apple Push Notification服务会自动更新系统自带的SwiftUI组件，而你的应用程序代码根本不会被执行。而在Android系统中，则不存在这种由系统管理的远程更新机制。相反，Firebase Cloud Messaging只会发送数据消息，这些消息会触发后台服务，然后由你的应用程序代码来重新显示通知内容。

在这本手册中，你将学习如何同时实现这两种功能。你需要编写一个TypeScript编写的API，并为其提供两种原生实现方案：一种是使用Swift语言实现的，它与ActivityKit接口进行交互；另一种则是使用Kotlin语言实现的，它与NotificationManager进行交互。你还需要从头开始编写APNs客户端和FCM客户端，每段代码大约只有六十行长，且不需要使用任何第三方库。同时，你也会了解到那些会导致这些API功能出现异常的隐藏问题——因为在这里，几乎所有的错误都不会产生任何明显的提示信息。

为了帮助大家更好地理解这些内容，我制作了一个名为DropTrack的配送跟踪演示项目。下面介绍的所有内容都来自于这个项目，其中还包括一项针对三星三款设备的测试实验，实验的最后还附有一张显示了硬编码允许列表的截图。

目录

1. 先决条件

2. “实时活动”与“实时更新”功能的真正含义

3. 你在哪里见过这个功能

4. 为什么你需要自定义的原生模块

5. iOS系统的协议机制是如何工作的

6. 如何使用SwiftUI构建通知组件

7. 如何将ActivityKit与JavaScript连接起来

8. 四个让我每晚都要花几个小时去解决的iOS开发问题

9. 如何通过APNs从服务器端控制iOS设备

10. 如何从头开始编写APNs客户端代码

11. 如何在真实设备上进行测试

12. 为什么Android系统没有ActivityKit

13. 如何编写Kotlin版本的相关代码

14. 如何通过FCM从服务器端控制Android设备

15. 简单实现方式会留下的三个用户体验方面的缺陷

如何对模拟器和真实设备进行自动化测试

16. iOS系统与Android系统的对比

17. 三星设备的实际测试结果

18. 演示项目的代码仓库

19. 在开始之前需要了解的信息

20. 总结

21. 参考资料与延伸阅读

先决条件

要顺利完成学习，您需要准备以下工具：

• Node.js 20或更高版本。

• Xcode 26或更高版本，同时需要拥有付费的Apple开发者账户。APNs功能需要使用真实的签名密钥以及设备构建文件；模拟器无法接收Live Activity推送通知。

• 安装Android Studio，并使用基于google_apis系统镜像生成的API 36模拟器。FCM功能需要Google Play服务，而纯Android开源项目镜像中并不包含这些服务。

• 为Android部分的学习内容，您还需要一个Firebase项目。

• 您需要具备Swift、Kotlin或TypeScript编程语言的相关知识。本文介绍的是与原生模块相关的内容，并非仅针对JavaScript编写的教程。

我在文中使用的具体版本如下：

androidx.core的版本是必须使用的。1.17.0这个版本回退了Android 16时期的相关API，因此这些API可以与基础SDK 36一起使用进行编译。稍后我会解释其中的原因。

Live Activities与Live Updates的本质

Live Activity并不属于推送通知范畴。推送通知是一种一次性的通知方式，而Live Activity则是一种持久的、可以快速查看的通知形式；它具有自己的状态，并且这种状态会实时发生变化；同时，Live Activity也有特定的系统显示界面。

不同平台对Live Activity的支持情况如下：

• iOS 16.1引入了锁屏界面上的Live Activities功能；16.2版本增加了Dynamic Island功能；17.2版本添加了“点击即可启动”功能；18版本则引入了广播频道功能。更多详细信息，请参阅Apple的ActivityKit文档以及Live Activities人机界面指南。

• Android 16（API 36）引入了Notification.ProgressStyle，即分段式进度条功能。

• Android 16的QPR1版本（API 36.1），也就是第一个季度发布的版本，引入了“推广”功能模块：状态栏提示图标以及锁屏界面上的特殊显示区域。Google将这一系列功能称为以进度为中心的通知系统。

我开发了DropTrack来测试所有这些功能。一个订单会经历七个步骤，从“下单”到“正在配送中”。在配送过程中，也可以重新分配快递员。用户可以通过应用内的控制面板在本地查看订单状态，或者通过推送通知远程获取信息。

您之前在哪里见过这个功能

在开始编写任何代码之前，先了解为什么需要这个API是很重要的，因为仅仅用“锁屏界面上的卡片”来描述它的作用是不够的。

想想你上次点餐的经历：你下了单，然后锁上了手机，接下来会发生什么？如果没有实时更新功能，应用只能通过状态变化时发送推送通知来与你联系——订单已确认、餐厅正在准备食物、快递员已被分配、快递员距离目的地还有两站路程、快递员已经到达……

对于同一笔订单来说，这就意味着会有五条通知。如果每笔订单都是这样，用户很快就会选择关闭这些通知功能。

实时更新功能可以将这五条通知合并成一张会在锁屏界面上动态变化的卡片。同样的信息通过一个界面呈现出来，而且不会让用户感到疲劳。这就是我们开发这个功能的全部意义所在。

苹果自己的《人类界面指南》中提到了这类功能的常见应用场景：体育比赛比分、健身训练、出行服务以及配送任务。谷歌的文档也列出了几乎相同的场景，指出“关键的应用场景包括共享出行、配送服务和导航功能”。那页文档甚至用“进度点”来描述食物准备和配送过程中的各个阶段，并用不同颜色来表示交通状况，而这正是你即将开发的这个界面的核心功能。

已经实现这一功能的应用

为了避免重复介绍这些应用，我直接查看了它们在App Store上的官方介绍。因为一家公司自己描述自己的功能，才是最有力的证据。以下列出的每个应用都用自己官方的语言说明了它们是如何使用实时更新功能的：

苹果也会在自己的软件中提供这一功能。根据Apple Sports的帮助页面介绍，当启用“实时动态”功能后，“你可以在iPhone的锁屏界面或Apple Watch上实时获取相关信息，从而随时了解比赛的进展。”

还有另外两种功能，主要是由科技媒体进行报道的，而非相关公司自己发布的。Uber Eats在2023年5月推出了这一功能，可以显示订单状态、预计送达时间以及司机的姓名和照片。DoorDash则在2023年12月跟进推出了这一功能，在动态岛界面中实时显示预计送达时间。

关于这个表格，有两条需要说明的事项。首先，如果某个应用程序在列表中没有提到“实时动态”功能，并不意味着它没有这个功能，只是我还没有亲自确认而已。Uber Eats就是这样的例子。其次，这个表格反映的是我阅读时看到的信息，任何应用程序都可能在后续版本中添加或删除这一功能。

食品配送服务是这类功能的典型代表，DropTrack也是根据这种模式进行设计的。而打车服务则是应用这一功能风险最高的领域：比如“司机将在3分钟内到达”、“车牌号码”、“当前行程状态”等等——这些信息都是在手机被锁住的情况下，站在路边时可以快速查看的。动态岛界面之所以设计成这样的形式，正是为了满足这类需求：用户可以在半秒钟内快速看到相应的图标和进度百分比。

金融领域则是人们容易忽略的一个例子，在这个领域，分段进度条会发挥很大的作用。例如，加密货币的存款流程并不是“待确认”然后就“完成”，而是需要经过“12次网络确认中的3次已完成”，这种分段进度条能够清晰地反映这一过程，与ProgressStyle中定义的各个阶段以及SwiftUI中的显示方式完全匹配。同样的展示形式也适用于银行转账的结算过程或信用卡支付的完成情况。

不过，在这里我需要特别提醒大家：我查看了各大交易所和新型银行的App Store列表，发现没有一家应用程序明确提到了“实时动态”功能。因此，可以把这一功能视为一个非常适合但尚未被纳入该分类的功能，并不能将其视为现有的成熟技术。

以下是我希望在开始讨论之前就能看到的表格：

>

>

请看第三列。在所有具有商业价值的场景中，更新都是由服务器发起的，而不是设备本身。这意味着该功能的全部价值都体现在推送路径上。而恰恰在这一点上，两个平台出现了差异；也正是在这里，问题会悄然发生，而本手册中大部分关于使用这些功能的难点也集中在这一环节。

使用SwiftUI来设计界面其实是比较简单的一部分。真正困难的是如何让后端在应用程序关闭的情况下依然能够可靠地更新这些界面元素，而且这个过程在不同的平台上会有所不同。

为什么你需要一个自定义的原生模块

在开始编写任何Swift代码之前，我首先考虑了其他替代方案，但它们都存在问题——这些问题其实很有启发性。

expo-live-activity提供了一个预定义的界面布局以及固定的内容显示形式。然而DropTrack需要一个自定义的分段进度条、一种用于重新分配任务的处理机制，以及专用的动态岛界面布局。所有这些功能都需要使用ActivityAttributes以及相应的SwiftUI代码来实现。你可以通过最快的方式完成初始渲染，然后再进行后续的调整。

Notifee是大多数React Native开发者都会选择的通知库，但它目前已经不再更新了。截至本文撰写时，它的GitHub仓库已被标记为“已归档”，最后一次发布的版本是@notifee/react-native@9.1.8，发布于2024年12月。此外，它的Android模块仍然使用compileSdk 34作为开发标准，因此它不支持实时更新功能。目前，自定义原生模块才是实现React Native与Android 16实时更新功能的唯一途径。

所以，最终我们需要：一个本地Expo模块、一套TypeScript API以及两个原生后端服务。

modules/droptrack-live/
├── expo-module.config.json   ← 自动链接功能（适用于苹果和安卓平台）
├── index.ts                  ← 公开的JavaScript API
├── src/                      ← TypeScript类型定义、原生绑定代码以及Web版本的空操作逻辑
├── ios/
│   ├── DeliveryAttributes.swift    ← ActivityKit相关契约代码
│   └── DroptrackLiveModule.swift   ← 将JavaScript代码转换为ActivityKit可识别的格式
└── android/
    ├── DroptrackLiveModule.kt      ← 将JavaScript代码转换为NotificationManager可识别的格式
    ├── DeliveryNotifier.kt         ← 公用的通知构建模块
    └── DroptrackFcmService.kt      ← 负责向NotificationManager发送推送通知的代码

JavaScript接口被刻意设计得非常简洁，并且在不同的平台上都是相同的：

// 卡片的动态部分：每次更新都会替换这个对象。
// 需要保持它的体积小，因为iOS系统会拒绝接收超过4KB的ActivityKit推送数据。
export type DeliveryState = {
  status: string;           // 显示在标题处的文本，例如“已取件”
  progress: number;         // 值范围为0.0到1.0，在两个平台上都会用来显示进度条
  etaEpochMillis: number;   // 以Unix毫秒为单位，JavaScript使用这个值来决定进度条的形状，Swift会对其进行转换
  stopsRemaining: number;   // 显示为“还有2站”或“下一个就是您”
  courierName: string;      // 这个值是动态变化的，因为任务可能会在运输过程中被重新分配
  riderReassigned: boolean; // 如果任务被重新分配，这个值会变为true，从而改变界面的显示方式
};

// 三个动词，对应ActivityKit的生命周期。Android平台也使用类似的三个方法
// 来实现相同的功能，因此调用者无需根据平台不同而进行任何调整。
// startDelivery：启动任务并返回系统分配的唯一标识符。这个标识符在后续的所有操作中都是必需的，
// 但是应用程序重启后，这个标识符就会丢失。
startDelivery(info: DeliveryInfo, state: DeliveryState): Promise;

// updateDelivery：直接替换界面的显示内容。卡片会发生变化，但不会重新出现。
updateDelivery(id: string, state: DeliveryState): Promise;

// endDelivery：完成任务并关闭界面。如果省略dismissAfterSeconds参数，
// 则界面会持续显示一段时间。
endDelivery(id: string, state: DeliveryState, dismissAfterSeconds?: number): Promise;

isSupported(): boolean;          // 如果iOS版本低于16.2、Android版本低于16，或者是在Web环境中，这个方法的返回值为false
areActivitiesEnabled(): boolean; // 如果用户已经在设置中关闭了这些功能，这个方法的返回值为false

最后这两项被故意设置成了独立的。即使用户在设置中关闭了实时活动功能，设备仍然可以支持这种功能，而只有`areActivitiesEnabled()`方法能够检测到这一情况。在这种情况下，`Activity.request`方法会抛出异常，因此`startDelivery`方法也会抛出异常。

`dismissAfterSeconds`这个参数实际上对应于ActivityKit的“关闭策略”。根据苹果官方文档中的默认设置，“系统会在实时活动在锁屏界面结束后的四小时内继续保留该活动的记录”。如果传入一个较小的数值，这个时间窗口就会缩短。

这个项目使用了Expo的“持续原生代码生成”功能，这意味着`ios`和`android`文件夹是由`prebuild`命令生成的，并不会被提交到版本控制系统中。因此，所有的原生代码都存储在模块文件中或配置插件中，这样在执行`prebuild –clean`命令时，这些代码也不会被删除。出于同样的原因，小部件扩展功能也是通过`@bacons/apple-targets`这个工具生成的。

还有一个结构上的细节需要注意：该模块是作为独立的CocoaPod进行编译的，而不是被合并到应用程序的目标代码中。

iOS合约的工作原理

ActivityKit中的活动被分成了两部分。`ActivityAttributes`用于存储静态数据，这些数据一旦设置完毕就不会再发生变化；而其嵌套的`ContentState`则用于存储动态数据，每次更新时，这部分数据都会被全部替换。

大多数教程都会直接介绍这一规则而不解释其原因，但实际上了解为什么平台要这样设计是非常重要的，因为这个原因能帮助我们明确理解某个字段应该属于哪一部分数据。

为什么要进行这种分割

这种分割并不是某种编程规范，而是基于物理层面的限制来决定的。

当我们调用`Activity.request(...)`方法时，实际上是在向ActivityKit提供两样信息：属性数据和初始的内容状态。系统会保存这些属性数据，而不会接受新的副本；从那一刻起，我们能够发送的只有新的`ContentState`数据而已。

这一点可以从ActivityKit的推送消息格式中看出来。以下是我使用的APNs客户端实际传输的数据结构：

aps: {
  // APNs会丢弃早于最新时间戳的数据。
  timestamp: Math.floor(Date.now() / 1000),
  event,                        // "update"或"end"
  'content-state': contentState, // 这是唯一包含数据的字段
}

不存在 `attributes` 这个键。它本来就不应该存在。负载数据中的任何内容都无法到达那部分静态数据区域。

所以，“这个字段应该是静态的还是动态的？”这个问题实际上是在问：“我的服务器是否会有需要修改这个值的情况？”如果答案是肯定的，那么这个字段就必须被存储在ContentState中，因为只有这个字段才能通过推送通知来更新。

整个设计思路就是这样：ActivityAttributes代表活动的身份信息，这些信息在活动创建之初就被确定下来；而ContentState则代表着活动当前的实时状态，每次更新时都会被整体替换，而不是仅仅进行部分修改。如果发送的ContentState中缺少某个字段，那就意味着你并没有正确地解析这些数据。Codable协议使得系统能够在不同的进程之间序列化这些状态数据，而Hashable协议则能让系统判断接收到的状态数据是否与当前屏幕上显示的状态有所不同。

我输掉的那场“赌注”

这是我最初设计的代码，看起来挺合理的：

// 之前的设计：courierName是静态字段。这样的设计可以正常编译、运行，
// 但一旦调度系统在配送过程中重新分配骑手，问题就出现了。
struct DeliveryAttributes: ActivityAttributes {
  public struct ContentState: Codable, Hashable {
    var status: String
    var progress: Double
    var eta: Date
    var stopsRemaining: Int
  }
  var orderId: String
  var courierName: String   // 这里其实是一个“赌注”：一次配送应该只使用一个骑手。
}

将某个字段设置为静态字段，就意味着在活动的整个生命周期内，这个字段的值永远不会发生变化。我当初假设一次配送只需要使用一个骑手，但后来我发现调度系统确实可以在配送过程中重新分配骑手，因此我的这个假设被打破了。

因为courierName是静态字段，所以根本没有办法反映这种变化。无论是通过activity.update()方法，还是通过推送通知，都无法实现这一目的。唯一的解决办法就是结束当前活动并重新开始一个新的活动，但这会导致屏幕上显示的信息发生变化——在配送过程中，卡片上的信息会突然变成另一张不同的卡片。这根本不是解决问题的办法，反而会让问题更加复杂。

因此，我最终改变了这个字段的设计：

// 现在的设计：只有orderId是真正不可变的字段。调度系统可以修改的
// 所有内容都会影响到ContentState，因为ContentState才是APNs推送通知能够携带的唯一数据。
struct DeliveryAttributes: ActivityAttributes {
  public struct ContentState: Codable, Hashable {
    /// 人类可读的状态信息，例如“已取件”、“还有2个站点”
    var status: String
    /// 整体配送进度，范围为0.0到1.0
    var progress: Double
    /// 预计到达时间
    var eta: Date
    /// 骑手在到达用户之前还需要经过的站点数量
    var stopsRemaining: Int
    /// 骑手的显示名称，这个字段是动态的，因为骑手可以在配送过程中被重新分配
    var courierName: String
    /// 在骑手被重新分配后，这个字段会变为true，从而影响系统的处理逻辑
    var riderReassigned: Bool
  }

  /// 卡片上显示的订单编号，这是唯一真正不可变的信息
  var orderId: String
}

修改一个字段竟然涉及到十二个文件，因为每当有代码层需要对这些数据进行编码或解码时，相关的契约规则都会被重复应用。

9  DeliveryNotifier.kt          Android通知构建工具
3  DroptrackLive.types.ts       TypeScript契约文件
3  DroptrackLiveModule.swift    Swift桥接文件
3  App.tsx                      React状态管理及推送处理逻辑
2  DeliveryLiveActivity.swift   widget的SwiftUI实现代码
2  DeliveryAttributes.swift     该模块的相关配置文件
2  DeliveryAttributes.swift     widget的配置文件（重复了一次）
2  DroptrackLiveModule.kt       Kotlin桥接文件
1  DroptrackFcmService.kt, dispatch-server.mjs, push-update.mjs,
   apns.test.mjs, delivery.ts

这里的关键在于这种不对称性：一个从不被修改的动态字段，在每次推送时只会消耗几字节的空间；而一个需要被修改的静态字段，则会占用大量的系统资源。如果有疑问，最好将这个字段放在ContentState中。最终，只有orderId被归类为静态字段。

“相同副本的陷阱”

Widget扩展部分是一个独立的二进制文件，它由系统启动执行，且不会与你的应用程序代码合并。你的应用程序会编译模块中的DeliveryAttributes.swift文件，而Widget则会编译自己对应的配置文件。两次编译会产生两个独立的文件，它们只是名称相同而已。

在运行时，ActivityKit需要将这两个文件连接起来。你的应用程序会请求系统“启动类型为DeliveryAttributes的Activity”，然后系统会询问Widget是否拥有一个名为该类型的WidgetConfiguration对象，其ContentState字段能够解码这些数据。这种匹配是基于类型名称及其Codable结构的，由系统后台进程在运行时跨进程边界进行判断。

现在，将其中一个副本中的courierName改成riderName，然后忽略另一个副本。应用程序和Widget都会正常编译通过，内部逻辑也是一致的。Activity.request()方法会成功执行并返回一个ID。但当系统将编码后的数据传递给Widget时，Widget的解码器会查找riderName，却找不到它，从而导致另一个进程中的后台程序出现异常，而你的断点设置和日志记录在这种情况下是无法起作用的。

结果就是：相关界面根本不会显示出来，也没有任何崩溃提示或控制台错误信息，而Activity.activities列表中仍然会显示该Activity正在运行。你可能会花费一小时时间去调试SwiftUI布局，但实际上问题并不出在布局代码上。

由此可以得出两个结论：首先，共享源文件并不能解决这个问题，因为该模块是作为独立的CocoaPod进行编译的，并不会被合并到应用程序中；其次，由于编译器本身无法检测到这种错误，因此必须通过外部手段来进行检查：diff modules/droptrack-live/ios/DeliveryAttributes.swift \
targets/widgets/DeliveryAttributes.swift

如果这个命令执行后输出了任何内容，那就说明你的Live Activity功能已经出现了故障。在预提交阶段添加这样的检查代码几乎不会增加任何开发成本，但这对保护项目的稳定性来说却至关重要。

如何在SwiftUI中构建这个小部件

这个小部件定义了一个Widget，它有两种显示形式：锁屏界面和动态岛。

在阅读代码之前，请记住一点：这些闭包实际上是从状态到视图的纯函数。小部件扩展程序本身并不是一个正在运行的程序。系统会启动这个进程，使用当前的ContentState来调用你的闭包，然后保留渲染后的结果，最后再终止这个进程。

当有新的状态信息传入时，系统会再次执行这些闭包。这里没有@State指令，也没有定时器、网络请求或onAppear方法在起作用。正因为如此，小部件扩展程序才无法访问网络：因为根本没有人会在那里发起请求。

struct DeliveryLiveActivity: Widget {
  var body: some WidgetConfiguration {
    ActivityConfiguration(for: DeliveryAttributes.self) { context in
      // 第一个闭包：用于锁屏界面和横幅显示
      DeliveryCardView(context: context)
        .activityBackgroundTint(Color(red: 0.07, green: 0.07, blue: 0.12))
        .activitySystemActionForegroundColor(.white)

    } dynamicIsland: { context in          // 第二个闭包：用于动态岛显示
      DynamicIsland {
        // 长按展开时显示的内容：四个可自定义的区块
        DynamicIslandExpandedRegion(.leading) {
          Image(systemName: "bicycle").foregroundStyle(brandOrange)
        }
        DynamicIslandExpandedRegion(.trailing) {
          Text(context.state.eta, style: .time).font(.callout.bold())
        }
        DynamicIslandExpandedRegion(.center) {
          Text(context.state.status).font(.callout.weight(.semibold)).lineLimit(1)
        }
        DynamicIslandExpandedRegion(.bottom) {
          VStack(spacing: 4) {
            SegmentedProgressBar.progress: context.state.progress)
            HStack {
              CourierLabel(state: context.state, compact: true)
              Spacer()
              Text(stopsLabel(context.state.stopsRemaining))
            }
            .font(.caption2).foregroundStyle(.secondary)
          }
        }
      } compactLeading: {                   // 默认显示区域，位于动态岛左侧
        Image(systemName: "bicycle").foregroundStyle(brandOrange)
      } compactTrailing: {                  // 位于右侧的内容
        Text“(Int(context.state.progress * 100))%”).font(.caption2.bold())
      } minimal: {                          // 当其他应用程序共享动态岛时显示的内容
        Image(systemName: "bicycle").foregroundStyle(brandOrange)
      }
      .keylineTint(brandOrange)
    }
  }
}

private struct SegmentedProgressBar: View {
  let progress: Double
  var segments: Int = 7   // 每个步骤对应一个圆形元素

  // ContentState 中存储的是 0 到 1 之间的分数，而不是步数索引，因此需要反向计算出实际需要显示的分段数量。
  // 由于这个值是数字形式，所以组件根本不需要知道这七个步骤的具体名称是什么。
  private var filled: Int {
    // 首先对数值进行限制：如果服务器发送的值是 1.4，那么就不能让 7 个分段中的 10 个都被点亮。
    let clamped = min(max(progress, 0), 1)
    // 使用 `.rounded(.up)` 方法来确保即使进度只有 0.05，也会对应的圆形元素被点亮。
    // progress * 7 = 0.35，向上取整后结果为 1，即有 1 个分段会被点亮。
    // 外层的 `min()` 方法可以确保最终结果一定是 1.0，从而避免出现第 8 个分段被点亮的情况。
    return min(segments, Int((clamped * Double(segments)).rounded(.up)))
  }

  var body: some View {
    HStack(spacing: 5) {
      // 使用 `ForEach` 遍历一个固定的范围，因此可以使用 `id: \.self` 来确保索引是唯一的。
      ForEach(0..<segments, id: \.self) { i in
        RoundedRectangle(cornerRadius: 3, style: .continuous)
          // 这是整个组件中唯一需要根据状态来改变显示效果的代码部分：决定某个分段是否应该被点亮，或者显示什么颜色。
          .fill(i < filled ? brandOrange : trackGray)
          // 高度是固定的，宽度由 `HStack` 自动分配，因此同一个组件可以同时适应宽大的锁屏界面和狭窄的动态岛界面。
          .frame(height: 7)
      }
    }
  }
}

这种重新分配机制在锁屏界面和动态信息栏中都会被使用，因此无论用户身处哪个界面，看到的显示内容都是一样的。
private struct CourierLabel: View {
  let state: DeliveryAttributes.ContentState
  let compact: Bool   // 在动态信息栏中，当水平空间有限时，会采用这种紧凑显示方式

  var body: some View {
    // 这两个分支的显示内容完全由ContentState状态决定，并没有本地状态存储。
    if state.riderReassigned {
      Label(
        // 在动态信息栏中，无法显示“新快递员 · Tunde”这样的完整名称，因此会省略前缀，
        // 通过更换图标和使用橙色来表达这一变化。
        compact ? state.courierName : "新快递员 · \(state.courierName)",
        systemImage: "arrow.triangle.2.circlepath"
      )
      // 子组件的显式样式会覆盖父组件中设置的 secondary 样式，
      // 这也是为什么更换后的快递员信息会在界面中格外显眼的原因。
      .foregroundStyle(brandOrange).bold()
    } else {
      // 当状态没有发生变化时，就使用父组件的标题字体和次要颜色进行显示。
      Label(state.courierName, systemImage: "bicycle")
    }
  }
}

“Record”是Expo所使用的一种类型化桥接结构。在函数体执行之前，所有的@Field字段都会从JS对象中被解析出来；因此，如果某个键缺失或类型错误，错误会在编译阶段就被立即发现，而不会在Swift代码运行过程中才出现问题。当JS代码没有为某个字段指定值时，该字段就会使用默认值。以下是DeliveryStateRecord的结构定义：

struct DeliveryStateRecord: Record {
  @Field var status: String = ""
  @Field var progress: Double = 0
  @Field var etaEpochMillis: Double = 0   // 使用Double类型，而不是Int：因为JS中的数值是f64格式的，
                                          // 而以毫秒为单位表示的时间长度会超出Int32的范围。
  @Field var stopsRemaining: Int = 0
  @Field var courierName: String = ""
  @Field var riderReassigned: Bool = false

  // “桥接类型”与ActivityKit中的类型故意被设计成不同的结构。只有在这个函数中，这两种不同的类型系统才会发生交互。
  @available(iOS 16.2, *)
  func toContentState() -> DeliveryAttributes.ContentState {
    DeliveryAttributes.ContentState(
      status: status,
      progress: min(max(progress, 0), 1),          // 确保进度值在0到1的范围内
      eta: Date(timeIntervalSince1970: etaEpochMillis / 1000), // 将毫秒转换为秒
      stopsRemaining: stopsRemaining,
      courierName: courierName,
      riderReassigned: riderReassigned
    )
  }
}

AsyncFunction("startDelivery") { (info: DeliveryInfoRecord, state: DeliveryStateRecord) -> String in
  // 运行时检查：由于该模块是为较旧的系统版本编写的，因此需要确保调用的是现有的框架功能。
  guard #available(iOS 16.2, *) else { throw LiveActivityUnsupportedException() }

  let activity = try Activity.request(
    attributes: DeliveryAttributes(orderId: info.orderId),                  // 静态参数，只需设置一次
    content: ActivityContent(state: state.toContentState(), staleDate: nil), // 动态参数
    pushType: .token                                                        // 请求APNs发送令牌
  )
  return activity.id   // 这是JS代码能够获取的唯一标识符，而且在页面重新加载后，这个标识符也会被重置。
}

AsyncFunction("updateDelivery") { (activityId: String, state: DeliveryStateRecord) in
  let activity = try Self.findActivity(id: activityId)
  // .update()方法会替换整个ContentState对象，目前没有提供部分更新的接口。
  await activity.update(ActivityContent(state: state.toContentState(), staleDate: nil))
}

@available(iOS 16.2, *)
private static func findActivity(id: String) throws -> Activity {
  // `Activity.activities`是一个由系统管理的实时列表。即使应用程序重新启动、JavaScript代码重新加载，甚至进程被终止，这个列表依然会保持有效。如果将这个列表的引用保存在Swift属性中，那么这些变化就会导致数据丢失，因此每次都需要重新查询。
  guard let activity = Activity.activities.first(where: { $0.id == id }) else {
    // 这种情况通常发生在用户将相关卡片滑出屏幕，或者该活动已经过了有效期限之后。
    throw ActivityNotFoundException(id)
  }
  return activity
}

AsyncFunction("getRunningActivities") { () => {
  guard #available(iOS 16.2, *) else {
    return [];
  }

  // 这是系统提供的活动列表，即使是在全新的进程中也会被生成。关键就在于这里。
  return Activity.activities.map(activity => {
    self.observePushToken(of: activity);   // 重新订阅推送通知
    let state = activity.content.state;    // 获取实时状态信息
    return [
      "activityId": activity.id,                // 这个ID是JavaScript之前丢失的
      "orderId": activity.attributes.orderId,   // 静态信息
      "status": state.status,
      "progress": state.progress,
      "courierName": state.courierName,
      "riderReassigned": state.riderReassigned,
    ];
  });
}

useEffect(() => {
  const sync = () => {
    void DroptrackLive.getRunningActivities().then((running) => {
      const activity = running[0];
      if (!activity) return;   // 如果没有活动在运行，就保持空白状态
      setActivityId(activity.activityId);   // 这一行代码会重新激活整个用户界面
      setRider({ name: activity.courierName, justReassigned: activity.riderReassigned });
      
      // 卡片上显示的状态字符串并不代表步骤索引，因此需要检查是否为-1。
      const index = STEPS.findIndex((s) => s.status === activity.status);
      if (index >= 0) setStepIndex(index);
    });
  };

  sync();   // 情况1：应用程序重新启动
  const sub = AppState.addEventListener("change", (s) => {
    if (s === "active") sync();   // 情况2：从后台恢复运行
  });
  return () => { sub.remove(); };
}, []);

let activity = try Activity.request(
  attributes: attributes,
  content: ActivityContent(state: state.toContentState(), staleDate: nil),
  pushType: .token   // 这个参数之前被设置为`nil`，而实际上这个参数才是实现该功能的关键。
)

Task {
  for await tokenData in activity.pushTokenUpdates {
    let token = tokenData.map { String(format: "%02x", $0) }.joined()   // 将原始数据转换为十六进制字符串
    NSLog("[DropTrack] 接收到的推送令牌：%@: %@", activity.id, token)       // 使用NSLog进行日志记录，以便devicectl能够接收到这些信息
    self.sendEvent("onPushTokenReceived", ["activityId": activity.id, "token": token])
  }
}

"ios": {
  "entitlements": {
    "aps-environment": "development",
    "com.apple.security.application-groups": ["group.com.fasarticle.droptrack"]
  }
}

# 用于读取被嵌入到签名后的.app文件中的权限信息。
# 如果这里没有指定aps-environment，那么无论app.json中如何设置，令牌获取操作都不会成功。
codesign -d --entitlements - --xml Build/Products/Release-iphoneos/DropTrack.app

import { createPrivateKey, sign } from "node:crypto";

const b64url = (buf) => Buffer.from(buf).toString("base64url");   // JWT使用的是base64url，而不是base64

export function mintJWT({ keyPath, keyId, teamId }) {
  const header = b64url(JSON.stringify({ alg: "ES256", kid: keyId }));   // kid：这个10个字符长的键ID
  const claims = b64url(JSON.stringify({ iss: teamId, iat: Math.floor(Date.now() / 1000) }));
  const signingInput = `${header}.${claims}`;   // JWT的签名部分是由头部信息和声明信息组合而成的

  const signature = sign("sha256", Buffer.from(signingInput), {
    key: createPrivateKey(readFileSync(keyPath, "utf8')),
    dsaEncoding: "ieee-p1363",   // 这一行代码非常重要。如果使用默认的DER编码方式，会导致签名失败。请注意这一点。
  });

  return `${signingInput}.${b64url(signature)}`;
}

// 这些伪请求头是HTTP/2用来编码请求信息的格式
// `client`在这里指的是与APNs服务器建立的HTTP/2会话。
const req = client.request({
  ":method": "POST",
  // 路径中包含的设备令牌实际上是针对特定活动的令牌，并不是来自UNUserNotificationCenter的设备令牌，
  // 这两种令牌是完全不同的。
  ":path": `/3/device/${token}`,
  authorization: `bearer ${jwt}`,   // APNs期望使用小写的"bearer"作为授权字段

  // 对于实时活动推送，需要在topic后面加上后缀。如果只发送不带后缀的bundle id，APNs会直接拒绝请求。
  "apns-topic": `${bundleId}.push-type.liveactivity`,
  "apns-push-type": "liveactivity", // 这个字段的值必须与topic后面的后缀相匹配
  "apns-priority": "10",            // 10表示立即发送，5表示择机发送
  "apns-expiration": "0",           // 0表示不重试失败的推送请求
});

req.end(JSON.stringify({
  aps: {
    // 时间戳字段的作用是确保推送消息的顺序正确。APNs会丢弃时间戳早于之前已发送的消息，
    // 因此如果顺序混乱，重新尝试也不会恢复正确的顺序。
    timestamp: Math.floor(Date.now() / 1000),
    event: "update",              // "update"用于更新信息，"end"用于完成推送操作
    // 这些数据会直接被解码并放入小部件的Codable ContentState中。字段名和类型必须与这个结构完全匹配，
    // 注意避免出现格式错误导致的问题。
    "content-state": contentState,
  },
}));

const APPLE_EPOCH_OFFSET = 978_307_200;   // 1970年到2001年之间的时间间隔（秒）

// 这是插件解码时所需的数据格式，而不是原生模块处理时的数据格式。
function toContentState({ etaEpochMillis, ...rest }) {
  return {
    ...rest,
    eta: Math.floor(etaEpochMillis / 1000) - APPLE_EPOCH_OFFSET,   // 将毫秒转换为秒，然后减去起始时间
  };
}

# --console            将应用程序的标准输出/错误输出重定向到当前终端
# --terminate-existing         先终止正在运行的实例，以便能捕获启动时的日志信息
# --device             指定COREDEVICE的ID（详见下面的注意事项）
xcrun devicectl device process launch --console --terminate-existing \
  --device  com.fasarticle.droptrack
# → [DropTrack] 推送令牌为3095ACA0-...: 80875cb137590013a4c9...
#   ^ 这个十六进制字符串就是调度服务器会提取并发送的推送令牌

dependencies {
  // NotificationCompat为36.1版本的API提供了回溯实现，因此可以使用它们
  // 与36基础版本进行兼容编译。如果没有这个依赖项，
  // ProgressStyle、setRequestPromotedOngoing和setShortCriticalText这些方法将无法被使用。
  implementation 'androidx.core:core-ktx:1.17.0'
}

Function("canPostPromotedNotifications") {
  // 这是一个同步执行的函数，因为UI需要在第一次渲染时就知道是否需要禁用该功能。
  val manager = notificationManager ?: return@Function false

  // 如果设备的API版本低于36，则不需要进行推广通知的检查。
  if (Build.VERSION.SDK_INT < 36) return@Function false

  // 虽然官方文档称这个方法是在API 36中添加的，但在预QPR版本中调用它会导致崩溃。因此，当该方法不可用时，应将其默认值设置为false。
  return@Function runCatching { manager.canPostPromotedNotifications() }.getOrDefault(false)
}

// 进度百分比需要进行限制，以防止数值过大导致显示异常。
val progressPercent = (progress.coerceIn(0.0, 1.0) * 100).toInt()

val builder = NotificationCompat.Builder(ctx, CHANNEL_ID)
  .setSmallIcon(R.drawable.ic_delivery)
  .setContentTitle(status)                     // 推广通知功能要求设置标题
  ..setContentText(courierLine(courierName, riderReassigned, stopsRemaining))
  .setSubText("订单编号：$orderId")
  .setOngoing(ongoing)                         // 推广通知功能要求显示进行中状态
  .setOnlyAlertOnce(true)                      // 只提示一次，之后自动更新状态
  .setColor(BRAND_ORANGE)                      // 不设置颜色会导致功能无法正常使用
  .setShortCriticalText("$progressPercent%")   // 状态栏中的进度文本
  .setRequestPromotedOngoing(ongoing)          // 发送推广通知的请求本身

// `when`参数用于设置预计到达时间，这个时间必须是在未来。
if (etaEpochMillis > System.currentTimeMillis()) {
  builder.setWhen(etaEpochMillis.toLong()).setShowWhen(true)
}

if (Build.VERSION.SDK_INT >= 36) {
  val style = NotificationCompat.ProgressStyle()
    .setStyledByProgress(true)                 // 进度条的颜色会随数值变化而改变
    .setProgress(progressPercent)
    .setProgressTrackerIcon(IconCompat.createWithResource(ctx, R.drawable.ic_delivery))
    .setProgressSegments(listOf(               // 进度条的分段
      NotificationCompat.ProgressStyle.Segment(100).setColor(BRAND_ORANGE)
    ))
    .setProgressPoints(listOf(                 // 分段上的标记点
      NotificationCompat ProgressStyle.Point(35)..setColor(Color.WHITE)
    ))}
  builder.setStyle/style)
} else {
  builder.setProgress(100, progressPercent, false)  // 在Android 16之前的版本中使用这种简单的进度条实现方式
}

val notification = builder.build()
if (Build.VERSION.SDK_INT >= 36) {
  Log.d(TAG, "hasPromotableCharacteristics=${notification.hasPromotableCharacteristics()}")
}
manager.notify(notificationIdFor(activityId), notification)   // 使用稳定的通知ID进行发送

// 在应用清单文件中注册了这个服务，因此Android系统可以在不需要你的Activity、React上下文或模块的情况下直接实例化它。
class DroptrackFcmService : FirebaseMessagingService() {

  // 在应用安装完成后会调用此方法，每当FCM更新令牌时也会再次调用。千万不要认为启动时看到的令牌仍然有效。
  override fun onNewToken(token: String) {
    Log.i(DeliveryNotifier TAG, "[DropTrack] fcm token: $token")
  }

  override fun onMessageReceived(message: RemoteMessage) {
    // FCM发送来的数据总是以Map的形式存在。所有的数字和布尔值在传输过程中都会被转换为字符串形式，因此在这里需要重新解析回原始类型。
    val d = message.data

    // 如果没有activityId字段，就意味着无法确定通知的具体内容。在这种情况下应该直接放弃处理，而不是随意猜测：使用错误的id发送通知会导致重复的通知界面出现。
    val activityId = d["activityId"] ?: return
    val event = d["event"] ?: "update"

    // 这个服务是一个独立的入口点，它无法访问模块中的内存状态，因此所有的数据都必须从接收到的消息中获取。在进行解析时必须格外小心，因为一旦出现错误，整个更新流程就会失败。
    DeliveryNotifier.ensureChannel(this)   // 当前进程可能是全新的
    DeliveryNotifier.post(
      ctx = this,
      activityId = activityId,
      // 下面所有的“?:”操作都起着关键作用。toDoubleOrNull方法会在输入数据格式不正确时返回null，而不会抛出异常，因此即使数据有误，也不会导致服务崩溃。
      orderId = d["orderId"] ?: "",
      status = d["status"] ?: "",
      progress = d["progress"]?.toDoubleOrNull() ?: 0.0,
      etaEpochMillis = d["etaEpochMillis"]?..toDoubleOrNull() ?: 0.0,
      stopsRemaining = d["stopsRemaining"]?.toIntOrNull() ?: 0,
      courierName = d["courierName"] ?: "",
      riderReassigned = d["riderReassigned"]?.toBoolean() ?: false,
      // 设置“end”状态可以清除“ongoing”状态，这样用户就可以最终删除这个通知界面了。
      ongoing = event != "end",
    )
  }
}

// `sa` 是从 Firebase获取的已解析的服务账户JSON数据。这个JWT并不是你发送给FCM的凭证；而是你需要用它来换取一个短期有效的访问令牌。
export function buildAuthJWT(sa) {
  const now = Math.floor(Date.now() / 1000);
  const header = b64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));  // 使用RSA密钥进行加密，因此不会遇到ieee-p1363相关的问题
  const claims = b64url(JSON.stringify({
    iss: sa.client_email,
    scope: "https://www.googleapis.com/auth/firebase.messaging",  // 必须指定具体的权限范围，否则每次发送消息都会收到403错误
    aud: sa.token_uri,        // 这个JWT是专门用于向Google的令牌端点请求访问令牌的
    iat: now,
    exp: now + 3600,          // 一小时后失效，这是Google规定的最大有效期
  }));
  const signingInput = `${header}.${claims}`;
  const sig = createSign("RSA-SHA256").update(signingInput).sign(sa.private_key);
  return `${signingInput}.${b64url(sig)}`;
}

export async function sendDataMessage({ token, data, sa }) {
  const accessToken = await getAccessToken(sa);   // 用JWT换取访问令牌，并将结果缓存起来
  const res = await fetch(
    `https://fcm.googleapis.com/v1/projects/${sa.project_id}/messages:send`,
    {
      method: "POST",
      headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
      body: JSON.stringify({
        message: {
          token,                        // 每个设备都需要一个令牌（APNs则是按活动来分配令牌的）
          data,                         // 注意：这里不需要`notification`键
          android: { priority: "high" },       // 优先级设置为“高”
        },
      }),
    }
  );
  const body = await res.json().catch(() => ({}));   // 如果响应数据格式错误，也不会抛出异常
  return { status: res.status, reason: body?.error?.status ?? null };
}

// plugins/withAndroidFcm.js
function withGoogleServicesJson(config) {
  // withDangerousMod会在预构建过程中执行任意的文件系统操作。这种做法虽然“危险”，但却是唯一一种可以在Gradle插件期望该文件已存在的情况下实际插入该文件的方法。
  return withDangerousMod(config, ["android", (cfg) =>> {
    // 这个文件被保存在仓库的根目录下，Git会忽略它，但在每次预构建时都会被复制到目标位置。
    const src = path.join(cfg.modRequest.projectRoot, "google-services.json");
    // 它必须被放置在android/app/目录中，因为google-services插件会在那里查找这个文件。
    const dest = path.join.cfg.modRequest.platformProjectRoot, "app", "google-services.json");

    // 如果找不到这个文件，就必须在预构建阶段抛出错误。如果不这样做，构建过程会成功完成，应用程序也会启动，但FCM在运行时却会无法正常初始化。
    if (!fs.existsSync(src)) {
      throw new Error("[withAndroidFcm] 项目根目录下未找到google-services.json文件");
    }

    fs.copyFileSync(src, dest);
    return cfg;
  });
}
// 还需要使用withProjectBuildGradle来配置类路径，
// 并使用withAppBuildGradle来应用该插件。

private fun launchIntent(ctx: Context, activityId: String): PendingIntent? {
  // 不要直接使用“MainActivity”这个类名，而是通过包管理器来获取对应的启动意图。
  // 在Expo的持续原生生成机制下，这个类名是动态生成的，如果硬编码的话，在下次预构建时会出问题。
  val intent = ctx.packageManager.getLaunchIntentForPackage(ctx.packageName)
    // SINGLE_TOP：重用现有的任务栈，而不是创建一个新的任务栈。
    // CLEAR.TOP：清除当前任务栈中的所有内容，使用户直接进入目标界面。
    ?.apply { flags = Intent.FLAG_ACTIVITY_SINGLE_Top or IntentFLAG_activityCLEAR Tops }
    ?: return null

  return PendingIntent.getActivity(
    ctx,
    // 请求代码。每个活动都有唯一的请求代码，这样同时发送的两个通知就会得到不同的PendingIntents，
    // 而不会共享同一个PendingIntent。
    notificationIdFor(activityId),
    intent,
    // 在Android 12及更高版本中，必须使用FLAG_IMMUTABLE；如果不使用这个标志，程序会抛出异常。
    PendingIntent.FLAG_immUTABLE or PendingIntent FLAG_UPDATE_CURRENT,
  )
}

companion object {
  // 这个变量是静态的，因为FCM服务无法直接访问模块的INSTANCE；同时使用@Volatile注解，是因为该服务运行在与其他线程不同的线程上。
  // 这个变量也可能是null，因为在大多数情况下，并没有活跃的模块需要发送通知。
  @Volatile private var pushEmitter: ((Map) -> Unit)? = null

  // 从任何地方都可以安全地调用这个方法。这里的`?.`实际上就是在检查“应用程序是否还处于活动状态”。
  fun emitPush(data: Map) { pushEmitter?.invoke(data) }
}

override fun definition() = ModuleDefinition {
  // 宣布JavaScript可以订阅的事件。如果声明了不存在的事件，程序会抛出异常。
  Events("onFcmTokenReceived", "onDeliveryPush")

  // 当模块实例存在时，建立这个桥梁机制…
  OnCreate  { pushEmitter = { data -> sendEvent("onDeliveryPush", data) } }
  // …当模块实例不存在时，删除这个桥梁机制。如果不删除它，就会导致内存泄漏。
  OnDestroy { pushEmitter = null }
  // …
}

与iOS版本中的实现使用相同的JavaScript函数名，因此App.tsx文件无需根据平台进行任何修改。  
AsyncFunction("getRunningActivities") {  
  val ctx = context ?: return@AsyncFunction emptyList()  
  
  // 这个值用于替代iOS系统中的Activityactivities：它在每次调用notify()时会被更新。  
  val active = DeliveryNotifier.activeDelivery(ctx)  
    ?: return@AsyncFunction emptyList()  
  val activityId = active["activityId"] as String  
  
  // 如果系统中的通知列表与我们的记录不一致，就重新初始化相关数据。  
  if (!DeliveryNotifier.isActive(ctx, activityId)) {  
    DeliveryNotifier.clear(ctx)  
    return@AsyncFunction emptyList()  
  }  
  
  // 将相关数据添加到内存映射中。如果应用程序是冷启动的，后续的操作可能会抛出异常。  
  deliveries[activityId] = DeliveryInfoRecord().apply { orderId = active["orderId"] as String }  
  return@AsyncFunction listOf(active)  
}

useEffect(() => {
  // 在发布版本中，这些代码会被删除：打包工具会移除整个effect块。
  if (!__DEV__) return;

  // "droptrack://drive/next" -> "next" -> 调用actions.next()方法。
  // 应该使用actionsRef而不是actions，因为监听器只注册一次，如果使用普通的闭包，就会永久捕获第一次渲染时的处理函数。
  const run = (url: string) => actionsRef.current[url.split("/").pop() ?? ""]?.();

  // 情况1：应用程序已经在运行中。simctl openurl会触发这个事件。
  const sub = Linking.addEventListener("url", ({ url }) => run(url));

  // 情况2：使用devicectl --payload-url命令来冷启动应用程序：此时URL会作为初始地址被传递过来，因此不会触发“url”事件。需要同时处理这两种情况，否则在模拟器自动化运行时，设备自动化功能将无法正常工作。
  void Linking.getInitialURL().then((url) => url && run(url));

  return () => sub.remove();
}, []);

# 这个命令会让正在运行的应用程序向前执行一步，无需用户点击操作，也不会请求访问权限。
xcrun simctl openurl booted "com.fasarticle.droptrack://drive/next"

iPhone --NSLog--> devicectl --console --
Android --Log.i--> adb logcat -----------+
                                         | 获取推送令牌
浏览器 <- SSE /events --> 调度服务器 (127.0.0.1:8787)
   \--POST /push --------> apns.mjs / fcm.mjs --> APNs / FCM --> 设备