In late August we shipped a small iOS 26 app that turns calendar events into AlarmKit alarms: if an event title contains a keyword you registered, a real alarm rings some minutes before it, through Silent mode and Focus, until you stop it.
I wrote up the launch-week lessons back then. This post is the other half: things that only showed up after real people had been using it for a few months. None of them are in the docs, and one of them came from a user report that ended with "I had to restart my phone".
1. The alarm UI is drawn by another process — pass it finished strings
AlarmPresentation.Alert takes LocalizedStringResource values for the title and buttons. It is tempting to pass keys and let the system localize them.
The full-screen alert is rendered by a system process, not by your app. When that process resolves a LocalizedStringResource, "the main bundle" is not your app. In our case the alarm came up showing the raw key — in our project the source language is Japanese, so English users saw Japanese. Other developers have reported the same thing after a device restart (FB20472264 on the Apple Developer Forums).
What fixed it for good was resolving every string inside the app and handing the system a string that needs no further lookup:
/// Resolve in-process, then wrap as a literal so nobody looks it up again. func finished(_ key: String.LocalizationValue) -> LocalizedStringResource { LocalizedStringResource(stringLiteral: String(localized: key)) } let alert = AlarmPresentation.Alert( title: finished("Piano lesson"), stopButton: AlarmButton(text: finished("Stop"), textColor: .white, systemImageName: "stop.circle"), secondaryButton: AlarmButton(text: finished("Snooze"), textColor: .white, systemImageName: "zzz"), secondaryButtonBehavior: .countdown ) The same applies to IntentDialog from App Intents and to anything else that crosses into Siri or the Lock Screen.
A related trap: no desk check covers this. We now ring one real alarm with the device set to English before every release, because the simulator and unit tests never render the system's alarm UI.
2. The full-screen alert appears once. The Live Activity is what stays
A user reported an alarm that would not stop. They had unlocked the phone instead of tapping Stop. On unlock, the full-screen alert goes away and does not come back — not even if you lock the phone again. What stays on screen for the whole time the alarm rings is the Live Activity on the Lock Screen and in the Dynamic Island. Ours had no buttons in the alerting state, so there was nowhere left to stop it.
Two fixes:
- Put Stop and Snooze in the Live Activity's alerting state, as
LiveActivityIntents (theirperform()runs in your app's process, so keep them to types shared with the widget target). - Use the right call.
AlarmManager.shared.cancel(id:)removes a scheduled alarm; it does nothing to one that is ringing.stop(id:)stops it, andcountdown(id:)snoozes it.
struct StopAlarmIntent: LiveActivityIntent { static let title: LocalizedStringResource = "Stop" static let openAppWhenRun = false @Parameter(title: "Alarm ID") var alarmID: String func perform() async throws -> some IntentResult { if let id = UUID(uuidString: alarmID) { try? AlarmManager.shared.stop(id: id) // not cancel(id:) } return .result() } } We also added a "ringing" banner inside the app with its own Stop button. Three places, any one of which is enough.
3. App updates silently drop your background task requests
Our diagnostics (opt-in, TestFlight only) once showed a 40-hour gap with no background refresh at all. It started right after an app update and ended the moment the user opened the app.
When an app is replaced, iOS discards its pending BGTaskRequests. Background tasks only run if they are scheduled, and they are scheduled from inside your process, so nothing brings them back until the app runs again.
While digging into that we found a second bug of our own: we called submit on every launch. Submitting a request with the same identifier replaces the pending one, including its earliestBeginDate. Anyone who opened the app more often than our interval pushed the next run further away every time, so it never ran.
func scheduleIfNeeded(_ id: String) async { let pending = await BGTaskScheduler.shared.pendingTaskRequests() guard !pending.contains(where: { request in request.identifier == id }) else { return } let request = BGAppRefreshTaskRequest(identifier: id) request.earliestBeginDate = Date(timeIntervalSinceNow: 3600) // a lower bound, not a period try? BGTaskScheduler.shared.submit(request) } Since alarms are registered days ahead, an update never removes alarms that already exist. The gap only affects events added after the update. We also ship an App Intent that users can run from a Shortcuts automation ("when Calendar closes"). Each run re-submits the request, so the app recovers without being opened.
4. A downgrade can wipe settings, through an enum
We decode saved data with decodeIfPresent and defaults everywhere, so adding a field never breaks old data. We still found a path that wiped every rule.
Pick a new alarm sound in a TestFlight build, then go back to the App Store build. The App Store build does not know that enum case. decodeIfPresent returns nil for a missing key but throws for an unknown value. One throwing field fails the whole rule book, and the store falls back to empty.
// Unknown values (from a newer build) fall back instead of throwing. sound = (try? c.decodeIfPresent(AlarmSound.self, forKey: .sound)) ?? .default scope = (try? c.decodeIfPresent(MatchScope.self, forKey: .scope)) ?? .title Rules for every enum in persisted data now: decode with try?, give the property a default, and if one section of the file fails, keep the other sections (losing settings is better than losing rules). We have a test that writes values from the future and checks nothing else is lost.
5. An expired trial must not skip alarms people already counted on
The app has a free trial and then a one-time purchase. The question we spent the most time on was what an expired trial should break.
Our answer: alarms that were already registered keep ringing; the app only stops registering new ones. An alarm app that goes silent the morning after a trial ends — while the user still believes it is on — is the worst possible version of this.
Two implementation details follow from that:
- The background paths (refresh task, processing task, App Intents) check the purchase state themselves. They do not go through the UI code, so a check that lives only there would let a background run keep registering after expiry.
- A sync that skipped because of expiry must not touch anything else. We have a nightly "N alarms tomorrow" notification. A skipped sync returns an empty list, and posting "0 alarms tomorrow" from it would be a false alarm.
6. Source language Japanese, fallback English: every gap shows
Our String Catalog's source language is Japanese, and the CFBundleDevelopmentRegion (the fallback for unsupported languages) is English. That combination is intentional, but it makes every gap loud:
-
NSAlarmKitUsageDescriptionis not picked up by-exportLocalizations. We maintain eachInfoPlist.stringsby hand, Japanese included, and a lint fails the build if any language is missing a key. Otherwise that language gets the permission dialog and home-screen name in English. - A string added without a Japanese entry makes Japanese devices fall back to English, because there is no explicit
jatable. We run a fill step on every new string. - Before a release we take screenshots of every screen in every language with a UI test and look at them. Anything in the wrong script is a bug, not polish.
7. iPad support is a one-way door
We added iPad support about a month in. What we did not know until reading the fine print: once a version with iPad support is live, App Store Connect will not let you remove it, because people who bought on iPad must keep getting updates. TestFlight is reversible; the App Store is not. If an iPad-only bug shows up after release, the only option is a quick fix that also works on iPad.
What I would tell myself in August
- Ring a real alarm, in another language, on a real device, before every release.
- Assume the full-screen alert is a one-time event and design stopping around the Live Activity.
- Treat "ringing" and "scheduled" as different states with different calls.
- Make every way data can fail to load fail toward keeping the user's alarms.
The app is called KeyAlarm (https://ltng.jp/keyalarm). Happy to answer AlarmKit questions in the comments.