iOS 实时活动怎么开发,Windows 上用 KXBuild 和 ActivityKit 写灵动岛

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 留空。
  • 命令行。在工程所在目录执行下面的命令。
powershell 复制代码
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 里已经同时列出了两者,不用改。

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 里加上下面这个键,用属性列表编辑器改也可以。

xml 复制代码
<key>NSSupportsLiveActivities</key>
<true/>

这个键加在 App 的 Info.plist 里,不是扩展的。

第 3 步:实时活动的数据怎么定义?

实时活动的数据分两部分,用一个遵守 ActivityAttributes 的结构体描述。

  • 不变的数据,写成结构体的属性,比如订单号、店名。启动时定好,之后不能改。
  • 会变的数据 ,写在嵌套的 ContentState 里,比如状态、进度、预计送达时间。每次更新都整份换掉。

App 启动活动时要用到这个类型,扩展显示时也要用到,所以两边各放一份一模一样的定义。字段名、类型、嵌套结构必须完全一致,推送里的 JSON 也按这些字段名解析。

第 4 步:锁屏和灵动岛界面怎么写?

把 MyAppWidget/MyAppWidgetLiveActivity.swift 换成下面的内容。

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,后面是管理实时活动的类和三个按钮。

swift 复制代码
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,按下面的顺序操作。

  1. 给扩展注册 App ID 。在 Identifiers 页点加号,选 App IDs → App,Bundle ID 选 Explicit,填 com.example.myapp.myappwidget。
  2. App 的 App ID 开启 Push Notifications 。要用推送更新时才需要,在 App 的 App ID(com.example.myapp)的 Capabilities 里勾选 Push Notifications,保存。
  3. 生成描述文件。给扩展的 App ID 新建 Development 描述文件。App 开启推送后,把 App 原来的描述文件 Edit 后直接 Save,重新下载。
  4. 放进 keychain 目录 。两份描述文件都放进 KXBuild 的 keychain 目录,删掉 App 的旧描述文件。构建时按 Bundle ID 自动给 App 和扩展各配一份。

用推送还要给 App 加 aps-environment entitlement,做法和普通推送完全一样,按给 iOS App 加推送通知的「给工程加 entitlements」一节操作。实时活动的推送令牌由 ActivityKit 提供,App 不用调用 registerForRemoteNotifications 来拿它。

扩展签名的完整规则见 iOS App 扩展的签名配置。

第 7 步:在 iPhone 上验证

  1. 在状态栏选好 iPhone,按 F5。KXBuild 会把 App 和扩展一起构建、签名并安装,然后启动 App。
  2. 点「开始配送」。下拉通知中心或锁屏,能看到锁屏样式的实时活动。带灵动岛的机型回到主屏幕,灵动岛左右出现图标和倒计时。
  3. 长按灵动岛看展开样式。
  4. 回到 App 点「骑手已取餐」,灵动岛会短暂展开提示,锁屏上的状态和进度跟着变。
  5. 点「已送达,结束」,灵动岛上的活动消失,锁屏上保留最终状态。

调试时注意几点。

  • F5 调试的是 App。实时活动的界面在扩展进程里渲染,App 里的断点管不到它。界面只负责显示,状态的计算放在 App 或服务器上。
  • 看 push token 。用了 pushType: .token 的,启动后 VS Code「输出 → KXBuild Console」里会打印 Live Activity push token: 加一串十六进制,下一节要用。
  • 没反应先看开关。「设置」里找到这个 App,确认实时活动是打开的。

怎么用 APNs 推送更新实时活动?

App 不在前台时,最可靠的更新方式是服务器推送。流程如下。

  1. App 用 pushType: .token 启动活动,从 pushTokenUpdates 拿到这个活动专属的 push token,上报给服务器。
  2. 订单状态变化时,服务器用这个 token 给 APNs 发一条 liveactivity 类型的推送。
  3. 系统收到后唤醒扩展,按推送里的 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 认证密钥」。

请求体

json 复制代码
{
  "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。

javascript 复制代码
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,然后锁上手机,执行下面的命令。

powershell 复制代码
node la.mjs update 粘贴的push token "骑手距您 1 公里" 3 0.9

返回 200 表示 APNs 已经接收,锁屏上的状态、倒计时和进度几秒内就会变化。再执行一次 end 结束活动。

powershell 复制代码
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: 构建,或者执行下面的命令。

powershell 复制代码
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 要用当前时间,活动已经结束的推送也会被忽略。

相关推荐
程序员cxuan12 分钟前
推荐 10 个 WorkBuddy 中的邪修用法
人工智能·后端·程序员
Bacon29 分钟前
给项目做一次"全身 CT":Agent Skills 生态里的代码体检全链路
前端·人工智能·后端
Java旅途1 小时前
课程表编排与调课申请系统|排得开,也能把每次调整管清楚
后端
iReaShare1 小时前
如何在没有 Wi-Fi 的情况下备份 iPhone
ios
象牙塔五六七1 小时前
Java 泛型精讲:从 Stream 源码说起
后端
掘金挖土1 小时前
前端手摸手跑路之 AI 应用开发(十二)
前端·后端
程序员cxuan1 小时前
GPT-6.2 Astra 发布了,但口碑崩了。。。
人工智能·后端·程序员
象牙塔五六七1 小时前
Java 函数式编程精讲:从 Stream 源码说起 —— 用真实源码学懂函数式思维
后端
字节跳动数据库1 小时前
火山引擎缓存数据库:如何构建超大规模缓存集群的无感弹性能力
数据库·人工智能·后端