8 min read
Live Activities and the Dynamic Island in production
How Live Activities behave in practice, including the ActivityKit lifecycle, push updates, and the states the system will end for you.
On this page9
A Live Activity looks like a widget that updates itself. In production it behaves like a state machine rendered by a process you do not own, with a deadline the system sets and an update path that mostly runs through your server.
That difference shows up in the first week of real usage. The activity looks right in the simulator, then it stops updating while the app is in the background, keeps displaying a countdown that no longer matches reality, or disappears an hour before the delivery arrives.
Most of the fixes are architectural rather than visual, and they are cheaper to build in than to retrofit.
1. Accept that no code of yours is running
The view you write for ActivityConfiguration is rendered from a state blob by the widget extension. There is no timer loop, no network client, no observing, and no chance to compute anything at render time beyond formatting what is in the state.
So the view is a pure function of ContentState. Everything it displays has to be in that state or derivable from it.
The exception worth knowing is Text(timerInterval:countsDown:). The system animates that countdown without any updates from you, which means a 40-minute delivery timer costs zero pushes and stays accurate while the app is suspended.
Text(timerInterval: context.state.eta...context.state.eta, countsDown: true)
.monospacedDigit()Anything else that changes over time, such as a progress bar or a driver's position, has to arrive as an update.
2. Treat attributes and content state as a wire format
ActivityAttributes is the immutable half: the order id, the restaurant name, the item count. Its nested ContentState is everything that moves: status, ETA, the step the order is on.
Both must be Codable, and the two combined must stay under 4 KB. That limit is tighter than people expect once you include localized strings and a small image reference.
struct DeliveryAttributes: ActivityAttributes {
public struct ContentState: Codable, Hashable {
var status: Status
var eta: Date
var driverName: String?
var progress: Double
}
var orderID: String
var restaurant: String
}The APNs payload carries content-state as JSON, and the decoder on the device uses your Codable conformance. Declare CodingKeys explicitly and do not use a key strategy on the server that you forgot to mirror in Swift. A camel-cased key against a default decoder fails silently at exactly the moment you are watching a live demo.
3. Request in the foreground, handle the refusals
Activity.request only succeeds while the app is in the foreground. That rules out starting an activity from a background task or a push handler, which is why push-to-start tokens exist on iOS 17.2 and later.
do {
let activity = try Activity.request(
attributes: attributes,
content: .init(state: initialState, staleDate: eta.addingTimeInterval(900)),
pushType: .token
)
Task { for await token in activity.pushTokenUpdates { await register(token) } }
} catch {
// ActivityAuthorizationError: .denied, .attributesTooLarge, .targetMaximumExceeded
}denied means the person switched Live Activities off for the app in Settings, which is a legitimate preference and not a bug to retry around. .attributesTooLarge is the 4 KB limit catching you. .targetMaximumExceeded shows up on devices with several activities already running.
On every cold launch, reconcile Activity.activities against your server. Restored activities from a previous session are the usual source of a card that is still sitting on the Lock Screen the morning after.
4. Push updates are the production path
Local updates work fine while the app is running. In real use it is backgrounded within seconds, so the updates that matter come from APNs.
Three headers have to be right, and each failure mode is quiet:
apns-push-type: liveactivity
apns-topic: com.example.app.push-type.liveactivity
apns-priority: 10A wrong apns-topic returns BadTopic. A missing apns-push-type gets the push rejected rather than delivered as an alert. Then the payload:
{
"aps": {
"timestamp": 1762879200,
"event": "update",
"content-state": { "status": "enRoute", "eta": 1762881300, "driverName": "Ivan", "progress": 0.4 },
"stale-date": 1762882200,
"relevance-score": 90
}
}timestamp is not decoration. The system uses it to order updates and drops anything older than what it already holds, so send a monotonic server time and never Date() from a device clock. Out-of-order arrivals after a retry are the usual cause of a progress bar that jumps backwards.
5. Updates cost something, even when nothing counts them
Apple does not publish a hard number for push updates, but the system throttles activity that updates too often, and the throttle is invisible from your side. The one escape hatch is NSSupportsLiveActivitiesFrequentUpdates in Info.plist, intended for activities where a sub-minute refresh is the point, such as a scoreboard or a live workout.
Budget mentally by transition count. An order has maybe six states worth rendering. A driver position that moves every three seconds is not one of them. If a value changes continuously, put a clock or an interpolation in the view instead of a push on the wire.
Two habits keep sends low: coalesce server-side state changes into one update per meaningful transition, and stop sending the moment the activity ends.
6. The system ends the activity whether you are ready or not
A Live Activity is active for up to eight hours. After that the system ends it, and it can stay on the Lock Screen for a few more hours before removal. The person can dismiss it earlier. Your app can be force-quit, in which case the card keeps rendering while your local updates stop.
Plan for four states rather than the happy one:
| State | What you do |
|---|---|
active | Normal updates, push and local |
stale | Render an explicit stale treatment, never a frozen ETA |
ended | Stop sending; clean up server-side state |
dismissed | Same as ended, from the person's side |
Set staleDate honestly. A card that says "arriving in 4 minutes" for twenty minutes does more damage to trust than one that says the estimate is out of date.
When you end it yourself, choose the dismissal policy deliberately:
await activity.end(
ActivityContent(state: finalState, staleDate: nil),
dismissalPolicy: .after(Date().addingTimeInterval(3600))
).default keeps the final state visible for about four hours, which is right for a completed delivery and wrong for a cancelled one. Use .immediate when the thing no longer exists.
APNs will start returning 410 Unregistered for the activity token once it is gone. Treat that as a signal to stop, not as an error to retry.
7. The Dynamic Island has four layouts and very little room
You provide compact leading, compact trailing, minimal, and expanded views. The system picks based on state: compact when one activity is running, minimal when two are competing for space, expanded when someone long-presses.
The constraints are stricter than the Lock Screen view you already built:
- compact regions fit a glyph and a short number, nothing else
- minimal is a single small circle, so it needs an icon that reads at 10 points
- expanded gets roughly 160 points of height and clips anything beyond it, with no scrolling
Design the expanded view last and derive it from the same state. If a layout needs a field that is not in ContentState, that is a data model decision, not a SwiftUI one.
Relevance score decides which activity gets the island when several are live. Two activities with the same score resolve by recency, so a stale one can win the island simply by being newer. Set the score from state: an order arriving in three minutes outranks one arriving tomorrow.
Deep links belong on the whole card via widgetURL, and on individual elements inside the expanded view with Link. Both are easy to forget until someone taps the driver's name and lands on the home screen.
8. Test the states that actually break
Xcode previews cover layout drift cheaply:
#Preview("En route", as: .content, using: DeliveryAttributes(orderID: "1", restaurant: "Test")) {
DeliveryLiveActivity()
} contentStates: {
DeliveryAttributes.ContentState(status: .enRoute, eta: .now.addingTimeInterval(600), driverName: "Ivan", progress: 0.4)
DeliveryAttributes.ContentState(status: .delivered, eta: .now, driverName: nil, progress: 1)
}Then test on a device, because the simulator will not tell you most of what matters: airplane mode mid-activity, a token rotation after app restart, Live Activities disabled in Settings, and a push arriving after the activity has already ended. Those four account for nearly every "it worked yesterday" report.
A debug screen inside the app that starts an activity with fake attributes and walks it through states on a button press pays for itself the first time you need to check a layout change against real device sizes.
9. Use it for less than you want to
Live Activities work best for a small set of situations: something is happening now, it will finish soon, and the person wants to glance rather than open the app. A delivery, a boarding pass, a match, a timer, a workout.
They are a poor fit for anything that is not live or not finite. A streak counter, an unread badge, or a weekly summary belongs in a widget, where refresh semantics do not have an eight-hour clock attached.
The extra work is real: a server that sends well-formed pushes, a state model that fits in 4 KB, a stale treatment that stays honest, and a token cleanup path. Do that once, properly, and the same infrastructure carries every future activity in the app. Skip it and you get a card that looks impressive on the day you demo it and goes quiet on the second day of real traffic.