Back to Details

activitykit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ActivityKit

ActivityKit

Build real-time, glanceable experiences on the Lock Screen, Dynamic Island, StandBy, CarPlay, and a paired Mac using ActivityKit. Patterns target iOS 26+ with Swift 6.3, backward-compatible to iOS 16.1 unless noted.
See references/activitykit-patterns.md for complete code patterns including push payload formats, concurrent activities, state observation, and testing.
借助ActivityKit在锁屏、Dynamic Island、StandBy、CarPlay及配对Mac上构建实时、一目了然的体验。相关模式针对iOS 26+与Swift 6.3设计，除非特别说明，否则向后兼容至iOS 16.1。
查看references/activitykit-patterns.md获取完整代码模式，包括推送负载格式、并发活动、状态观测和测试相关内容。

Contents

目录

Workflow

工作流程

1. Create a new Live Activity

1. 创建新的Live Activity

  1. Add 
    NSSupportsLiveActivities = YES
    to the host app's Info.plist.
  2. Define an 
    ActivityAttributes
    struct with a nested 
    ContentState
    .
  3. Create an 
    ActivityConfiguration
    in the widget bundle with Lock Screen content and Dynamic Island closures.
  4. Start the activity with 
    Activity.request(attributes:content:pushType:)
    .
  5. Update with 
    activity.update(_:)
    and end with 
    activity.end(_:dismissalPolicy:)
    .
  6. Forward push tokens to your server for remote updates.
  1. 在宿主应用的Info.plist中添加
    NSSupportsLiveActivities = YES
    。
  2. 定义包含嵌套
    ContentState
    的
    ActivityAttributes
    结构体。
  3. 在小组件包中创建
    ActivityConfiguration
    ，包含锁屏内容和Dynamic Island闭包。
  4. 调用
    Activity.request(attributes:content:pushType:)
    启动活动。
  5. 使用
    activity.update(_:)
    更新活动，使用
    activity.end(_:dismissalPolicy:)
    结束活动。
  6. 将推送令牌转发至服务器以实现远程更新。

2. Review existing Live Activity code

2. 审查现有Live Activity代码

Run through the Review Checklist at the end of this document.
按照本文档末尾的审查清单逐一检查。

ActivityAttributes Definition

ActivityAttributes 定义

Define both static data (immutable for the activity lifetime) and dynamic 
ContentState
(changes with each update). Keep 
ContentState
small because the entire struct is serialized on every update and push payload.
swift
import ActivityKit

struct DeliveryAttributes: ActivityAttributes {
    // Static -- set once at activity creation, never changes
    var orderNumber: Int
    var restaurantName: String

    // Dynamic -- updated throughout the activity lifetime
    struct ContentState: Codable, Hashable {
        var driverName: String
        var estimatedDeliveryTime: ClosedRange<Date>
        var currentStep: DeliveryStep
    }
}

enum DeliveryStep: String, Codable, Hashable, CaseIterable {
    case confirmed, preparing, pickedUp, delivering, delivered

    var icon: String {
        switch self {
        case .confirmed: "checkmark.circle"
        case .preparing: "frying.pan"
        case .pickedUp: "bag.fill"
        case .delivering: "box.truck.fill"
        case .delivered: "house.fill"
        }
    }
}
定义静态数据（活动生命周期内不可变）和动态
ContentState
（随每次更新变化）。请保持
ContentState
精简，因为整个结构体在每次更新和推送负载时都会被序列化。
swift
import ActivityKit

struct DeliveryAttributes: ActivityAttributes {
    // Static -- set once at activity creation, never changes
    var orderNumber: Int
    var restaurantName: String

    // Dynamic -- updated throughout the activity lifetime
    struct ContentState: Codable, Hashable {
        var driverName: String
        var estimatedDeliveryTime: ClosedRange<Date>
        var currentStep: DeliveryStep
    }
}

enum DeliveryStep: String, Codable, Hashable, CaseIterable {
    case confirmed, preparing, pickedUp, delivering, delivered

    var icon: String {
        switch self {
        case .confirmed: "checkmark.circle"
        case .preparing: "frying.pan"
        case .pickedUp: "bag.fill"
        case .delivering: "box.truck.fill"
        case .delivered: "house.fill"
        }
    }
}

Stale Date

过期时间

