Implement, review, or improve Live Activities and Dynamic Island experiences in iOS apps using ActivityKit. Use when building real-time updating widgets for the Lock Screen and Dynamic Island — delivery tracking, sports scores, ride-sharing status, workout timers, media playback, or any time-sensiti

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. 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. 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+. Updating Update the dynamic content state from the app. Use AlertConfiguration to trigger a visible banner and sound alongside the update. 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. 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. Supplemental Activity Families The Lock Screen presentation has limited vertical space. Avoid layouts taller than roughly 160 points. On iOS 18+, use supplementalActivityFamilies when you provide adaptive layouts beyond the default: .medium for iOS/macOS Live Activity sizing and .small for watchOS Live Activity sizing. Dynamic Island Dynamic Island presentations appear only on devices that include Dynamic Island. Design all three modes, but treat the Lock Screen as the primary surface since not all devices have a Dynamic Island. Compact (Leading + Trailing) Used when one Live Activity occupies Dynamic Island compact space. Space is extremely limited show only the most critical information. Region Purpose compactLeading Icon or tiny label identifying the activity compactTrailing One key value (timer, score, status) Minimal Shown when multiple Live Activities compete for space. Only one activity gets the minimal slot. Display a single icon or glyph. Expanded Regions Shown when the user long presses the Dynamic Island. Region Position .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 Keyline Tint Apply a subtle tint to the Dynamic Island border: 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, subject to APNs delivery, priority, budget, and throttling. Setup Pass .token as the pushType when starting the activity, then forward the per activity update token to your server. Update tokens can rotate, so observe activity.pushTokenUpdates and re register every emitted token: APNs Payload Format Send an HTTP/2 POST to APNs with these headers and JSON body: Required device token HTTP headers: apns push type: liveactivity apns topic: <bundle id .push type.liveactivity apns priority: 5 (lower priority) or 10 (immediate, counts against budget) The aps.alert payload controls visible alert/banner/sound behavior; priority alone does not create an alert. Put timestamp , event , and the full content state inside aps . Validate update, end, and push to start bodies against the complete examples in [Push to Update Payloads](references/activitykit patterns.md push to update server payload format), including the exact Codable date/range representation. Push to Start Start a Live Activity remotely without the app running (iOS 17.2+). Push to start tokens are ActivityKit specific tokens from Activity<Attributes .pushToStartTokenUpdates ; they are distinct from ordinary app/device APNs tokens and per activity update tokens: Frequent Push Updates Add NSSupportsLiveActivitiesFrequentUpdates = YES to Info.plist to increase the system managed push update budget. When cadence matters, check ActivityAuthorizationInfo.frequentPushesEnabled and observe frequentPushEnablementUpdates ; Apple does not guarantee a fixed update rate. Recent Additions Scheduled Live Activities (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). ActivityStyle (iOS 18+ request parameter) Use the iOS 18+ style: request parameter to choose persistence behavior. Use .standard for persistent Live Activities such as deliveries, rides, sports scores, timers, and flight/status boards. Use .transient only for a short lived expanded Dynamic Island presentation; it can auto end when the user locks the device, collapses or shrinks the expanded presentation, leaves the app, or does other work outside Dynamic Island. Paired Mac & CarPlay (iOS 26+) Live Activities can appear on a paired Mac and on the CarPlay Home Screen. No additional ActivityKit API is required, but validate compact layouts; buttons and toggles in Live Activities do not perform actions in CarPlay. Channel Based Push (iOS 18+) Broadcast updates to many Live Activities at once with an APNs created channel ID. Enable the broadcast capability outside Xcode, create the channel on the server, then subscribe with .channel(channelID) . Channel pushes update or end Live Activities; they do not start them. Use apns channel id and expiration for channel pushes instead of the device token apns topic example above. 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 reaches any terminal state. DO: End activities on success, cancellation, sign out, unrecoverable errors, and terminal server failures. A leaked activity frustrates users. DON'T: Assume every device has Dynamic Island. 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: Fetch network data or location directly from Live Activity views. DO: Pre compute display values in the app or server and pass them through ActivityKit updates or pushes. 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 terminal paths (success, error, cancellation, sign out, terminal server failure) [ ] ActivityKit lifecycle and Lock Screen/Dynamic Island Live Activity surfaces are separated from ordinary Home Screen/timeline widget work [ ] Lock Screen layout, the primary Live Activity surface, handles context.isStale [ ] Dynamic Island compact, expanded, and minimal implemented with Lock Screen fallback [ ] Push update token forwarded to server via activity.pushTokenUpdates [ ] Push to start token collected via Activity<Attributes .pushToStartTokenUpdates [ ] Push to start payload includes required alert [ ] content state JSON matches the actual ContentState Codable shape, including coordinated date/range encoding [ ] Review distinguishes 8 hour active lifetime, 12 hour total system ended Lock Screen presence, and 4 hour app ended .default linger [ ] ActivityAuthorizationInfo checked before starting [ ] frequentPushesEnabled checked before assuming high cadence pushes [ ] ContentState kept small (serialized on every update) [ ] iOS 18+ availability guarded for style: , .channel , and supplemental families [ ] iOS 18+ style: choices are justified: .standard for persistent Live Activities, .transient only for short lived expanded Dynamic Island presentations [ ] ActivityKit push priority and aps.alert behavior are handled separately [ ] Live Activity views avoid direct network/location work [ ] Tested on device for push delivery and Dynamic Island behavior References See [references/activitykit patterns.md](references/activitykit patterns.md) for patterns and code examples