alarmkit

AlarmKit

アラームやカウントダウンタイマーを設定すると、アラームが鳴ったときにロック画面、Dynamic Island、スタンバイ、ペアリング済みの Apple Watch に目立つ形で表示されます。AlarmKit には iOS 26+ / iPadOS 26+ が必要です。アラームは集中モードや消音モードを突破できます。

AlarmKit はライブアクティビティに ActivityKit のデータモデルを使用しますが、アラームが鳴ったときの通知 UI はシステムが管理するもので、一般的なカスタム通知 UI の表示領域ではありません。カスタム UI を使用できるのは、スケジュール設定時に使用するものと同じ AlarmAttributes<Metadata> と AlarmPresentationState を使ってウィジェット拡張機能で描画する、カウントダウン状態と一時停止中のライブアクティビティ状態に限られます。

認証、スケジュール設定、カウントダウンタイマー、スヌーズ処理、ウィジェットの設定などの完全なコードパターンについては、references/alarmkit-patterns.md を参照してください。

import AlarmKit

目次

• ワークフロー
• 認証
• アラームとタイマーの選択
• アラームのスケジュール設定
• カウントダウンタイマー
• アラームの状態
• AlarmAttributes と AlarmPresentation
• AlarmButton
• ライブアクティビティとの統合
• よくある間違い
• レビュー用チェックリスト
• 参考資料

ワークフロー

1. 新しいアラームまたはタイマーを作成する

1. Info.plist に、ユーザーに表示する文言を指定した NSAlarmKitUsageDescription を追加します。
2. アプリが利用価値を説明できるタイミングで AlarmManager.shared.requestAuthorization() を使って認証をリクエストするか、最初のスケジュール設定時に表示されるシステムプロンプトを処理します。
3. 認証が .denied または .authorized 以外の場合は、スケジュール設定を行わず、問題解決のための UI を表示します。
4. AlarmPresentation（アラート、カウントダウン、一時停止状態）を設定します。
5. 表示設定、任意のメタデータ、色を使って AlarmAttributes を作成します。
6. AlarmManager.AlarmConfiguration（.alarm または .timer）を作成します。
7. AlarmManager.shared.schedule(id:configuration:) を使ってスケジュールを設定します。
8. alarmManager.alarmUpdates を監視し、スケジュール設定した ID が想定される状態になることを確認します。
9. カウントダウンを使用する場合は、同じ AlarmAttributes<Metadata> 型の ActivityConfiguration を備えたウィジェット拡張機能のターゲットを追加します。

2. 既存のアラームコードをレビューする

このドキュメントの最後にあるレビュー用チェックリストに沿って確認します。

認証

AlarmKit にはユーザーの認証が必要です。アプリが利用価値を説明できるタイミングで早めにリクエストするか、最初のスケジュール設定時に AlarmKit が自動的にプロンプトを表示するようにします。明示的なプロンプトまたは自動プロンプトの後に認証が許可されなかった場合、アラームはスケジュール設定されず、通知も行われません。

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）	タイマー（.timer）
鳴るタイミング	特定の時刻（スケジュール）	指定した時間の経過後
カウントダウン UI	任意	常に表示
繰り返し	あり（曜日指定）	なし
用途	起床、スケジュール済みリマインダー	料理、ワークアウトのインターバル

時計の時刻に鳴らす場合は .alarm(schedule:...) を使用します。現在から指定した時間の経過後に鳴らす場合は .timer(duration:...) を使用します。

アラームのスケジュール設定

Alarm.Schedule

1 回限りの絶対日時には .fixed(date) を使用し、現地時刻には .never または .weekly の繰り返しを指定した .relative を使用します。毎日、平日、週末、固定日の各パターンについては、Recurring Alarm Patterns を参照してください。

スケジュール設定と構成

let id = UUID()

let alert = AlarmPresentation.Alert(
    title: "Wake Up",
    secondaryButton: AlarmButton(
        text: "Snooze", textColor: .white, systemImageName: "bell.slash"
    ),
    secondaryButtonBehavior: .countdown
)
let presentation = AlarmPresentation(alert: alert)
struct EmptyAlarmMetadata: AlarmMetadata {}
let attributes = AlarmAttributes<EmptyAlarmMetadata>(
    presentation: presentation,
    metadata: nil,
    tintColor: .indigo
)

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
)