Set 
staleDate
on 
ActivityContent
to tell the system when content becomes outdated. The system sets 
context.isStale
to 
true
after this date; show fallback UI (e.g., "Updating...") in your views.
swift
let content = ActivityContent(
    state: state,
    staleDate: Date().addingTimeInterval(300), // stale after 5 minutes
    relevanceScore: 75
)
在
ActivityContent
上设置
staleDate
，告知系统内容何时过期。超过该日期后，系统会将
context.isStale
设为
true
，此时应在视图中显示备用UI（如“更新中...”）。
swift
let content = ActivityContent(
    state: state,
    staleDate: Date().addingTimeInterval(300), // stale after 5 minutes
    relevanceScore: 75
)

Activity Lifecycle

Activity 生命周期

Starting

启动

Use 
Activity.request
to create and display a Live Activity. Pass 
.token
as the 
pushType
to enable remote updates via APNs.
swift
let attributes = DeliveryAttributes(orderNumber: 42, restaurantName: "Pizza Place")
let state = DeliveryAttributes.ContentState(
    driverName: "Alex",
    estimatedDeliveryTime: Date()...Date().addingTimeInterval(1800),
    currentStep: .preparing
)
let content = ActivityContent(state: state, staleDate: nil, relevanceScore: 75)

do {
    let activity = try Activity.request(
        attributes: attributes,
        content: content,
        pushType: .token
    )
    print("Started activity: \(activity.id)")
} catch {
    print("Failed to start activity: \(error)")
}
使用
Activity.request
创建并显示Live Activity。传入
.token
作为
pushType
，以支持通过APNs进行远程更新。
swift
let attributes = DeliveryAttributes(orderNumber: 42, restaurantName: "Pizza Place")
let state = DeliveryAttributes.ContentState(
    driverName: "Alex",
    estimatedDeliveryTime: Date()...Date().addingTimeInterval(1800),
    currentStep: .preparing
)
let content = ActivityContent(state: state, staleDate: nil, relevanceScore: 75)

do {
    let activity = try Activity.request(
        attributes: attributes,
        content: content,
        pushType: .token
    )
    print("Started activity: \(activity.id)")
} catch {
    print("Failed to start activity: \(error)")
}

Updating

更新

Update the dynamic content state from the app. Use 
AlertConfiguration
to trigger a visible banner and sound alongside the update.
swift
let updatedState = DeliveryAttributes.ContentState(
    driverName: "Alex",
    estimatedDeliveryTime: Date()...Date().addingTimeInterval(600),
    currentStep: .delivering
)
let updatedContent = ActivityContent(
    state: updatedState,
    staleDate: Date().addingTimeInterval(300),
    relevanceScore: 90
)

// Silent update
await activity.update(updatedContent)

// Update with an alert
await activity.update(updatedContent, alertConfiguration: AlertConfiguration(
    title: "Order Update",
    body: "Your driver is nearby!",
    sound: .default
))
从应用内更新动态内容状态。使用
AlertConfiguration
在更新时触发可见横幅和提示音。
swift
let updatedState = DeliveryAttributes.ContentState(
    driverName: "Alex",
    estimatedDeliveryTime: Date()...Date().addingTimeInterval(600),
    currentStep: .delivering
)
let updatedContent = ActivityContent(
    state: updatedState,
    staleDate: Date().addingTimeInterval(300),
    relevanceScore: 90
)

// Silent update
await activity.update(updatedContent)

// Update with an alert
await activity.update(updatedContent, alertConfiguration: AlertConfiguration(
    title: "Order Update",
    body: "Your driver is nearby!",
    sound: .default
))

Ending

结束

End the activity when the tracked event completes. Choose a dismissal policy to control how long the ended activity lingers on the Lock Screen.
swift
let finalState = DeliveryAttributes.ContentState(
    driverName: "Alex",
    estimatedDeliveryTime: Date()...Date(),
    currentStep: .delivered
)
let finalContent = ActivityContent(state: finalState, staleDate: nil, relevanceScore: 0)

// System decides when to remove (up to 4 hours)
await activity.end(finalContent, dismissalPolicy: .default)

// Remove immediately
await activity.end(finalContent, dismissalPolicy: .immediate)

