Show Your Rork App's Progress on the Lock Screen and Dynamic Island

Define the state type

ActivityKit describes an activity's data with ActivityAttributes. The key is to separate values that never change (the session type) from values that get rewritten on each update (seconds remaining).

import ActivityKit
 
struct MeditationAttributes: ActivityAttributes {
    // Dynamic state rewritten on each update
    public struct ContentState: Codable, Hashable {
        var remainingSeconds: Int
        var phase: String   // "breathing" / "rest" etc.
    }
 
    // Static values fixed at session start
    var sessionTitle: String
    var totalSeconds: Int
}

Watch the size here: if the JSON in ContentState exceeds 16KB, the update is rejected. Do not carry heavy data like a Base64 image string directly — pass an identifier and draw it widget-side. Skip this and you get a hard-to-reproduce bug where small payloads pass in TestFlight but the moment you push a long string in production the update is dropped.

The three steps: start / update / end

The lifecycle is just start, update, and end. Starting a meditation session looks like this.

import ActivityKit
 
final class MeditationLiveActivity {
    private var activity: Activity<MeditationAttributes>?
 
    func start(title: String, total: Int) {
        // Always confirm Live Activities are enabled on the device
        guard ActivityAuthorizationInfo().areActivitiesEnabled else { return }
 
        let attributes = MeditationAttributes(sessionTitle: title, totalSeconds: total)
        let initial = MeditationAttributes.ContentState(
            remainingSeconds: total, phase: "breathing"
        )
 
        do {
            activity = try Activity.request(
                attributes: attributes,
                content: .init(state: initial, staleDate: nil),
                pushType: nil          // local updates only; push covered below
            )
        } catch {
            // Do not swallow this — always log it
            print("Live Activity start failed: \(error)")
        }
    }
 
    func update(remaining: Int, phase: String) {
        let state = MeditationAttributes.ContentState(
            remainingSeconds: remaining, phase: phase
        )
        Task {
            await activity?.update(.init(state: state, staleDate: nil))
        }
    }
 
    func end() {
        Task {
            await activity?.end(nil, dismissalPolicy: .immediate)
        }
    }
}

Skip the areActivitiesEnabled check and Activity.request throws on the devices of users who turned the feature off in Settings. I swallowed that error at first, and tracking down why "only some users never see the timer" cost me half a day. Always log the exception — that is basic production hygiene, not specific to Live Activities.

Drawing the lock screen versus the Dynamic Island

In the Widget Extension you draw the same data in two layouts: the larger lock-screen card and the folded Dynamic Island presentation.

import WidgetKit
import SwiftUI
 
struct MeditationWidget: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: MeditationAttributes.self) { context in
            // Lock screen / banner
            VStack {
                Text(context.attributes.sessionTitle)
                Text(format(context.state.remainingSeconds))
                    .font(.system(size: 36, weight: .semibold, design: .rounded))
                    .monospacedDigit()
            }
            .padding()
        } dynamicIsland: { context in
            DynamicIsland {
                DynamicIslandExpandedRegion(.center) {
                    Text(format(context.state.remainingSeconds)).monospacedDigit()
                }
            } compactLeading: {
                Image(systemName: "leaf.fill")
            } compactTrailing: {
                Text(format(context.state.remainingSeconds)).monospacedDigit()
            } minimal: {
                Image(systemName: "leaf.fill")
            }
        }
    }
}

Whether you add monospacedDigit() decides whether the number jitters every time a digit drops. Small detail, but a flickering display during meditation is noise, so for any timer I always use monospaced digits.

Local updates or push updates — which to pick

There are two update paths: local updates, where you call activity.update while the app is alive in the foreground or background, and push updates, where the server injects state through APNs.

For a meditation timer, where the user is watching the screen or away for a few minutes at most, local updates are enough. But when you want to keep updating even after the app is fully terminated — like delivery tracking — you must specify pushType: .token and send from APNs.

A common report: it worked with local updates during development, but in production "the remaining time freezes when I close the app." That is not a bug; it is how local updates work. Decide up front to switch to push updates if you need post-termination updates, and you avoid a rebuild later.

The 8-hour ceiling and avoiding orphaned cards

iOS automatically ends a Live Activity at most 8 hours after it starts. On top of that, if your app forgets to call end, a frozen timer lingers on the lock screen and unsettles users.

My rule is simple: enumerate every path that ends a session and make sure end is called no matter which one fires. I always verify the three paths — normal completion, user interruption, and recovery from a crash. After a crash especially, scanning Activity.activities at launch to clear stranded activities keeps things safe.

func cleanupStaleActivities() {
    for activity in Activity<MeditationAttributes>.activities {
        Task { await activity.end(nil, dismissalPolicy: .immediate) }
    }
}

What I check before release

For submission I keep a three-point checklist. Live Activities look different on supported devices (Dynamic Island needs iPhone 14 Pro or later) versus older ones, so on-device testing is not optional.

• Does a user who turned Live Activities off in Settings avoid a crash?
• When updates cannot arrive in airplane mode or no signal, does the display stay coherent?
• When a session is canceled midway, does the lock-screen card reliably disappear?

Plain checks, but passing them cuts both review rejections and low-star reviews. Even for apps earning through AdMob, I find this kind of polish lifts retention, which in turn grows impressions.

Once you can quietly place the remaining time on the lock screen, the app shifts from something you open to something that sits beside you. As a next step, write down the one piece of information in your own app that users would want to check without opening it. That becomes the first star you put into a Live Activity.