写在前面

集成灵动岛踩了一些坑，回看发现是对灵动岛的了解还不够透彻。老实说，于是重新梳理了一下从开始到结束的一整条链路。并把常见的痛点、方法全部写进来了帮助大家少走弯路。

iPhone 14 Pro 之后苹果从齐刘海过渡到了挖孔时代。老实说，挖孔里放前置摄像头，为了美观。用黑色像素把这块区域包起来形成一个“药丸”。程序可以动态控制这块区域：计时器倒计时、音乐专辑封面、AirPods 连接动画等。它可以变形、伸缩、分裂，这块由程序掌控、环绕前置传感器的屏幕显示区域。就是灵动岛。

灵动岛有三种状态：

• 紧凑态以挖孔为界，分成左右两小块——有内容跑动时的默认样子。
• 最小态一个小圆点/小药丸，当第二个活动抢占位置时使用。
• 展开态

谁能往上面放东西？其实，至于分为两类，

• 程序自带
  • 来电
  • Face ID
  • 充电
  • 静音
  • AirPods 连接状态
  • 屏幕录制指示
  • 导航指示
  • 正在播放的音乐等
• 第三方 APP

第三方 APP 想上岛。只能使用Live Activities框架。Live Activities 不只会在灵动岛展示，还会在锁屏页面出现。

哪些设备能用？

• 首次支持 iPhone 14 Pro，随后 Pro、Pro Max 还有全系 iPhone 均可使用。说起来，
• 程序版本要求：iOS 16.1 及以上。
• 语言/框架要求：UI 必须使用 SwiftUI。但主 App 可以是 UIKit，只要 Live Activity 那块 UI 用 SwiftUI 编写。
• 最低配置：
• - iPhone 14 Pro 或以后机型 - iOS 16.1+ - 主 App 可为 UIKit，Live Activity UI 必须是 SwiftUI - 开启 Push Notifications 能力并添加 Live Activity 能力

如何集成

整体数据流图

① 配置证书 / 能力
② 定义数据模型
③ 搭 UI
④ App：启动活动 → 监听拿 token → 上报服务端
│
▼
⑤ 服务端 → APNs 推送
│
▼
⑥ 程序用新 content-state 重渲染 Widget 里的视图 ← App 进程全程不参与！│
▼
⑦ 使用者在 锁屏 / 灵动岛 看到更新 →
▼
⑧ App 或服务端发 end 结束活动

1️⃣ 证书与能力配置

• PUSH NOTIFICATIONS 能力：Live Activity 使用 APNs，需要打开此能力。
• Live Activity 能力：Xcode 中勾选 “Include Live Activity”。程序会自动生成 ActivityAttributes.swift 骨架和 Widget 模板。

Pain Point: 没开 Live Activity 能力导致推送被程序直接丢弃，却没有报错。检查 Xcode 项目 → Signing & Capabilities 是否都有对应条目。

2️⃣ 工程结构 & 模型定义

• Main App Target：`ActivityKit` 用于启动/更新/结束活动并上报 token。
• Widget Extension Target：`WidgetKit` 用于渲染锁屏卡片和灵动岛三态 UI，是独立进程、独立 Bundle ID。

@available struct LiveActivityDemoAttributes: ActivityAttributes { // 动态数据。 每次推送都会整体替换 struct ContentState: Codable,Hashable { var emoji: String // 紧凑态左侧表情 var title: String // 标题 var body: String // 正文 var progress: Double?// 可选进度条 } // 静态数据，仅创建时确定。不可变 var name: String }

Pain Point: 把 Attributes 文件只加入了主 App 导致 Widget 编译失败。务必在 File Inspector 中勾选 both targets。

3️⃣ 服务端消息体示例

{
至于"aps"，{
"timestamp": 1721234567,"event": "start","attributes-type": "LiveActivityDemoAttributes","attributes": {
再看"name"，"LiveActivityDemo"
}。"content-state": {
"emoji": "⬇️","title": "下载中","body": "模型包.zip","progress": 0.42
},"alert": {
"title": "已下载 %42","body": "点击查看详情"
}
}
}

Pain Point: `attributes-type` 必须与客户端结构体名完全一致；`content-state` 键必须对应 `ContentState` 的属性。否则程序解码失败但仍返回成功响应，导致“推送成功却看不到任何内容”。请使用 Xcode 自动生成的模型进行 JSON 序列化校验。

4️⃣ 客户端注册 & Token 获取

• Add `NSSupportsLiveActivities` 到 Info.plist.

The flow differs by iOS version:

// iOS 16.0 – legacy API
let activity = try Activity.request(
attributes: attributes,contentState: initialState,pushType: .token)
Task {
for await tokenData in activity.pushTokenUpdates {
let token = tokenData.map { String }.joined
reportToken
}
}
// iOS 16.1 – 新 API
let activity = try Activity.request(
attributes: attributes,content: ActivityContent。pushType: .token)
Task {
for await tokenData in activity.pushTokenUpdates {
let token = tokenData.map { String }.joined
reportToken
}
// iOS 17+ – 支持 push‑to‑start token
if #available {
Task {
for await tokenData in Activity.pushToStartTokenUpdates {
let token = tokenData.map { String }.joined
reportToken // app‑level token
}
 // 捕获服务器拉起的新活动并获取其 per‑activity token
for await activity in Activity.activityUpdates {
observeActivityToken // 内部仍是 activity.pushTokenUpdates → .update/.end
}
}


}


Pain Point:


If `NSSupportsLiveActivities` is missing,`areActivitiesEnabled` always returns false and request never happens.


5️⃣ 服务端推送实现要点 


#1 保存不同类型的 token：`push-to-start` 与 `per‑activity` 分别存库，以便后续区分起始与更新。



If an activity already exists,**prefer update**;only fallback to start when update fails or activity is considered expired.


A typical expiration strategy is to treat an activity as dead after ~24 hours of creation time;n clean it from DB and issue a new start.

Pain Point Summary：



🐛 Start 一时爽——每次 start 都会新建一个活动，达到程序上限后后续 start 完全失效；方法是先尝试 update。再降级为 start，并定期清理过期或多余的活动。




⚠️ 静默失败——APNs 返回成功但设备不展示；检查：


attributes-type 是否严格匹配客户端结构体名；



 

`content-state` 键值是否完整且类型匹配；



`progress` 等可选字段若为空，请省略键而不是空字符串；



`timestamp` 必须是当前 Unix 秒，否则被认为旧消息直接丢弃；



`alert.title/body` 在 start 时必须提供，否则不会弹出横幅提示；







⏱ Update 在后台失效——如果仅依赖本地 activity.updateApp 被杀后就不再更新。需要场景，可利用 staleDate 把时间交给程序本地跑秒。



⚙️ 环境错配——Debug 使用 Sandbox APNs 而 Release/TestFlight 使用 Production。token 与环境不匹配会导致推送无效且没有错误回执。请根据 Build Configuration 动态切换 endpoint。




值得一说的坑 & 排查思路 

Start 一时爽，却被限制数量 

The system caps simultaneous live activities . Each `start` creates a new instance without removing old one;once limit is hit furr starts return an error and nothing appears on island.

SOLUTION:



💡 在收到 update 错误码时改为 start 并同时清理已完成或超时的旧实例。



📅 定期检查 `Activity.activities.count`;说起来，超过阈值立即结束最老的几条。