// Remove after a specific time (max 4 hours from now)
await activity.end(finalContent, dismissalPolicy: .after(Date().addingTimeInterval(3600)))
Always end activities on all code paths -- success, error, and cancellation. A leaked activity stays on the Lock Screen until the system kills it (up to 8 hours), which frustrates users.
当追踪的事件完成时结束活动。选择关闭策略，控制已结束的活动在锁屏上保留的时长。
swift
let finalState = DeliveryAttributes.ContentState(
    driverName: "Alex",
    estimatedDeliveryTime: Date()...Date(),
    currentStep: .delivered
)
let finalContent = ActivityContent(state: finalState, staleDate: nil, relevanceScore: 0)

// System decides when to remove (up to 4 hours)
await activity.end(finalContent, dismissalPolicy: .default)

// Remove immediately
await activity.end(finalContent, dismissalPolicy: .immediate)

// Remove after a specific time (max 4 hours from now)
await activity.end(finalContent, dismissalPolicy: .after(Date().addingTimeInterval(3600)))
务必在所有代码路径中结束活动——成功、错误和取消场景均需处理。未正确结束的活动会在锁屏上保留至系统自动清理（最长8小时），这会影响用户体验。

Lock Screen Presentation

锁屏展示

The Lock Screen is the primary surface for Live Activities. Every device with iOS 16.1+ displays Live Activities here. Design this layout first.
swift
struct DeliveryActivityWidget: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: DeliveryAttributes.self) { context in
            // Lock Screen / StandBy / CarPlay / paired Mac content
            VStack(alignment: .leading, spacing: 8) {
                HStack {
                    Text(context.attributes.restaurantName)
                        .font(.headline)
                    Spacer()
                    Text("Order #\(context.attributes.orderNumber)")
                        .font(.caption)
                        .foregroundStyle(.secondary)
                }

                if context.isStale {
                    Label("Updating...", systemImage: "arrow.trianglehead.2.clockwise")
                        .font(.subheadline)
                        .foregroundStyle(.secondary)
                } else {
                    HStack {
                        Label(context.state.driverName, systemImage: "person.fill")
                        Spacer()
                        Text(timerInterval: context.state.estimatedDeliveryTime,
                             countsDown: true)
                            .monospacedDigit()
                    }
                    .font(.subheadline)

                    // Progress steps
                    HStack(spacing: 12) {
                        ForEach(DeliveryStep.allCases, id: \.self) { step in
                            Image(systemName: step.icon)
                                .foregroundStyle(
                                    step <= context.state.currentStep ? .primary : .tertiary
                                )
                        }
                    }
                }
            }
            .padding()
        } dynamicIsland: { context in
            // Dynamic Island closures (see next section)
            DynamicIsland {
                // Expanded regions...
                DynamicIslandExpandedRegion(.leading) {
                    Image(systemName: "box.truck.fill").font(.title2)
                }
                DynamicIslandExpandedRegion(.trailing) {
                    Text(timerInterval: context.state.estimatedDeliveryTime,
                         countsDown: true)
                        .font(.caption).monospacedDigit()
                }
                DynamicIslandExpandedRegion(.center) {
                    Text(context.attributes.restaurantName).font(.headline)
                }
                DynamicIslandExpandedRegion(.bottom) {
                    HStack(spacing: 12) {
                        ForEach(DeliveryStep.allCases, id: \.self) { step in
                            Image(systemName: step.icon)
                                .foregroundStyle(
                                    step <= context.state.currentStep ? .primary : .tertiary
                                )
                        }
                    }
                }
            } compactLeading: {
                Image(systemName: "box.truck.fill")
            } compactTrailing: {
                Text(timerInterval: context.state.estimatedDeliveryTime,
                     countsDown: true)
                    .frame(width: 40).monospacedDigit()
            } minimal: {
                Image(systemName: "box.truck.fill")
            }
        }
    }
}
锁屏是Live Activity的主要展示载体，所有iOS 16.1+设备均支持在此显示Live Activity。请优先设计该布局。
swift
struct DeliveryActivityWidget: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: DeliveryAttributes.self) { context in
            // Lock Screen / StandBy / CarPlay / paired Mac content
            VStack(alignment: .leading, spacing: 8) {
                HStack {
                    Text(context.attributes.restaurantName)
                        .font(.headline)
                    Spacer()
                    Text("Order #\(context.attributes.orderNumber)")
                        .font(.caption)
                        .foregroundStyle(.secondary)
                }

                if context.isStale {
                    Label("Updating...", systemImage: "arrow.trianglehead.2.clockwise")
                        .font(.subheadline)
                        .foregroundStyle(.secondary)
                } else {
                    HStack {
                        Label(context.state.driverName, systemImage: "person.fill")
                        Spacer()
                        Text(timerInterval: context.state.estimatedDeliveryTime,
                             countsDown: true)
                            .monospacedDigit()
                    }
                    .font(.subheadline)

                    // Progress steps
                    HStack(spacing: 12) {
                        ForEach(DeliveryStep.allCases, id: \.self) { step in
                            Image(systemName: step.icon)
                                .foregroundStyle(
                                    step <= context.state.currentStep ? .primary : .tertiary
                                )
                        }
                    }
                }
            }
            .padding()
        } dynamicIsland: { context in
            // Dynamic Island closures (see next section)
            DynamicIsland {
                // Expanded regions...
                DynamicIslandExpandedRegion(.leading) {
                    Image(systemName: "box.truck.fill").font(.title2)
                }
                DynamicIslandExpandedRegion(.trailing) {
                    Text(timerInterval: context.state.estimatedDeliveryTime,
                         countsDown: true)
                        .font(.caption).monospacedDigit()
                }
                DynamicIslandExpandedRegion(.center) {
                    Text(context.attributes.restaurantName).font(.headline)
                }
                DynamicIslandExpandedRegion(.bottom) {
                    HStack(spacing: 12) {
                        ForEach(DeliveryStep.allCases, id: \.self) { step in
                            Image(systemName: step.icon)
                                .foregroundStyle(
                                    step <= context.state.currentStep ? .primary : .tertiary
                                )
                        }
                    }
                }
            } compactLeading: {
                Image(systemName: "box.truck.fill")
            } compactTrailing: {
                Text(timerInterval: context.state.estimatedDeliveryTime,
                     countsDown: true)
                    .frame(width: 40).monospacedDigit()
            } minimal: {
                Image(systemName: "box.truck.fill")
            }
        }
    }
}

