iOS 实时活动用 ActivityKit 把进行中的事放到锁屏和灵动岛。本文给 SwiftUI 工程加一个外卖配送实时活动:用 kxbuild project add-target 添加扩展,写锁屏和灵动岛三种样式,启动、更新、结束并用 APNs 推送。
iOS 实时活动(Live Activity)用 ActivityKit 把一件正在进行的事放到锁屏和灵动岛上,比如外卖配送、打车、比赛比分。做法是给 App 加一个小组件扩展写界面,在 App 里用 ActivityKit 启动、更新和结束,必要时由服务器通过 APNs 推送更新。
这篇给 SwiftUI 工程 MyApp 加一个「外卖配送」实时活动:用 kxbuild project add-target --type widget-live-activity 添加扩展,写锁屏和灵动岛三种样式,在 App 里启动、更新、结束,最后从电脑用 APNs 推送更新它,全程在 Windows 上完成。
实时活动的界面写在小组件扩展里,建议先看[给 iOS App 加一个桌面小组件(WidgetKit)]。文中的 Apple 规则以官方文档为准,截至 2026 年 10 月。这是KXBuild VSCode 插件地址,安装完再开始
iOS 实时活动和小组件有什么不同?
两者都用 SwiftUI 写界面、放在同一个小组件扩展里,但更新方式完全不同。
| 小组件 | 实时活动 | |
|---|---|---|
| 显示位置 | 主屏幕、锁屏、今天视图 | 锁屏、灵动岛、StandBy,配对的 Apple Watch 和 Mac |
| 谁来更新 | 系统按时间线定时取数据 | App 用 ActivityKit 更新,或服务器推送 |
| 持续时间 | 一直在 | 一件事结束就结束,最长 8 小时 |
| 适合 | 一眼看完的汇总信息 | 正在进行、几分钟就变一次的状态 |
| 能否联网 | 时间线里可以 | 不能,数据只能从 App 或推送来 |
几条需要提前知道的限制。
| 规则 | 内容 |
|---|---|
| 系统版本 | ActivityKit 从 iOS 16.1 开始提供,下文用到的 ActivityContent 写法要 iOS 16.2。本文添加的扩展要求 iOS 17 及以上 |
| 灵动岛 | 只有带灵动岛的 iPhone(iPhone 14 Pro 起)显示,其他机型只显示锁屏样式,解锁时以横幅出现 |
| 持续时间 | 活动最多进行 8 小时,到时系统自动结束并从灵动岛移除。结束后最多再在锁屏停留 4 小时,所以锁屏上最长 12 小时 |
| 数据大小 | 不变数据和会变数据加起来不能超过 4 KB,每次更新和推送也是 |
| 启动时机 | 一般要在 App 处于前台时启动,更新和结束可以在后台 |
| 用户开关 | 用户可以在「设置」里关闭某个 App 的实时活动 |
第 1 步:怎么添加实时活动扩展?
以下两种做法任选其一。
- VS Code 插件。在 KXBuild 视图中右键 MyApp 这个 target,选
KXBuild: 添加 Target…,类型选带实时活动的小组件,名称用默认的 MyAppWidget。实时活动不需要和 App 共享数据,App Group 留空。 - 命令行。在工程所在目录执行下面的命令。
kxbuild project add-target -P .\MyApp.xcodeproj --type widget-live-activity --name MyAppWidget
widget-live-activity 会添加一个小组件扩展,里面同时有一个普通小组件和一个实时活动。扩展的 Bundle ID 是 App 的 Bundle ID 加点和小写的名称,这里是 com.example.myapp.myappwidget,命令输出里会提示为它注册 App ID。全部类型和参数见 [kxbuild 命令参考]和[添加 Target]。
已经按 171 篇加过 widget 类型小组件的工程,不用再加一个扩展。把下文的实时活动代码加进原来的扩展,在 MyAppWidgetBundle.swift 的 body 里加上它,再按下一节给 App 开启 Supports Live Activities。
添加扩展后生成了哪些文件?
工程目录下多出一个 MyAppWidget 文件夹。
| 文件 | 作用 |
|---|---|
| MyAppWidgetBundle.swift | 扩展入口,同时列出小组件和实时活动 |
| MyAppWidget.swift | 普通小组件,不需要可以从 Bundle 里去掉 |
| MyAppWidgetLiveActivity.swift | 实时活动的数据定义和界面 |
| Info.plist | 声明这是一个 WidgetKit 扩展 |
| Assets.xcassets | 强调色和背景色 |
MyAppWidgetBundle.swift 里已经同时列出了两者,不用改。
@main
struct MyAppWidgetBundle: WidgetBundle {
var body: some Widget {
MyAppWidget()
MyAppWidgetLiveActivity()
}
}
第 2 步:开启 Supports Live Activities
App 要在 Info.plist 里声明 NSSupportsLiveActivities 为 YES,否则启动实时活动会失败。
用 widget-live-activity 添加时,App target 的构建设置里已经加上了 INFOPLIST_KEY_NSSupportsLiveActivities = YES,在[工程设置编辑器]的 Build Settings 页搜索 NSSupportsLiveActivities 能看到。
工程自己维护 Info.plist 文件的(比如从老 Xcode 项目搬过来的),在 App 的 Info.plist 里加上下面这个键,用[属性列表编辑器]改也可以。
<key>NSSupportsLiveActivities</key>
<true/>
这个键加在 App 的 Info.plist 里,不是扩展的。
第 3 步:实时活动的数据怎么定义?
实时活动的数据分两部分,用一个遵守 ActivityAttributes 的结构体描述。
- 不变的数据,写成结构体的属性,比如订单号、店名。启动时定好,之后不能改。
- 会变的数据,写在嵌套的
ContentState里,比如状态、进度、预计送达时间。每次更新都整份换掉。
App 启动活动时要用到这个类型,扩展显示时也要用到,所以两边各放一份一模一样的定义。字段名、类型、嵌套结构必须完全一致,推送里的 JSON 也按这些字段名解析。
第 4 步:锁屏和灵动岛界面怎么写?
把 MyAppWidget/MyAppWidgetLiveActivity.swift 换成下面的内容。
import ActivityKit
import WidgetKit
import SwiftUI
/// 实时活动的数据。App 里要有一份一模一样的定义
struct DeliveryAttributes: ActivityAttributes {
/// 会变的数据:每次 update 或推送都换一份新的
public struct ContentState: Codable, Hashable {
var status: String
var progress: Double
var eta: Date
}
/// 不变的数据:启动时定好,之后不能改
var orderNumber: String
var shopName: String
}
struct MyAppWidgetLiveActivity: Widget {
var body: some WidgetConfiguration {
ActivityConfiguration(for: DeliveryAttributes.self) { context in
// 锁屏,以及没有灵动岛的机型上的横幅
DeliveryLockScreenView(context: context)
.activityBackgroundTint(Color.orange.opacity(0.15))
.activitySystemActionForegroundColor(.orange)
} dynamicIsland: { context in
DynamicIsland {
// 展开样式:长按灵动岛,或收到带提醒的更新时出现
DynamicIslandExpandedRegion(.leading) {
Label(context.attributes.shopName, systemImage: "bag.fill")
.font(.caption)
.foregroundStyle(.orange)
}
DynamicIslandExpandedRegion(.trailing) {
CountdownText(eta: context.state.eta)
.font(.caption.bold())
}
DynamicIslandExpandedRegion(.center) {
Text(context.state.status)
.font(.headline)
.lineLimit(1)
}
DynamicIslandExpandedRegion(.bottom) {
ProgressView(value: context.state.progress)
.tint(.orange)
}
} compactLeading: {
Image(systemName: "bag.fill")
.foregroundStyle(.orange)
} compactTrailing: {
CountdownText(eta: context.state.eta)
.frame(width: 44)
.font(.caption2.bold())
} minimal: {
Image(systemName: "bag.fill")
.foregroundStyle(.orange)
}
.keylineTint(.orange)
}
}
}
struct DeliveryLockScreenView: View {
let context: ActivityViewContext<DeliveryAttributes>
var body: some View {
VStack(alignment: .leading, spacing: 8) {
HStack {
Label(context.attributes.shopName, systemImage: "bag.fill")
.font(.subheadline.bold())
.foregroundStyle(.orange)
Spacer()
Text("订单 \(context.attributes.orderNumber)")
.font(.caption)
.foregroundStyle(.secondary)
}
HStack(alignment: .firstTextBaseline) {
Text(context.isStale ? "状态可能已过时" : context.state.status)
.font(.headline)
Spacer()
CountdownText(eta: context.state.eta)
.font(.headline)
}
ProgressView(value: context.state.progress)
.tint(.orange)
}
.padding()
}
}
/// 倒计时由系统负责走字,不需要每秒更新实时活动
struct CountdownText: View {
let eta: Date
var body: some View {
if eta > Date() {
Text(timerInterval: Date()...eta, countsDown: true)
.monospacedDigit()
.multilineTextAlignment(.trailing)
} else {
Text("即将送达")
}
}
}
ActivityConfiguration 的第一个闭包是锁屏样式,dynamicIsland 闭包里是灵动岛的三种样式。三种都要提供,系统按场景自动选。
| 样式 | 什么时候出现 | 代码位置 |
|---|---|---|
| 紧凑(compact) | 只有一个实时活动时,摄像头左右各一块 | compactLeading、compactTrailing |
| 最小(minimal) | 多个 App 同时有实时活动时,缩成一个小圆 | minimal |
| 展开(expanded) | 长按灵动岛,或收到带提醒的更新时短暂出现 | DynamicIsland { } 里的各个区域 |
展开样式用 DynamicIslandExpandedRegion 分区摆放内容。
| 区域 | 位置 |
|---|---|
.leading | 摄像头左侧,内容多时往下排 |
.trailing | 摄像头右侧,内容多时往下排 |
.center | 摄像头下方 |
.bottom | 以上三块的下方,适合放进度条 |
写界面时注意几点。
- 倒计时交给系统。
Text(timerInterval:countsDown:)会自己走字,不要为了让秒数变化去频繁更新活动。 - 紧凑样式要窄。宽度有限时内容会被截断,用图标或很短的文字。
- 锁屏高度。超过 160 点系统可能截断。
- 过时状态。启动和更新时可以给一个
staleDate,到时context.isStale变成true,界面上提示信息可能不是最新的。 - 动画。实时活动里
withAnimation这类动画修饰会被忽略,系统用自己的过渡效果。 - 图片。图片分辨率不能大于显示区域,太大的图可能导致活动启动失败。
点击实时活动默认打开 App。
第 5 步:在 App 里怎么启动、更新和结束?
把 App 的 MyApp/ContentView.swift 换成下面的内容。文件开头是和扩展里一模一样的 DeliveryAttributes,后面是管理实时活动的类和三个按钮。
import ActivityKit
import SwiftUI
/// 和小组件里的定义保持一字不差
struct DeliveryAttributes: ActivityAttributes {
public struct ContentState: Codable, Hashable {
var status: String
var progress: Double
var eta: Date
}
var orderNumber: String
var shopName: String
}
@available(iOS 16.2, *)
@MainActor
final class DeliveryActivityManager: ObservableObject {
@Published var message = ""
private var activity: Activity<DeliveryAttributes>?
init() {
// App 被系统关掉后重新打开,接回还在进行的实时活动
activity = Activity<DeliveryAttributes>.activities.first
}
func start() {
guard ActivityAuthorizationInfo().areActivitiesEnabled else {
message = "实时活动已在设置中关闭"
return
}
let attributes = DeliveryAttributes(orderNumber: "A1024", shopName: "街角咖啡")
let state = DeliveryAttributes.ContentState(
status: "商家已接单",
progress: 0.2,
eta: Date().addingTimeInterval(20 * 60)
)
do {
let activity = try Activity.request(
attributes: attributes,
content: ActivityContent(state: state, staleDate: Date().addingTimeInterval(30 * 60)),
pushType: .token // 不用推送更新时传 nil
)
self.activity = activity
message = "已启动 \(activity.id)"
watchPushToken(of: activity)
} catch {
message = "启动失败:\(error.localizedDescription)"
}
}
func update() async {
guard let activity else { return }
let state = DeliveryAttributes.ContentState(
status: "骑手已取餐",
progress: 0.7,
eta: Date().addingTimeInterval(8 * 60)
)
await activity.update(
ActivityContent(state: state, staleDate: Date().addingTimeInterval(15 * 60)),
alertConfiguration: AlertConfiguration(title: "骑手已取餐", body: "预计 8 分钟送达", sound: .default)
)
message = "已更新"
}
func end() async {
guard let activity else { return }
let final = DeliveryAttributes.ContentState(status: "已送达", progress: 1, eta: Date())
await activity.end(ActivityContent(state: final, staleDate: nil), dismissalPolicy: .default)
self.activity = nil
message = "已结束"
}
private func watchPushToken(of activity: Activity<DeliveryAttributes>) {
Task {
// 令牌是异步生成的,而且中途可能变,每次变化都要重新上报
for await data in activity.pushTokenUpdates {
let token = data.map { String(format: "%02x", $0) }.joined()
print("Live Activity push token: \(token)")
// 在这里把 token 和订单号一起发给你的服务器
}
}
}
}
@available(iOS 16.2, *)
struct DeliveryPanel: View {
@StateObject private var manager = DeliveryActivityManager()
var body: some View {
VStack(spacing: 16) {
Button("开始配送") { manager.start() }
.buttonStyle(.borderedProminent)
Button("骑手已取餐") { Task { await manager.update() } }
Button("已送达,结束") { Task { await manager.end() } }
Text(manager.message)
.font(.footnote)
.foregroundStyle(.secondary)
}
}
}
struct ContentView: View {
var body: some View {
if #available(iOS 16.2, *) {
DeliveryPanel()
.padding()
} else {
Text("实时活动需要 iOS 16.2 及以上")
}
}
}
三个操作分别对应 ActivityKit 的三个方法。
| 操作 | 方法 | 要点 |
|---|---|---|
| 启动 | Activity.request(attributes:content:pushType:) | App 在前台时调用。pushType: .token 表示要用推送更新,会拿到一个 push token |
| 更新 | activity.update(_:alertConfiguration:) | 传一份新的 ContentState。带 AlertConfiguration 时,灵动岛机型会短暂展开,其他机型以横幅提示 |
| 结束 | activity.end(_:dismissalPolicy:) | 带上最终状态。.default 让它在锁屏多留一段时间,.immediate 立即移除,.after(date) 到指定时间移除 |
启动可能失败,比如用户关了实时活动,或者设备上同时进行的活动已经到上限,所以 request 要放在 do/catch 里,把错误提示给用户。Activity<DeliveryAttributes>.activities 能拿到这个 App 当前所有进行中的活动,App 重启后用它接回之前的活动。
暂时不做推送的,把 pushType: .token 改成 pushType: nil,下面的推送能力也可以先不开。
第 6 步:App ID 和描述文件要怎么准备?
实时活动所在的扩展是一个单独的程序,签名用自己的描述文件。登录 developer.apple.com,进入 Certificates, Identifiers & Profiles,按下面的顺序操作。
- 给扩展注册 App ID。在 Identifiers 页点加号,选 App IDs → App,Bundle ID 选 Explicit,填
com.example.myapp.myappwidget。 - App 的 App ID 开启 Push Notifications。要用推送更新时才需要,在 App 的 App ID(
com.example.myapp)的 Capabilities 里勾选 Push Notifications,保存。 - 生成描述文件。给扩展的 App ID 新建 Development 描述文件。App 开启推送后,把 App 原来的描述文件 Edit 后直接 Save,重新下载。
- 放进 keychain 目录。两份描述文件都放进 KXBuild 的
keychain目录,删掉 App 的旧描述文件。构建时按 Bundle ID 自动给 App 和扩展各配一份。
用推送还要给 App 加 aps-environment entitlement,做法和普通推送完全一样,按[给 iOS App 加推送通知]的「给工程加 entitlements」一节操作。实时活动的推送令牌由 ActivityKit 提供,App 不用调用 registerForRemoteNotifications 来拿它。
扩展签名的完整规则见 [iOS App 扩展的签名配置]。
第 7 步:在 iPhone 上验证
- 在状态栏选好 iPhone,按 F5。KXBuild 会把 App 和扩展一起构建、签名并安装,然后启动 App。
- 点「开始配送」。下拉通知中心或锁屏,能看到锁屏样式的实时活动。带灵动岛的机型回到主屏幕,灵动岛左右出现图标和倒计时。
- 长按灵动岛看展开样式。
- 回到 App 点「骑手已取餐」,灵动岛会短暂展开提示,锁屏上的状态和进度跟着变。
- 点「已送达,结束」,灵动岛上的活动消失,锁屏上保留最终状态。
调试时注意几点。
- F5 调试的是 App。实时活动的界面在扩展进程里渲染,App 里的断点管不到它。界面只负责显示,状态的计算放在 App 或服务器上。
- 看 push token。用了
pushType: .token的,启动后 VS Code「输出 → KXBuild Console」里会打印Live Activity push token:加一串十六进制,下一节要用。 - 没反应先看开关。「设置」里找到这个 App,确认实时活动是打开的。
怎么用 APNs 推送更新实时活动?
App 不在前台时,最可靠的更新方式是服务器推送。流程如下。
- App 用
pushType: .token启动活动,从pushTokenUpdates拿到这个活动专属的 push token,上报给服务器。 - 订单状态变化时,服务器用这个 token 给 APNs 发一条
liveactivity类型的推送。 - 系统收到后唤醒扩展,按推送里的
content-state重新渲染界面。
push token 属于某一个活动,和普通推送的设备令牌不是一回事,每启动一个新活动都要上报新的 token。它在活动期间也可能变化,收到新 token 后服务器要换掉旧的。
请求头
推送请求和普通推送用同一个 APNs 地址和 .p8 密钥签的 JWT,只是三个请求头不同。
| 请求头 | 值 | 说明 |
|---|---|---|
apns-push-type | liveactivity | 固定值 |
apns-topic | com.example.myapp.push-type.liveactivity | App 的 Bundle ID 加 .push-type.liveactivity,不是扩展的 Bundle ID |
apns-priority | 5 或 10 | 10 立即送达,计入每小时的推送额度;5 不计入额度 |
地址按环境选。F5 装上去的 Debug 包用 https://api.sandbox.push.apple.com,TestFlight 和 App Store 包用 https://api.push.apple.com。.p8 密钥的创建见 158 篇的「创建 APNs 认证密钥」。
请求体
{
"aps": {
"timestamp": 1792370815,
"event": "update",
"content-state": {
"status": "骑手已取餐",
"progress": 0.7,
"eta": 814064095
},
"stale-date": 1792371715
}
}
| 字段 | 作用 |
|---|---|
timestamp | 当前时间,1970 年起的秒数。系统据此只显示最新的一次更新 |
event | update 更新,end 结束 |
content-state | 字段要和 ContentState 完全对应,系统用默认规则解码,不能用自定义的 JSON 编码策略 |
stale-date | 可选,到这个时间界面变成过时状态 |
dismissal-date | 可选,只用于 end,结束后在这个时间从锁屏移除,填过去的时间就是立即移除 |
alert | 可选,带上后灵动岛机型会展开,其他机型显示横幅 |
eta 是 Date 类型,最容易出错。系统用默认规则解码 Date,它要的是从 2001 年 1 月 1 日起算的秒数,不是 Unix 时间戳。服务器上用 Unix 秒数减去 978307200 再填进去。不想处理这个差值,可以把字段改成 Double 类型的 Unix 秒数,界面里再用 Date(timeIntervalSince1970:) 转换。
从电脑发一条测试推送
在 158 篇用过的文件夹里(里面已经有 .p8 密钥),新建 la.mjs,改掉开头四个常量。脚本只用 Node.js 自带模块,会自动填好 timestamp 和换算好的 eta。
import crypto from 'node:crypto'
import fs from 'node:fs'
import http2 from 'node:http2'
const TEAM_ID = 'ABCDE12345' // Team ID
const KEY_ID = 'XYZ1234567' // Key ID
const KEY_FILE = 'Auth_Key_XYZ1234567.p8' // .p8 文件
const BUNDLE_ID = 'com.example.myapp' // App 的 Bundle ID,不是扩展的
const HOST = 'https://api.sandbox.push.apple.com' // F5 装的 Debug 包走开发环境
function makeJwt() {
const b64 = (obj) => Buffer.from(JSON.stringify(obj)).toString('base64url')
const unsigned = b64({ alg: 'ES256', kid: KEY_ID }) + '.' + b64({ iss: TEAM_ID, iat: Math.floor(Date.now() / 1000) })
const key = crypto.createPrivateKey(fs.readFileSync(KEY_FILE))
const sig = crypto.sign('sha256', Buffer.from(unsigned), { key, dsaEncoding: 'ieee-p1363' })
return unsigned + '.' + sig.toString('base64url')
}
const [event, token, status = '骑手已取餐', minutes = '8', progress = '0.7'] = process.argv.slice(2)
if (!['update', 'end'].includes(event) || !token) {
console.log('用法 node la.mjs update|end <push token> [状态] [剩余分钟] [进度]')
process.exit(1)
}
const now = Math.floor(Date.now() / 1000)
const aps = {
timestamp: now,
event,
'content-state': {
status,
progress: Number(progress),
// Swift 的 Date 默认按 2001-01-01 起的秒数解码
eta: now + Number(minutes) * 60 - 978307200,
},
}
if (event === 'update') aps['stale-date'] = now + 15 * 60
if (event === 'end') aps['dismissal-date'] = now + 60 * 60
const payload = JSON.stringify({ aps })
console.log(payload)
const client = http2.connect(HOST)
client.on('error', (err) => { console.error(err.message); process.exit(1) })
const req = client.request({
':method': 'POST',
':path': '/3/device/' + token,
authorization: 'bearer ' + makeJwt(),
'apns-topic': BUNDLE_ID + '.push-type.liveactivity',
'apns-push-type': 'liveactivity',
'apns-priority': '10',
})
let code
let body = ''
req.on('response', (headers) => { code = headers[':status'] })
req.setEncoding('utf8')
req.on('data', (chunk) => { body += chunk })
req.on('end', () => { console.log(code, body); client.close() })
req.end(payload)
在 App 里点「开始配送」,从 KXBuild Console 复制 push token,然后锁上手机,执行下面的命令。
node la.mjs update 粘贴的push token "骑手距您 1 公里" 3 0.9
返回 200 表示 APNs 已经接收,锁屏上的状态、倒计时和进度几秒内就会变化。再执行一次 end 结束活动。
node la.mjs end 粘贴的push token "已送达" 0 1
返回 400、403 时,响应里的 reason 说明了原因,对照 158 篇的「APNs 返回错误」一节处理。最常见的是 apns-topic 写成了扩展的 Bundle ID,或者 Debug 包发到了生产地址。
更新频率
系统给每个 App 的实时活动推送设了每小时额度,具体数字没有公开。用 apns-priority: 10 的推送计入额度,超了会被限流;5 不计入额度,送达没那么及时。
- 不需要用户马上看到的变化(进度从 60% 到 65%)用 5,关键节点(骑手已到楼下)用 10。
- 倒计时用
Text(timerInterval:)交给系统,不要靠推送每秒更新。 - 比分直播这类每分钟要更新多次的场景,在 App 的 Info.plist 里加
NSSupportsLiveActivitiesFrequentUpdates为 YES,申请更高的频率。用户可以在「设置」里关掉它,App 里用ActivityAuthorizationInfo().frequentPushesEnabled检查。
推送可能因为没网送不到,活动结束后到达的推送也会被忽略。App 回到前台时再用 update 同步一次,避免显示过时的信息。
用推送启动活动
iOS 17.1 及更早的系统只能用推送更新和结束实时活动,不能用推送启动。
更新的系统上,App 可以从 Activity<DeliveryAttributes>.pushToStartTokenUpdates 拿到一个启动用的令牌,服务器用它发 event 为 start 的推送,请求体要带 attributes-type(这里是 DeliveryAttributes)、attributes 和 alert。这一步做完基础流程后再加。
实时活动不显示或报错怎么排查?
| 现象 | 原因 | 处理 |
|---|---|---|
Activity.request 抛错,提示不支持或未授权 | App 的 Info.plist 没有 NSSupportsLiveActivities,或用户关了实时活动 | 按上文检查构建设置,「设置」里打开该 App 的实时活动 |
| 启动成功但锁屏、灵动岛都不显示 | 扩展没装上,或手机系统低于扩展要求的 iOS 17 | 确认 F5 时扩展也签名成功,手机系统是 iOS 17 及以上 |
| 只有锁屏样式,没有灵动岛 | 机型没有灵动岛 | 正常现象,用带灵动岛的机型测试 |
| 启动失败,提示达到上限 | 同时进行的活动太多 | 结束旧的活动,request 要处理错误 |
| 一直拿不到 push token | App 没开推送能力或没带 aps-environment | 开通 Push Notifications,重新生成描述文件,加 entitlement |
| 推送返回 200,界面没变 | content-state 字段名或类型和 ContentState 对不上,或者 Date 填成了 Unix 秒数 | 逐个核对字段,Date 用 2001 年起的秒数 |
推送返回 400 TopicDisallowed 或 DeviceTokenNotForTopic | apns-topic 不对,或 token 和环境不匹配 | topic 用 App 的 Bundle ID 加 .push-type.liveactivity,Debug 包用 sandbox 地址 |
| 构建时报扩展的描述文件找不到 | keychain 里没有 com.example.myapp.myappwidget 的描述文件 | 注册 App ID 并生成描述文件,放进 keychain |
| 活动几小时后自己消失 | 到了 8 小时上限 | 正常现象,长时间的事情拆成多个活动,或改用推送通知 |
签名和安装相关的报错见 [iOS 签名报错与 ipa 安装失败,16 条常见错误及解决办法]。
带实时活动的 App 怎么打包上架?
上架时 App 和扩展都要有 App Store 类型的描述文件,放进 keychain 目录后,在 KXBuild 视图「构建配置」节点切到 Release,命令面板运行 KXBuild: 构建,或者执行下面的命令。
kxbuild build .\MyApp.xcodeproj -c Release
生成的 build\MyApp.ipa 里已经带着 iOS 实时活动扩展。正式版的推送要发到 https://api.push.apple.com,用环境为 Production 的 .p8 密钥签 JWT,令牌也换成正式包上报的新令牌。扩展和 App 的版本号要一致,改版本号时在[工程设置编辑器]里把 MyApp 和 MyAppWidget 一起改。
常见问题
实时活动最低支持哪个 iOS 版本?
ActivityKit 从 iOS 16.1 开始提供,本文用的 ActivityContent 写法要 iOS 16.2。用 KXBuild 添加的扩展要求 iOS 17 及以上,所以按本文做的实时活动在 iOS 17 及以上的 iPhone 上显示。
实时活动最长能显示多久?
一个实时活动最多进行 8 小时,到时系统自动结束并从灵动岛移除。结束后还能在锁屏上停留最多 4 小时,所以锁屏上最长 12 小时。
没有灵动岛的 iPhone 能用实时活动吗?
能。没有灵动岛的机型显示锁屏样式,手机解锁时带提醒的更新会以横幅出现。灵动岛样式只在 iPhone 14 Pro 起带灵动岛的机型上显示。
实时活动推送的 apns-topic 怎么写?
写成 App 的 Bundle ID 加 .push-type.liveactivity,例如 com.example.myapp.push-type.liveactivity,同时把 apns-push-type 设为 liveactivity。不要用扩展的 Bundle ID,令牌要用 pushTokenUpdates 拿到的活动令牌。
推送返回 200 但实时活动没更新是什么原因?
多半是 content-state 和 ContentState 的字段名或类型对不上,系统解码失败就不更新。Date 字段要填从 2001 年 1 月 1 日起的秒数,timestamp 要用当前时间,活动已经结束的推送也会被忽略。