認証を条件とする関数とメタデータを含むバリエーションについては、Complete Alarm Scheduling Flow を参照してください。

stopIntent と secondaryIntent のデフォルト値は nil です。AlarmKit 標準のシステムによる停止動作を使用する場合は stopIntent を省略します。停止時にアプリのクリーンアップ、カスタムの停止動作、その他の副作用を実行する必要がある場合にのみ指定してください。通常のスヌーズ／繰り返しで secondaryButtonBehavior: .countdown と Alarm.CountdownDuration.postAlert を使用する場合は secondaryIntent を省略します。.custom のセカンダリ動作、またはアプリのクリーンアップやカスタム動作を行う場合にのみ指定してください。

アラームの状態遷移

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

• cancel(id:) -- 繰り返しアラームも含め、アラームを完全に削除します
• pause(id:) -- カウントダウン中のアラームを一時停止します。それ以外の状態ではエラーになります
• resume(id:) -- 一時停止中のアラームを再開します。それ以外の状態ではエラーになります
• stop(id:) -- アラームを停止します。単発アラームは削除され、繰り返しアラームは再スケジュールされます
• countdown(id:) -- アラート中の状態からカウントダウンを再開します（スヌーズ）。それ以外の状態ではエラーになります

カウントダウンタイマー

タイマーは指定した時間が経過すると発火し、常にカウントダウン UI を表示します。アラート前後の時間を制御するには Alarm.CountdownDuration を使用します。

CountdownDuration

Alarm.CountdownDuration は、表示されるカウントダウンの各フェーズを制御します。

• preAlert -- アラームが発火する前にカウントダウンする秒数（メインのカウントダウン）
• postAlert -- アラーム発火後の繰り返し／スヌーズ用カウントダウンの秒数

タイマーのファクトリー、一時停止／再開時の表示、メタデータ、スケジューリングのゲートについては、 完全なカウントダウンタイマーのフローを参照してください。

アラームの状態

各 Alarm には、現在のライフサイクル上の位置を示す state プロパティがあります。

状態	意味
.scheduled	スケジュール済みで、適切な時刻にアラートを開始する準備ができています
.countdown	カウントダウン中です（タイマーまたはアラート前のフェーズ）
.paused	ユーザーまたはアプリによってカウントダウンが一時停止されています
.alerting	アラームが鳴動中です（サウンドが再生され、UI が目立つ形で表示されます）

状態の変化を監視する

AlarmManager.shared.alarms は、現在のデーモンのスナップショットを返す、エラーをスローするゲッターです。try を使用し、スナップショットを利用する前に、エラーを伝播するか、起動時の更新処理を do/catch で囲んでください。

独自にライフサイクルを管理するのではなく、alarmUpdates を監視してください。ストアと更新ループの完全な実装については、 非同期シーケンスによる状態の監視を参照してください。

alarmUpdates からアラームが消えた場合、そのアラームは AlarmKit でスケジュールされていません。発火、キャンセル、再スケジュールを区別する必要がある場合は、アプリに保存した ID と比較してください。

AlarmAttributes と AlarmPresentation

AlarmAttributes は ActivityAttributes に準拠し、アラームの Live Activity 用の静的データを定義します。AlarmMetadata に準拠する Metadata 型をジェネリック型として受け取ります。AlarmMetadata は Decodable、Encodable、Hashable、Sendable を継承します。metadata の値自体はオプションで、デフォルトは nil です。

AlarmPresentation は必須のアラートコンテンツと、オプションのカウントダウン／一時停止中のコンテンツを提供します。アラート UI はシステムが描画します。ウィジェット拡張機能では、同じ属性と表示状態を使って、カウントダウン中および一時停止中の Live Activity ビューをカスタマイズできます。メタデータは軽量に保ち、不要な場合は nil を使用し、その型をウィジェット拡張機能と共有してください。

AlarmPresentationState

AlarmPresentationState は、アラームの Live Activity においてシステムが管理する ContentState です。アラーム ID と Mode 列挙型を含みます。