Lock Screen Sizing

锁屏尺寸

The Lock Screen presentation has limited vertical space. Avoid layouts taller than roughly 160 points. Use 
supplementalActivityFamilies
to opt into 
.small
(compact) or 
.medium
(standard) sizing:
swift
ActivityConfiguration(for: DeliveryAttributes.self) { context in
    // Lock Screen content
} dynamicIsland: { context in
    // Dynamic Island
}
.supplementalActivityFamilies([.small, .medium])
锁屏展示的垂直空间有限，避免布局高度超过约160点。使用
supplementalActivityFamilies
选择启用
.small
（紧凑）或
.medium
（标准）尺寸：
swift
ActivityConfiguration(for: DeliveryAttributes.self) { context in
    // Lock Screen content
} dynamicIsland: { context in
    // Dynamic Island
}
.supplementalActivityFamilies([.small, .medium])

Dynamic Island

Dynamic Island

The Dynamic Island is available on iPhone 14 Pro and later. It has three presentation modes. Design all three, but treat the Lock Screen as the primary surface since not all devices have a Dynamic Island.
Dynamic Island仅在iPhone 14 Pro及后续机型上可用，包含三种展示模式。请完成三种模式的设计，但需注意并非所有设备都支持Dynamic Island，因此锁屏仍是主要展示载体。

Compact (Leading + Trailing)

紧凑模式（左侧+右侧）

Always visible when a single Live Activity is active. Space is extremely limited -- show only the most critical information.
RegionPurpose
compactLeading
Icon or tiny label identifying the activity
compactTrailing
One key value (timer, score, status)
当单个Live Activity处于活跃状态时始终可见。空间极其有限——仅显示最关键的信息。
区域用途
compactLeading
标识活动的图标或极小标签
compactTrailing
一个核心数值（计时器、比分、状态）

Minimal

极简模式

Shown when multiple Live Activities compete for space. Only one activity gets the minimal slot. Display a single icon or glyph.
当多个Live Activity竞争空间时显示，仅一个活动能占据极简展示位。显示单个图标或标志符号即可。

Expanded Regions

展开区域

