From apple-kit-skills
Implements, reviews, or improves Live Activities and Dynamic Island in iOS apps using ActivityKit. For real-time Lock Screen widgets like delivery tracking, sports scores, or media playback.
npx claudepluginhub dpearson2699/swift-ios-skills --plugin all-ios-skillsThis skill uses the workspace's default tool permissions.
Build real-time, glanceable experiences on the Lock Screen, Dynamic Island,
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
Build real-time, glanceable experiences on the Lock Screen, Dynamic Island, StandBy, CarPlay, and a paired Mac using ActivityKit. Patterns target iOS 26+ with Swift 6.3, backward-compatible to iOS 16.1 unless noted.
See references/activitykit-patterns.md for complete code patterns including push payload formats, concurrent activities, state observation, and testing.
NSSupportsLiveActivities = YES to the host app's Info.plist.ActivityAttributes struct with a nested ContentState.ActivityConfiguration in the widget bundle with Lock Screen
content and Dynamic Island closures.Activity.request(attributes:content:pushType:).activity.update(_:) and end with activity.end(_:dismissalPolicy:).Run through the Review Checklist at the end of this document.
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.
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"
}
}
}
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.
let content = ActivityContent(
state: state,
staleDate: Date().addingTimeInterval(300), // stale after 5 minutes
relevanceScore: 75
)
Use Activity.request to create and display a Live Activity. Pass .token as
the pushType to enable remote updates via APNs.
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)")
}
Update the dynamic content state from the app. Use AlertConfiguration to
trigger a visible banner and sound alongside the update.
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
))
End the activity when the tracked event completes. Choose a dismissal policy to control how long the ended activity lingers on the Lock Screen.
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 code paths -- success, error, and cancellation. A leaked activity stays on the Lock Screen until the system kills it (up to 8 hours), which frustrates users.
The Lock Screen is the primary surface for Live Activities. Every device with iOS 16.1+ displays Live Activities here. Design this layout first.
struct DeliveryActivityWidget: Widget {
var body: some WidgetConfiguration {
ActivityConfiguration(for: DeliveryAttributes.self) { context in
// Lock Screen / StandBy / CarPlay / paired Mac content
VStack(alignment: .leading) {
HStack {
Text(context.attributes.restaurantName)
.font(.headline)
Spacer()
Text("Order #\(context.attributes.orderNumber)")
.font(.caption)
.foregroundStyle(.secondary)
}
if context.isStale {
Label("Updating...", systemImage: "arrow.trianglehead.2.clockwise")
.font(.subheadline)
.foregroundStyle(.secondary)
} else {
HStack {
Label(context.state.driverName, systemImage: "person.fill")
Spacer()
Text(timerInterval: context.state.estimatedDeliveryTime,
countsDown: true)
.monospacedDigit()
}
.font(.subheadline)
// Progress steps
HStack {
ForEach(DeliveryStep.allCases, id: \.self) { step in
Image(systemName: step.icon)
.foregroundStyle(
step <= context.state.currentStep ? .primary : .tertiary
)
}
}
}
}
.padding()
} dynamicIsland: { context in
// Dynamic Island closures (see next section)
DynamicIsland {
// Expanded regions...
DynamicIslandExpandedRegion(.leading) {
Image(systemName: "box.truck.fill").font(.title2)
}
DynamicIslandExpandedRegion(.trailing) {
Text(timerInterval: context.state.estimatedDeliveryTime,
countsDown: true)
.font(.caption).monospacedDigit()
}
DynamicIslandExpandedRegion(.center) {
Text(context.attributes.restaurantName).font(.headline)
}
DynamicIslandExpandedRegion(.bottom) {
HStack {
ForEach(DeliveryStep.allCases, id: \.self) { step in
Image(systemName: step.icon)
.foregroundStyle(
step <= context.state.currentStep ? .primary : .tertiary
)
}
}
}
} compactLeading: {
Image(systemName: "box.truck.fill")
} compactTrailing: {
Text(timerInterval: context.state.estimatedDeliveryTime,
countsDown: true)
.frame(width: 40).monospacedDigit()
} minimal: {
Image(systemName: "box.truck.fill")
}
}
}
}
The Lock Screen presentation has limited vertical space. Avoid layouts taller
than roughly 160 points. Use supplementalActivityFamilies to opt into
.small (compact) or .medium (standard) sizing:
ActivityConfiguration(for: DeliveryAttributes.self) { context in
// Lock Screen content
} dynamicIsland: { context in
// Dynamic Island
}
.supplementalActivityFamilies([.small, .medium])
The Dynamic Island is available on iPhone 14 Pro and later. It has three presentation modes. Design all three, but treat the Lock Screen as the primary surface since not all devices have a Dynamic Island.
Always visible when a single Live Activity is active. 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) |
Shown when multiple Live Activities compete for space. Only one activity gets the minimal slot. Display a single icon or glyph.
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 |
Apply a subtle tint to the Dynamic Island border:
DynamicIsland { /* expanded */ }
compactLeading: { /* ... */ }
compactTrailing: { /* ... */ }
minimal: { /* ... */ }
.keylineTint(.blue)
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.
Pass .token as the pushType when starting the activity, then forward the
push token to your server:
let activity = try Activity.request(
attributes: attributes,
content: content,
pushType: .token
)
// Observe token changes -- tokens can rotate
Task {
for await token in activity.pushTokenUpdates {
let tokenString = token.map { String(format: "%02x", $0) }.joined()
try await ServerAPI.shared.registerActivityToken(
tokenString, activityID: activity.id
)
}
}
Send an HTTP/2 POST to APNs with these headers and JSON body:
Required HTTP headers:
apns-push-type: liveactivityapns-topic: <bundle-id>.push-type.liveactivityapns-priority: 5 (low) or 10 (high, triggers alert)Update payload:
{
"aps": {
"timestamp": 1700000000,
"event": "update",
"content-state": {
"driverName": "Alex",
"estimatedDeliveryTime": {
"lowerBound": 1700000000,
"upperBound": 1700001800
},
"currentStep": "delivering"
},
"stale-date": 1700000300,
"alert": {
"title": "Delivery Update",
"body": "Your driver is nearby!"
}
}
}
End payload: Same structure with "event": "end" and optional "dismissal-date".
The content-state JSON must match the ContentState Codable structure
exactly. Mismatched keys or types cause silent failures.
Start a Live Activity remotely without the app running (iOS 17.2+):
Task {
for await token in Activity<DeliveryAttributes>.pushToStartTokenUpdates {
let tokenString = token.map { String(format: "%02x", $0) }.joined()
try await ServerAPI.shared.registerPushToStartToken(tokenString)
}
}
Add NSSupportsLiveActivitiesFrequentUpdates = YES to Info.plist to increase
the push update budget. Use for activities that update more than once per
minute (sports scores, ride tracking).
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).
let scheduledDate = Calendar.current.date(
from: DateComponents(year: 2026, month: 3, day: 15, hour: 19, minute: 0)
)!
let activity = try Activity.request(
attributes: attributes,
content: content,
pushType: .token,
start: scheduledDate
)
style: parameter iOS 26+)Control persistence: .standard (persists until ended, default) or .transient (system may dismiss automatically). Use .transient for short-lived updates like transit arrivals. The style: parameter on Activity.request requires iOS 26+.
let activity = try Activity.request(
attributes: attributes, content: content,
pushType: .token, style: .transient
)
Live Activities automatically appear on a paired Mac running macOS Tahoe and on the CarPlay Home Screen. No additional code needed — ensure Lock Screen layout is legible at smaller scales.
Broadcast updates to many Live Activities at once with .channel:
let activity = try Activity.request(
attributes: attributes, content: content,
pushType: .channel("delivery-updates")
)
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 completes. DO: Always end activities on success, error, and cancellation paths. A leaked activity frustrates users.
DON'T: Assume the Dynamic Island is available (only iPhone 14 Pro+). 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: Put heavy logic in Live Activity views. They render in a size-limited widget process.
DO: Pre-compute display values and pass them through ContentState.
ActivityAttributes defines static properties and ContentStateNSSupportsLiveActivities = YES in host app Info.plistActivityContent (not deprecated contentState API)context.isStaleactivity.pushTokenUpdatesAlertConfiguration used for important updatesActivityAuthorizationInfo checked before starting