Activitykit

ActivityKit

ActivityKit owns real-time, glanceable Live Activities displayed on the Lock Screen and Dynamic Island. Ordinary timeline widgets belong in widgetkit, and generic APNs setup belongs in push-notifications; ActivityKit owns the Live Activity lifecycle and payload contract. aps.content-state must decode into the exact ActivityAttributes.ContentState shape, including any coordinated custom date/range encoding. Modern ActivityContent lifecycle examples require iOS 16.2+ unless noted.

See references/activitykit-patterns.md for complete code patterns including push payload formats, concurrent activities, state observation, and testing.

Contents

• Workflow
• ActivityAttributes Definition
• Activity Lifecycle
• Lock Screen Presentation
• Dynamic Island
• Push-to-Update
• Recent Additions
• Common Mistakes
• Review Checklist
• References

Workflow

1. Create a new Live Activity

1. Verify the host app capability and NSSupportsLiveActivities = YES.
2. Define ActivityAttributes.ContentState; encode and decode a representative fixture that matches the server payload contract.
3. Create ActivityConfiguration and preview Lock Screen and Dynamic Island states, including stale and terminal content.
4. Check ActivityAuthorizationInfo.areActivitiesEnabled, then request and observe the activity lifecycle.
5. Exercise local update and every terminal end path.
6. For remote updates, validate a complete reference payload before registering rotating update or push-to-start tokens with the server.

2. Review existing Live Activity code

Run through the Review Checklist at the end of this document.

ActivityAttributes Definition

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.

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.

let content = ActivityContent(
    state: state,
    staleDate: Date().addingTimeInterval(300), // stale after 5 minutes
    relevanceScore: 75
)

Activity Lifecycle

Starting

Use Activity.request to create and display a Live Activity. Pass .token as the pushType to enable remote updates via APNs. The ActivityContent request shown here requires iOS 16.2+.

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.

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.

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 terminal code paths -- success, user/app cancellation, sign-out/session stop, unrecoverable app error, and terminal server failure. If the server says the tracked event can no longer continue or be represented accurately, apply or send a final terminal state and end the activity instead of leaving stale progress visible. When reviewing duration claims, distinguish the active lifetime (up to 8 hours unless the app or user ends it sooner), system-ended Lock Screen presence (up to 4 additional hours, for 12 hours total from start), and app-ended .default dismissal linger (up to 4 hours after ending).

Lock Screen Presentation

The Lock Screen is the primary Live Activity display surface. Every device with iOS 16.1+ displays Live Activities here. Design this layout first, then adapt for Dynamic Island where available.

struct DeliveryActivityWidget: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: DeliveryAttributes.self) { context in
            VStack(alignment: .leading) {
                Text(context.attributes.restaurantName).font(.headline)

                if context.isStale {
                    Label("Updating...", systemImage: "arrow.trianglehead.2.clockwise")
                        .foregroundStyle(.secondary)
                } else {
                    Text(timerInterval: context.state.estimatedDeliveryTime, countsDown: true)
                        .monospacedDigit()
                }
            }
            .padding()
        } dynamicIsland: { context in
            DynamicIsland {
                DynamicIslandExpandedRegion(.center) {
                    Text(context.attributes.restaurantName).font(.headline)
                }
                DynamicIslandExpandedRegion(.trailing) {
                    Text(timerInterval: context.state.estimatedDeliveryTime, countsDown: true)
                }
            } compactLeading: {
                Image(systemName: "box.truck.fill")
            } compactTrailing: {
                Text(timerInterval: context.state.estimatedDeliveryTime, countsDown: true)
            } minimal: {
                Image(systemName: "box.truck.fill")
            }
        }
    }
}

Supplemental Activity Families