Shown when the user long-presses the Dynamic Island.
RegionPosition
.leading
Left of the TrueDepth camera; wraps below
.trailing
Right of the TrueDepth camera; wraps below
.center
Directly below the camera
.bottom
Below all other regions
当用户长按Dynamic Island时显示。
区域位置
.leading
原深感摄像头左侧，可向下延伸
.trailing
原深感摄像头右侧，可向下延伸
.center
摄像头正下方
.bottom
所有其他区域下方

Keyline Tint

轮廓色调

Apply a subtle tint to the Dynamic Island border:
swift
DynamicIsland { /* expanded */ }
    compactLeading: { /* ... */ }
    compactTrailing: { /* ... */ }
    minimal: { /* ... */ }
    .keylineTint(.blue)
为Dynamic Island边框设置细微色调：
swift
DynamicIsland { /* expanded */ }
    compactLeading: { /* ... */ }
    compactTrailing: { /* ... */ }
    minimal: { /* ... */ }
    .keylineTint(.blue)

Push-to-Update

推送更新

Push-to-update sends Live Activity updates through APNs, which is more efficient than polling from the app and works when the app is suspended.
推送更新通过APNs发送Live Activity更新，比应用内轮询更高效，且在应用挂起时仍可正常工作。

Setup

设置

Pass 
.token
as the 
pushType
when starting the activity, then forward the push token to your server:
swift
let activity = try Activity.request(
    attributes: attributes,
    content: content,
    pushType: .token
)

// Observe token changes -- tokens can rotate
Task {
    for await token in activity.pushTokenUpdates {
        let tokenString = token.map { String(format: "%02x", $0) }.joined()
        try await ServerAPI.shared.registerActivityToken(
            tokenString, activityID: activity.id
        )
    }
}
启动活动时传入
.token
作为
pushType
，然后将推送令牌转发至服务器：
swift
let activity = try Activity.request(
    attributes: attributes,
    content: content,
    pushType: .token
)

// Observe token changes -- tokens can rotate
Task {
    for await token in activity.pushTokenUpdates {
        let tokenString = token.map { String(format: "%02x", $0) }.joined()
        try await ServerAPI.shared.registerActivityToken(
            tokenString, activityID: activity.id
        )
    }
}

APNs Payload Format

APNs 负载格式

Send an HTTP/2 POST to APNs with these headers and JSON body:
Required HTTP headers:
  • apns-push-type: liveactivity
  • apns-topic: <bundle-id>.push-type.liveactivity
  • apns-priority: 5
    (low) or 
    10
    (high, triggers alert)
Update payload:
json
{
    "aps": {
        "timestamp": 1700000000,
        "event": "update",
        "content-state": {
            "driverName": "Alex",
            "estimatedDeliveryTime": {
                "lowerBound": 1700000000,
                "upperBound": 1700001800
            },
            "currentStep": "delivering"
        },
        "stale-date": 1700000300,
        "alert": {
            "title": "Delivery Update",
            "body": "Your driver is nearby!"
        }
    }
}
End payload: Same structure with 
"event": "end"
and optional 
"dismissal-date"
.
The 
content-state
JSON must match the 
ContentState
Codable structure exactly. Mismatched keys or types cause silent failures.
通过HTTP/2 POST请求发送至APNs，需包含以下请求头和JSON主体：
必填HTTP请求头：
  • apns-push-type: liveactivity
  • apns-topic: <bundle-id>.push-type.liveactivity
  • apns-priority: 5
    （低优先级）或
    10
    （高优先级，触发提醒）
更新负载：
json
{
    "aps": {
        "timestamp": 1700000000,
        "event": "update",
        "content-state": {
            "driverName": "Alex",
            "estimatedDeliveryTime": {
                "lowerBound": 1700000000,
                "upperBound": 1700001800
            },
            "currentStep": "delivering"
        },
        "stale-date": 1700000300,
        "alert": {
            "title": "Delivery Update",
            "body": "Your driver is nearby!"
        }
    }
}
结束负载： 结构相同，将
"event": "update"
改为
"event": "end"
，可选择性添加
"dismissal-date"
。
content-state
的JSON结构必须与
ContentState
的Codable定义完全匹配。键名或类型不匹配会导致静默失败。

Push-to-Start

推送启动