• .alert(Alert) -- アラームが鳴動中で、スケジュールされた時刻を含みます
• .countdown(Countdown) -- カウントダウン中で、発火日時と各時間を含みます
• .paused(Paused) -- カウントダウンが一時停止中で、経過時間と合計時間を含みます

ウィジェット拡張機能は AlarmPresentationState.mode を読み取り、アラート以外の状態で Dynamic Island とロック画面に表示する UI を決定します。

AlarmButton

AlarmButton は、アラームアクションのテキスト、色、シンボルを定義します。上記の代表的なスケジューリング例には、標準のスヌーズボタンが示されています。

セカンダリボタンの動作

アラート UI のセカンダリボタンには、次の 2 つの動作があります。

動作	効果
.countdown	postAlert の時間を使ってカウントダウンを再開します（スヌーズ）
.custom	secondaryIntent を実行します（例：アプリを開く）

ライブアクティビティの統合

AlarmKit のアラームは、アラームが鳴るとロック画面、Dynamic Island、StandBy、およびペアリング済みの Apple Watch にライブアクティビティとして表示されます。通知 UI はシステムが管理します。カウントダウン状態と一時停止状態を表示するには、アラームのスケジュール時に使用するものと同じ AlarmAttributes<Metadata> 型を使う ActivityConfiguration を備えた Widget Extension ターゲットを追加します。

アラームでカウントダウン表示を使用する場合、Widget Extension が必要です。この軽量なメタデータ型は、アプリと Widget Extension の両方から使用できるようにしてください。Extension がないと、アラームが予期せず解除されたり、通知されなかったりする可能性があります。ただし、デバイスの再起動後、初回ロック解除前など、限られた状況ではシステムがフォールバックのカウントダウン UI を表示する場合があります。

作業	担当
認証、スケジュール／状態、表示、サウンド、システムのアラーム操作	AlarmKit
ホーム画面／Smart Stack ウィジェット、ファミリー、タイムライン、再読み込み	widgetkit
アラーム以外のライブアクティビティのライフサイクル、トークン、リモートコンテンツの状態	activitykit
APNs、通知カテゴリ／アクション、カスタム通知 UI	push-notifications

AlarmKit のアラートは、ロック画面、Dynamic Island、StandBy、およびペアリング済みの Apple Watch にシステムによって表示されます。Widget Extension を使用するのは、カウントダウン状態と一時停止状態のみです。

セットアップでは、Apple がドキュメントで指定している NSAlarmKitUsageDescription と AlarmManager による認証を使用してください。最新の Apple の情報源に記載がない限り、サポートされていない AlarmKit のセットアップキーや com.apple.developer.alarmkit を必須にしないでください。共有属性を使った Widget の実装全体については、アラーム用ライブアクティビティ Widget Extension を参照してください。

よくある間違い

間違い	修正方法
使用目的の文字列または認証ゲートがない	NSAlarmKitUsageDescription を追加し、スケジュール設定の前に拒否を処理します
繰り返しにタイマーを使う	.weekly([...]) を使ったアラームにします
アプリ側の状態で alarmUpdates を置き換える	システムのシーケンスを監視し、ID で同期します
標準の停止／スヌーズ用にインテントを追加する	クリーンアップやカスタム動作に必要な場合を除き、省略します
AlarmMetadata のペイロードが大きい	メタデータを軽量にするか、ID でアプリデータを参照します
非推奨の stopButton イニシャライザー	init(title:secondaryButton:secondaryButtonBehavior:) を使います

レビューチェックリスト

• サポートされていないエンタイトルメントキーなしで、セットアップと認証のゲートが機能する
• アラーム／タイマーの選択、表示、メタデータ、インテント、スヌーズ時間、色合いが有効である
• スケジュール済みの ID を保持し、alarmUpdates を通じて同期する。操作エラーも処理する
• カウントダウンでは、共有の Widget Extension 属性と表示状態を使う
• システム管理のアラート UI と隣接スキルの担当範囲が、ルーティング表に従っている
• サウンド、振動、停止／スヌーズ、状態変更を実機でテストする

参考資料

• パターンとコード：references/alarmkit-patterns.md
• Apple のドキュメント：AlarmKit | AlarmManager | AlarmAttributes | アラームのスケジュール設定