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:
- Enable the host-app capability and set
NSSupportsLiveActivities = YES. - Separate immutable
ActivityAttributesfrom a small,Codable,HashableContentState; encode a representative server fixture before integrating APNs. - Build
ActivityConfigurationfor the Lock Screen first, then compact, minimal, and expanded Dynamic Island presentations. - Check
ActivityAuthorizationInfo.areActivitiesEnabled, request withActivityContent, and exercise local update plus every terminal end path. - 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
.defaultdismissal linger (up to 4 hours after ending). - Use
.tokenfor per-activity remote updates. Observeactivity.pushTokenUpdatesfor 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.liveactivityas the topic. Priority controls delivery urgency; onlyaps.alertrequests visible alert behavior. NSSupportsLiveActivitiesFrequentUpdatesrequests a larger system-managed budget, not a guaranteed cadence. CheckfrequentPushesEnabled.- 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
| Feature | Availability and constraint |
|---|---|
| Push-to-start | iOS 17.2+ |
style: request parameter |
iOS 18+; .standard for persistent work, .transient only for short-lived expanded presentation |
| Channel/broadcast updates | iOS 18+; update/end only, not start |
| Supplemental activity families | iOS 18+ |
| Scheduled start | iOS 26+ |
| Paired Mac and CarPlay presentation | iOS 26+; validate compact layouts and noninteractive CarPlay behavior |
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
contentStaterequest/update/end overloads instead ofActivityContent. - 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
ContentStatehave a small, tested Codable contract. - Host app contains
NSSupportsLiveActivities = YESand 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-statefixtures 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.