Start a Live Activity remotely without the app running (iOS 17.2+):
swift
Task {
    for await token in Activity<DeliveryAttributes>.pushToStartTokenUpdates {
        let tokenString = token.map { String(format: "%02x", $0) }.joined()
        try await ServerAPI.shared.registerPushToStartToken(tokenString)
    }
}
无需应用运行即可远程启动Live Activity（iOS 17.2+）：
swift
Task {
    for await token in Activity<DeliveryAttributes>.pushToStartTokenUpdates {
        let tokenString = token.map { String(format: "%02x", $0) }.joined()
        try await ServerAPI.shared.registerPushToStartToken(tokenString)
    }
}

Frequent Push Updates

高频推送更新

Add 
NSSupportsLiveActivitiesFrequentUpdates = YES
to Info.plist to increase the push update budget. Use for activities that update more than once per minute (sports scores, ride tracking).
在Info.plist中添加
NSSupportsLiveActivitiesFrequentUpdates = YES
，提升推送更新的频次上限。适用于每分钟更新超过一次的活动（如体育比分、网约车追踪）。

iOS 26 Additions

iOS 26 新增功能

Scheduled Live Activities (iOS 26+)

定时Live Activity（iOS 26+）

Schedule a Live Activity to start at a future time. The system starts the activity automatically without the app being in the foreground. Use for events with known start times (sports games, flights, scheduled deliveries).
swift
let scheduledDate = Calendar.current.date(
    from: DateComponents(year: 2026, month: 3, day: 15, hour: 19, minute: 0)
)!

let activity = try Activity.request(
    attributes: attributes,
    content: content,
    pushType: .token,
    start: scheduledDate
)
安排Live Activity在未来某个时间启动。系统会自动启动活动，无需应用处于前台。适用于有明确开始时间的事件（如体育赛事、航班、预约配送）。
swift
let scheduledDate = Calendar.current.date(
    from: DateComponents(year: 2026, month: 3, day: 15, hour: 19, minute: 0)
)!

let activity = try Activity.request(
    attributes: attributes,
    content: content,
    pushType: .token,
    start: scheduledDate
)

ActivityStyle (iOS 16.1+ type, 
style:
parameter iOS 26+)

ActivityStyle（iOS 16.1+类型，
style:
参数iOS 26+支持）

Control persistence: 
.standard
(persists until ended, default) or 
.transient
(system may dismiss automatically). Use 
.transient
for short-lived updates like transit arrivals. The 
style:
parameter on 
Activity.request
requires iOS 26+.
swift
let activity = try Activity.request(
    attributes: attributes, content: content,
    pushType: .token, style: .transient
)
控制持久化方式：
.standard
（持续至手动结束，默认）或
.transient
（系统可自动关闭）。
.transient
适用于短暂的更新场景，如公交到站提醒。
Activity.request
的
style:
参数需iOS 26+支持。
swift
let activity = try Activity.request(
    attributes: attributes, content: content,
    pushType: .token, style: .transient
)

Paired Mac & CarPlay (iOS 26+)

配对Mac与CarPlay（iOS 26+）

Live Activities automatically appear on a paired Mac running macOS Tahoe and on the CarPlay Home Screen. No additional code needed — ensure Lock Screen layout is legible at smaller scales.
Live Activity会自动显示在运行macOS Tahoe的配对Mac及CarPlay主屏幕上。无需额外代码——只需确保锁屏布局在小尺寸下仍清晰可读。

Channel-Based Push (iOS 18+)

基于频道的推送（iOS 18+）

Broadcast updates to many Live Activities at once with 
.channel
:
swift
let activity = try Activity.request(
    attributes: attributes, content: content,
    pushType: .channel("delivery-updates")
)
通过
.channel
向多个Live Activity广播更新：
swift
let activity = try Activity.request(
    attributes: attributes, content: content,
    pushType: .channel("delivery-updates")
)

Common Mistakes

常见错误

