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](references/activitykit-patterns.md) for complete code patterns including push payload formats, concurrent activities, state observation, and testing.

## Contents

- [Workflow](#workflow)
- [ActivityAttributes Definition](#activityattributes-definition)
- [Activity Lifecycle](#activity-lifecycle)
- [Lock Screen Presentation](#lock-screen-presentation)
- [Dynamic Island](#dynamic-island)
- [Push-to-Update](#push-to-update)
- [Recent Additions](#recent-additions)
- [Common Mistakes](#common-mistakes)
- [Review Checklist](#review-checklist)
- [References](#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.

```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
)
```

## 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+.

```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
))
```

### 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 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 visibl