ActivityKit

ActivityKit owns real-time, glanceable Live Activities on the Lock Screen and Dynamic Island. Route ordinary timeline widgets to widgetkit and generic APNs setup to push-notifications; keep the Live Activity lifecycle, token handling, and payload contract here.

Modern ActivityContent lifecycle APIs require iOS 16.2+ unless noted. The server's aps.content-state must decode into the exact ActivityAttributes.ContentState shape, including coordinated custom date or range encoding.

Contents

• Choose the workflow
• Core contract
• Lifecycle and delivery rules
• Presentation rules
• Availability-sensitive features
• Common mistakes
• Review checklist
• References

Choose the workflow

• For attributes, local request/update code, push-to-update, push-to-start, channel payloads, and exact APNs headers, read Lifecycle, updates, and push.
• For dismissal policies, terminal cleanup, Lock Screen layouts, and every Dynamic Island region, read Ending and presentation.
• For multiple activities, authorization, rotating tokens, background behavior, Simulator/device verification, previews, and Info.plist keys, read Concurrency, state, and testing.

For a new Live Activity:

1. Enable the host-app capability and set NSSupportsLiveActivities = YES.
2. Separate immutable ActivityAttributes from a small, Codable, Hashable ContentState; encode a representative server fixture before integrating APNs.
3. Build ActivityConfiguration for the Lock Screen first, then compact, minimal, and expanded Dynamic Island presentations.
4. Check ActivityAuthorizationInfo.areActivitiesEnabled, request with ActivityContent, and exercise local update plus every terminal end path.
5. For remote delivery, observe every emitted token and validate update, end, and push-to-start payloads against the same Codable contract.

Core contract

Keep static identity in the outer attributes and only changing display state in ContentState:

import ActivityKit

struct DeliveryAttributes: ActivityAttributes {
    let orderNumber: Int

    struct ContentState: Codable, Hashable {
    var stage: String
        var estimatedDelivery: ClosedRange<Date>
    }
}

Use ActivityContent for request, update, and end. Set staleDate whenever the display can become misleading, and render a safe fallback from ActivityViewContext.isStale. Treat Lock Screen content as public: never place secrets or sensitive detail in attributes or state.

Lifecycle and delivery rules

• End on success, user/app cancellation, sign-out, unrecoverable app error, and terminal server failure. Apply a final truthful state before ending when one exists.
• Distinguish the active lifetime (up to 8 hours), system-ended Lock Screen presence (up to 4 additional hours), and an app-ended .default dismissal linger (up to 4 hours after ending).
• Use .token for per-activity remote updates. Observe activity.pushTokenUpdates for the full activity lifetime because tokens rotate.
• Push-to-start uses Activity<Attributes>.pushToStartTokenUpdates; it is not an app APNs token or an activity update token. Its payload requires an alert.
• Live Activity pushes require apns-push-type: liveactivity. Device-token pushes use <bundle-id>.push-type.liveactivity as the topic. Priority controls delivery urgency; only aps.alert requests visible alert behavior.
• NSSupportsLiveActivitiesFrequentUpdates requests a larger system-managed budget, not a guaranteed cadence. Check frequentPushesEnabled.
• Do not fetch network or location data from the widget extension view. Compute display state in the app/server and deliver it through ActivityKit.

Presentation rules

• Design the Lock Screen first; Dynamic Island is unavailable on some devices.
• Compact leading/trailing regions contain only identity plus one critical value.
• Minimal presentation must work as a single glyph when activities compete.
• Expanded regions must tolerate content changes without relying on fixed sizes.
• Render stale and terminal states explicitly; avoid pretending old progress is live.
• Test push delivery and Dynamic Island behavior on physical hardware.

Availability-sensitive features

Use availability guards around each newer API. Read the lifecycle reference for complete request and payload examples rather than combining signatures from different OS branches.

Common Mistakes

• Using deprecated contentState request/update/end overloads instead of ActivityContent.
• Ignoring token rotation or registering only the first emitted token.
• Assuming APNs priority creates an alert without aps.alert.
• Leaving an activity alive after a terminal state.
• Treating Dynamic Island as the only presentation surface.
• Omitting stale UI, overloading compact regions, or exposing sensitive data.
• Assuming frequent-update capability guarantees a fixed update frequency.

Review Checklist

• Static attributes and dynamic ContentState have a small, tested Codable contract.
• Host app contains NSSupportsLiveActivities = YES and authorization is checked.
• Request, update, and end use ActivityContent.
• Every terminal path ends the activity with an intentional dismissal policy.
• Lock Screen, stale, compact, minimal, expanded, and terminal states are covered.
• Update and push-to-start tokens are collected from the correct async sequences.
• APNs headers, alert semantics, and content-state fixtures are validated.
• Newer APIs have explicit availability guards.
• Extension views perform no network or location work.
• Simulator previews and physical-device delivery checks both exist.

References

• Lifecycle, updates, and push
• Ending and presentation
• Concurrency, state, and testing
• ActivityKit documentation