alarmkit

# AlarmKit

Schedule prominent alarms and countdown timers that surface on the Lock Screen,
Dynamic Island, StandBy, and a paired Apple Watch when the alarm fires. AlarmKit
requires iOS 26+ / iPadOS 26+. Alarms can break through Focus and Silent mode.

AlarmKit uses ActivityKit data models for its Live Activity, but the firing alert
is system-managed alarm UI, not a general custom notification UI surface. Custom
UI belongs only to countdown and paused Live Activity states rendered by a Widget
Extension with the same `AlarmAttributes<Metadata>` and
`AlarmPresentationState` used when scheduling.

See [references/alarmkit-patterns.md](references/alarmkit-patterns.md) for complete code patterns including
authorization, scheduling, countdown timers, snooze handling, and widget setup.

```swift
import AlarmKit
```

## Contents

- [Workflow](#workflow)
- [Authorization](#authorization)
- [Alarm vs Timer Decision](#alarm-vs-timer-decision)
- [Scheduling Alarms](#scheduling-alarms)
- [Countdown Timers](#countdown-timers)
- [Alarm States](#alarm-states)
- [AlarmAttributes and AlarmPresentation](#alarmattributes-and-alarmpresentation)
- [AlarmButton](#alarmbutton)
- [Live Activity Integration](#live-activity-integration)
- [Common Mistakes](#common-mistakes)
- [Review Checklist](#review-checklist)
- [References](#references)

## Workflow

### 1. Create a new alarm or timer

1. Add `NSAlarmKitUsageDescription` to Info.plist with a user-facing string.
2. Request authorization with `AlarmManager.shared.requestAuthorization()` when the app can explain the value, or handle the first-schedule system prompt.
3. If authorization is `.denied` or not `.authorized`, show recovery UI instead of scheduling.
4. Configure `AlarmPresentation` (alert, countdown, paused states).
5. Create `AlarmAttributes` with the presentation, optional metadata, and tint color.
6. Build an `AlarmManager.AlarmConfiguration` (.alarm or .timer).
7. Schedule with `AlarmManager.shared.schedule(id:configuration:)`.
8. Observe state changes via `alarmManager.alarmUpdates`.
9. If using countdown, add a Widget Extension target with an `ActivityConfiguration` for the same `AlarmAttributes<Metadata>` type.

### 2. Review existing alarm code

Run through the Review Checklist at the end of this document.

## Authorization

AlarmKit requires user authorization. Request early when the app can explain the
value, or let AlarmKit prompt automatically on first schedule. If authorization
is not granted after the explicit or automatic prompt, alarms are not scheduled
and will not alert.

```swift
let manager = AlarmManager.shared

// Request authorization explicitly
let state = try await manager.requestAuthorization()
guard state == .authorized else { return }

// Check current state synchronously
let current = manager.authorizationState // .authorized, .denied, .notDetermined

// Observe authorization changes
for await state in manager.authorizationUpdates {
    switch state {
    case .authorized: print("Alarms enabled")
    case .denied:     print("Alarms disabled")
    case .notDetermined: break
    @unknown default: break
    }
}
```

## Alarm vs Timer Decision

| Feature | Alarm (`.alarm`) | Timer (`.timer`) |
|---|---|---|
| Fires at | Specific time (schedule) | After duration elapses |
| Countdown UI | Optional | Always shown |
| Recurring | Yes (weekly days) | No |
| Use case | Wake-up, scheduled reminders | Cooking, workout intervals |

Use `.alarm(schedule:...)` when firing at a clock time. Use `.timer(duration:...)`
when firing after a duration from now.

## Scheduling Alarms

### Alarm.Schedule

Alarms use `Alarm.Schedule` to define when they fire.

```swift
// Fixed: fire at an exact Date (one-time only)
let fixed: Alarm.Schedule = .fixed(myDate)

// Relative one-time: fire at 7:30 AM in device time zone, no repeat
let oneTime: Alarm.Schedule = .relative(.init(
    time: .init(hour: 7, minute: 30),
    repeats: .never
))

// Recurring: fire at 6:00 AM on weekdays
let weekday: Alarm.Schedule = .relative(.init(
    time: .init(hour: 6, minute: 0),
    repeats: .weekly([.monday, .tuesday, .wednesday, .thursday, .friday])
))
```

### Schedule and Configure

```swift
let id = UUID()

let snooze = Alarm.CountdownDuration(preAlert: nil, postAlert: 300)
let configuration = AlarmManager.AlarmConfiguration(
    countdownDuration: snooze,
    schedule: .relative(.init(
        time: .init(hour: 7, minute: 0),
        repeats: .never
    )),
    attributes: attributes,
    sound: .default
)

let alarm = try await AlarmManager.shared.schedule(
    id: id,
    configuration: configuration
)
```

`stopIntent` and `secondaryIntent` default to `nil`. Omit `stopIntent` for
AlarmKit's standard system Stop behavior; provide it only when Stop must run app
cleanup, custom stop behavior, or other side effects. Omit `secondaryIntent` for
ordinary Snooze/Repeat with `secondaryButtonBehavior: .countdown` and
`Alarm.CountdownDuration.postAlert`; provide it only for `.custom` secondary
behavior or app cleanup/custom behavior.

### Alarm State Transitions

```text
cancel(id:)
    |
scheduled --> countdown --> alerting
    |             |             |
    |         pause(id:)    stop(id:) / countdown(id:)
    |             |
    |         paused ----> countdown (via resume(id:))
    |
cancel(id:) removes from system entirely
```

- `cancel(id:)` -- remove the alarm completely, including repeating alarms
- `pause(id:)` -- pause a counting-down alarm; throws from other states
- `resume(id:)` -- resume a paused alarm; throws from other states
- `stop(id:)` -- stop the alarm; one-shot alarms are removed, repeating alarms reschedule
- `countdown(id:)` -- restart countdown from alerting state (snooze); throws from other states

## Countdown Timers

Timers fire after a duration and always show a countdown UI. Use
`Alarm.CountdownDuration` to control pre-alert and post-alert durations.

```swift
// Simple timer: 5-minute countdown, no snooze
let timerConfig = AlarmManager.