DON'T: Put too much content in the compact presentation -- it is tiny. DO: Show only the most critical info (icon + one value) in compact leading/trailing.
DON'T: Update Live Activities too frequently from the app (drains battery). DO: Use push-to-update for server-driven updates. Limit app-side updates to user actions.
DON'T: Forget to end the activity when the event completes. DO: Always end activities on success, error, and cancellation paths. A leaked activity frustrates users.
DON'T: Assume the Dynamic Island is available (only iPhone 14 Pro+). DO: Design for the Lock Screen as the primary surface; Dynamic Island is supplementary.
DON'T: Store sensitive information in ActivityAttributes (visible on Lock Screen). DO: Keep sensitive data in the app and show only safe-to-display summaries.
DON'T: Forget to handle stale dates. DO: Check 
context.isStale
in views and show fallback UI ("Updating..." or similar).
DON'T: Ignore push token rotation. Tokens can change at any time. DO: Use 
activity.pushTokenUpdates
async sequence and re-register on every emission.
DON'T: Forget the 
NSSupportsLiveActivities
Info.plist key. DO: Add 
NSSupportsLiveActivities = YES
to the host app's Info.plist (not the extension).
DON'T: Use the deprecated 
contentState
-based API for request/update/end. DO: Use 
ActivityContent
for all lifecycle calls.
DON'T: Put heavy logic in Live Activity views. They render in a size-limited widget process. DO: Pre-compute display values and pass them through 
ContentState
.
请勿： 在紧凑模式中放置过多内容——该模式空间极小。 建议： 在紧凑左侧/右侧仅显示最关键的信息（图标+一个数值）。
请勿： 从应用内过于频繁地更新Live Activity——这会消耗电量。 建议： 服务器驱动的更新使用推送更新方式。将应用内更新限制为用户操作触发的场景。
请勿： 事件完成后忘记结束活动。 建议： 务必在成功、错误和取消路径中结束活动。未正确结束的活动会影响用户体验。
请勿： 假设所有设备都支持Dynamic Island——仅iPhone 14 Pro及后续机型支持。 建议： 以锁屏作为主要展示载体进行设计；Dynamic Island作为补充。
请勿： 在ActivityAttributes中存储敏感信息——这些信息会在锁屏上显示。 建议： 敏感数据保留在应用内，仅展示安全的摘要信息。
请勿： 忽略过期时间处理。 建议： 在视图中检查
context.isStale
，并显示备用UI（如“更新中...”）。
请勿： 忽略推送令牌轮换。令牌可能随时变更。 建议： 使用
activity.pushTokenUpdates
异步序列，每次令牌更新时重新注册。
请勿： 遗漏
NSSupportsLiveActivities
Info.plist键。 建议： 在宿主应用的Info.plist中添加
NSSupportsLiveActivities = YES
（不要添加到扩展中）。
请勿： 使用已弃用的基于
contentState
的请求/更新/结束API。 建议： 在所有生命周期调用中使用
ActivityContent
。
请勿： 在Live Activity视图中放置复杂逻辑。这些视图在尺寸受限的小组件进程中渲染。 建议： 预先计算展示值，并通过
ContentState
传递。

Review Checklist

审查清单

  • ActivityAttributes
    defines static properties and 
    ContentState
  • NSSupportsLiveActivities = YES
    in host app Info.plist
  • Activity uses 
    ActivityContent
    (not deprecated contentState API)
  • Activity ended in all code paths (success, error, cancellation)
  • Lock Screen layout handles 
    context.isStale
  • Dynamic Island compact, expanded, and minimal implemented
  • Push token forwarded to server via 
    activity.pushTokenUpdates
  • AlertConfiguration
    used for important updates
  • ActivityAuthorizationInfo
    checked before starting
  • ContentState kept small (serialized on every update)
  • Tested on device (Dynamic Island differs from Simulator)
  • Ensure ActivityAttributes and ContentState types are Sendable; update Live Activity UI on @MainActor
  • ActivityAttributes
    定义了静态属性和
    ContentState
  • 宿主应用Info.plist中包含
    NSSupportsLiveActivities = YES
  • 活动使用
    ActivityContent
    （而非已弃用的contentState API）
  • 所有代码路径中均结束了活动（成功、错误、取消）
  • 锁屏布局处理了
    context.isStale
    场景
  • 实现了Dynamic Island的紧凑、展开和极简模式
  • 通过
    activity.pushTokenUpdates
    将推送令牌转发至服务器
  • 重要更新使用了
    AlertConfiguration
  • 启动前检查了
    ActivityAuthorizationInfo
  • 保持ContentState精简（每次更新都会序列化）
  • 在真机上进行了测试（Dynamic Island在模拟器中的表现与真机不同）
  • 确保ActivityAttributes和ContentState类型为Sendable；在@MainActor上更新Live Activity UI

References

参考资料

  • See references/activitykit-patterns.md for patterns and code examples
  • 查看references/activitykit-patterns.md获取更多模式和代码示例