background-execution

アプリがバックグラウンド状態またはサスペンド状態でも実行される Swift コードを作成・レビューします。作業内容に適した API を選び、システムの制約を守ることで、作業を確実に実行し、アプリが終了されないようにします。

レビューの手順：

1. references/fundamentals.md を使って、バックグラウンド実行モデル（ライフサイクル、実行時間の上限、強制終了、5 つの原則）を把握します。
2. 以下の決定木で、選択した API が作業内容に合っていることを確認します。合っていない場合は、適切な API に切り替えます。
3. references/bg-task-scheduler.md を使って、BGTaskScheduler の使用方法（登録のタイミング、Info.plist、有効期限、setTaskCompleted）を確認します。
4. references/task-assertions.md を使って、タスクアサーション（beginBackgroundTask/endBackgroundTask、performExpiringActivity）を確認します。
5. references/background-url-session.md を使って、バックグラウンドの URLSession 設定と再起動のフローを確認します。
6. references/background-push.md を使って、サイレントプッシュ／VoIP プッシュのペイロード、ヘッダー、ハンドラーを確認します。
7. references/background-modes.md を使って、UIBackgroundModes の宣言と位置情報に関する詳細を確認します。
8. references/background-audio.md を使って、バックグラウンドオーディオ（セッションカテゴリ、ロック中の録音、中断、ルート変更、マイクの許可）を確認します。
9. references/swiftui-background-tasks.md を使って、SwiftUI の ScenePhase／.backgroundTask の使用方法を確認します。
10. references/macos-background.md を使って、macOS のスケジューラー（NSBackgroundActivityScheduler、beginActivity、SMAppService）を確認します。
11. references/testing-and-debugging.md を使って、テスト／デバッグと制約への対処を確認します。
12. references/anti-patterns.md を使って、よくある間違いを見つけます。

作業の一部だけを行う場合は、関連するリファレンスファイルだけを読み込みます。

タスクに応じた参照先

ユーザーの目的に合わせて、読み込む順序を決めます。必要なものだけを読み込みます。

「アプリのコンテンツをバックグラウンドで更新したい」

1. references/bg-task-scheduler.md - BGAppRefreshTask、登録／送信／有効期限
2. references/testing-and-debugging.md - 起動のシミュレート、backgroundRefreshStatus の処理

「長時間のメンテナンス／ML／クリーンアップをバックグラウンドで実行したい」

1. references/bg-task-scheduler.md - BGProcessingTask、電源／ネットワークの要件
2. references/testing-and-debugging.md - 起動と有効期限のシミュレート

「ユーザーが開始したエクスポートを、アプリを離れた後も実行し続けたい（iOS 26）」

1. references/bg-task-scheduler.md - BGContinuedProcessingTask、進捗、送信方法、GPU
2. references/fundamentals.md - ユーザーの同意／ユーザーが開始した作業に関する原則

「アプリがバックグラウンドに移行するとき、進行中のアップロード／保存を完了させたい」

1. references/task-assertions.md - beginBackgroundTask/endBackgroundTask、performExpiringActivity

「サスペンド中も継続する大容量ファイルのダウンロード／アップロードをしたい」

1. references/background-url-session.md - バックグラウンド設定、デリゲート、再起動のフロー
2. references/testing-and-debugging.md - 強制終了と制約に関する注意事項

「サーバーからアプリを起動したい」

1. references/background-push.md - サイレントプッシュのペイロード／ヘッダー／ハンドラー、または通話向けの PushKit
2. references/background-modes.md - remote-notification モード

「バックグラウンドでオーディオを再生し続けたい」

1. references/background-audio.md - audio モードとアクティブなセッション、カテゴリ／モード／オプション、中断、ルート変更

「画面をロックした状態で録音／音声入力／文字起こしをしたい」

1. references/background-audio.md - .playAndRecord、ロック中の録音、マイクの許可、AVAudioEngine のタップ、本番環境での注意点

「バックグラウンドで位置情報を追跡したい」

1. references/background-modes.md - location モード、大きな変更の監視、領域の監視

「SwiftUI の方法で実装したい」

1. references/swiftui-background-tasks.md - ScenePhase、.backgroundTask(.appRefresh/.urlSession)
2. references/bg-task-scheduler.md - 引き続き BGTaskScheduler でスケジュールします

「macOS でバックグラウンド作業をしたい」

1. references/macos-background.md - NSBackgroundActivityScheduler、beginActivity、SMAppService

「バックグラウンドタスクが実行されません／テストするにはどうすればよいですか」

1. references/testing-and-debugging.md - lldb のシミュレーションコマンド、実行を制御する状態
2. references/anti-patterns.md - よくある原因

「バグや App Review の問題が発生しています」

1. references/anti-patterns.md - 修正前と修正後の例を紹介

決定ツリー

どのバックグラウンド API を使えばよいですか？

Does the work require user consent or input mid-flight?
  -> Background runtime is wrong. Bring it to the foreground.

Is work already running and you just need to finish it as the app backgrounds?
  -> beginBackgroundTask / endBackgroundTask (apps)
  -> ProcessInfo.performExpiringActivity (app extensions, watchOS)

Is it a user-initiated long task that should continue with visible progress? (iOS/iPadOS 26)
  -> BGContinuedProcessingTask

Is it a large/long file download or upload that must survive suspension/termination?
  -> background URLSession

Does the server need to tell the app new content exists?
  -> background (silent) push  (apns-push-type: background, content-available: 1)

Is it an incoming call invitation?
  -> PushKit + CallKit (report the call on every push)

Is it periodic content refresh before the user opens the app?
  -> BGAppRefreshTask

Is it long, deferrable maintenance / ML / cleanup?
  -> BGProcessingTask (optionally requiresExternalPower / requiresNetworkConnectivity)

Does the app need to keep playing audio or recording the mic (incl. while locked)?
  -> audio UIBackgroundMode + active AVAudioSession (.playback or .playAndRecord)  [background-audio.md]

Does the app need to keep running for location / BLE / VoIP?
  -> declare the matching UIBackgroundModes capability  [background-modes.md]

macOS, deferrable repeating maintenance?
  -> NSBackgroundActivityScheduler

macOS, keep critical non-UI work from being napped?
  -> ProcessInfo.beginActivity / performActivity

どの BGTask タイプを使えばよいですか？

Short content refresh, system picks the time around app usage?
  -> BGAppRefreshTask          (UIBackgroundModes: fetch)

Long maintenance, ideally on charger + network?
  -> BGProcessingTask          (UIBackgroundModes: processing; requiresExternalPower / requiresNetworkConnectivity)

User-tapped long work with progress UI, continues after backgrounding? (iOS 26)
  -> BGContinuedProcessingTask (title/subtitle, progress, submission strategy, optional .gpu)

Long processing of health-research-study data? (iOS 17)
  -> BGHealthResearchTask

コア指示

• 決してバックグラウンド実行が保証されていると考えないでください。実行は状況に応じて任意に行われます。すべての機能にフォアグラウンドでの照合経路を設け、正確性が重要なロジックをバックグラウンドタスクだけに依存させないでください。
• 決してBGTaskScheduler ハンドラーを遅延登録したり、ビューコード内や起動完了後に登録したりしないでください。システムがアプリを直接バックグラウンドで起動する場合があるため、すべてのハンドラーを App.init() / application(_:didFinishLaunchingWithOptions:) で登録してください。（例外は BGContinuedProcessingTask で、ユーザーの操作時に動的に登録します。）
• 決して同じタスク識別子を二度登録しないでください。アプリがクラッシュします。
• 決してBGTask に有効期限ハンドラーを設定し忘れないでください。設定しないと、システムはタスクを完了済みかつ失敗として黙って扱います。ハンドラーを設定して、処理を速やかにキャンセルし、setTaskCompleted(success:) を必ず一度だけ呼び出してください。
• 決して再スケジュールを忘れないでください。BGTaskScheduler のリクエストは一度限りです。起動ハンドラーの最初の行で次のリクエストを送信してください。
• requiresExternalPower / requiresNetworkConnectivity は BGProcessingTaskRequest にのみ設定し、アプリの更新リクエストには設定しないでください。earliestBeginDate は予定時刻ではなく、開始可能な最も早い時刻として扱ってください。
• 決してbeginBackgroundTask の開始と終了を対応させ忘れないでください。成功時と有効期限ハンドラー内の両方で、べき等に（.invalid を確認して）endBackgroundTask を呼び出してください。対応しないとアサーションによりアプリが終了します。バックグラウンド遷移デリゲートの最後ではなく、処理を開始する前に beginBackgroundTask を呼び出してください。
• 決してbackgroundTimeRemaining を実際の猶予時間として信頼しないでください。フォアグラウンドでは DBL_MAX、バックグラウンドでは参考値です。約30秒を想定して計画し、有効期限ハンドラーに頼ってください。
• beginBackgroundTask（アプリ）または performExpiringActivity（エクステンション、watchOS）は、すでに実行中の処理を完了するためだけに使用してください。新たに長時間の処理を開始したり、将来の処理をスケジュールしたりするために使用してはいけません。
• 決してバックグラウンド URLSession で完了ハンドラー付きの簡易メソッドや dataTask を使わないでください。バックグラウンドセッションにはデリゲートが必要です。識別子ごとにセッションを1つ作成して保存し、再起動時には同一の識別子と構成で再作成してください。
• バックグラウンド URLSession の再起動フローを完全に実装してください。handleEventsForBackgroundURLSession からハンドラーを保存し、セッションを再作成して、メインスレッド上で urlSessionDidFinishEvents(forBackgroundURLSession:) から保存したハンドラーを呼び出してください。didFinishDownloadingTo のコールバック内で、location のファイルを同期的に移動してください。
• バックグラウンドアップロードには、ファイルを使う uploadTask(with:fromFile:) を使用してください。アプリ終了後は、データアップロードとストリームアップロードは失敗します。
• 決してapns-push-type: background（および apns-priority: 5）を付けずにサイレントプッシュを送信しないでください。また、aps 辞書には content-available だけを含めてください。約30秒以内にフェッチ完了ハンドラーを呼び出してください。サイレントプッシュは信頼できるものではなく、間引きや統合の対象として扱ってください。
• iOS 13以降では、すべてのVoIPプッシュに対してCallKitへ着信を通知してください。通知しないと、システムがアプリを終了し、VoIPプッシュの権限を取り消します。通話以外のデータにVoIPプッシュを使用しないでください。
• 決してlocation バックグラウンドモードを有効にせずに allowsBackgroundLocationUpdates = true を設定しないでください。致命的なエラーになります。継続的な location モードよりも、大きな変更の通知や領域監視を優先してください。
• バックグラウンドオーディオには、audio モードと、バックグラウンドに対応したカテゴリ（再生には .playback、ロック中の録音には .playAndRecord / .record）を設定した有効な AVAudioSession の両方が必要です。モードだけでは何も起こりません。起動時ではなく、オーディオの開始時にセッションを有効化し、.notifyOthersOnDeactivation を指定して無効化してください。必ず interruptionNotification（再開前に .shouldResume を確認）と routeChangeNotification（.oldDeviceUnavailable で一時停止）に対応してください。
• マイクのキャプチャには、AVAudioApplication.requestRecordPermission()（iOS 17以降）で権限を要求し、NSMicrophoneUsageDescription を宣言してください。このキーがないとアプリはクラッシュし、権限がないとキャプチャはエラーではなく無音のゼロ値サンプルを返します。AVAudioEngine のタップはメインアクター以外で設定してください（クロージャーはリアルタイムスレッドで実行されます）。また、AVAudioFile の設定を入力ノードのフォーマットに合わせてください。
• UIBackgroundModes は必要最小限に宣言してください。正当な理由のないモードはApp Reviewで却下されます。より軽量な代替手段を優先してください。
• ユーザーの状況を考慮してください。強制終了すると、次回の手動起動まで BGTaskScheduler、サイレントプッシュ、バックグラウンド URLSession による再起動が抑止されます。backgroundRefreshStatus を読み取り（.denied では機能を縮退させ、.restricted では処理を行わないでください）、低電力モードや高い熱状態ではバックオフしてください。
• バックグラウンドに関係する設定（タスク登録、セッション再作成、依存関係の設定）は、.onAppear / .task 内ではなく、すべての起動時に実行される経路で行ってください。バックグラウンド起動では、UIが一度も構築されないことがあります。
• シーンが有効な場合は、非推奨の applicationDidEnterBackground(_:) ではなく sceneDidEnterBackground(_:) を使用してください。戻るまでの時間は約5秒です。
• macOSでは、延期可能なメンテナンスには NSBackgroundActivityScheduler を使用し、App Napの制御には ProcessInfo.beginActivity / endActivity（対応させて使用）または performActivity を使用してください。performExpiringActivity はmacOSにはありません。
• 実機で、lldbの _simulateLaunchForTaskWithIdentifier: / _simulateExpirationForTaskWithIdentifier: コマンドを使ってバックグラウンドタスクをテストしてください。これらのコマンドへの参照は決して出荷しないでください。必ず有効期限切れの経路もテストしてください。

出力形式

ユーザーがレビューを依頼した場合は、ファイルごとに指摘事項をまとめてください。各問題について：

1. ファイル名と該当する行を示します。
2. 置き換えるアンチパターンの名称を挙げます。
3. 簡潔な修正前／修正後のコードを示します。

問題のないファイルは省略します。最後に、影響の大きい変更から優先順位を付けてまとめます。

ユーザーがバックグラウンド実行コードの作成または修正を依頼した場合は、指摘事項のレポートを返すのではなく、コードを直接変更してください。

出力例：

SyncManager.swift

22 行目：.onAppear で BGTaskScheduler ハンドラーを登録しています。バックグラウンド起動時には実行されません。

// Before
.onAppear {
    BGTaskScheduler.shared.register(forTaskWithIdentifier: id, using: nil) { ... }
}

// After - register in App.init() / didFinishLaunching
init() {
    BGTaskScheduler.shared.register(forTaskWithIdentifier: id, using: nil) { task in
        self.handleRefresh(task: task as! BGAppRefreshTask)
    }
}

48 行目：有効期限ハンドラーと setTaskCompleted がありません。有効期限が切れるとアプリが強制終了されます。

// Before
func handleRefresh(task: BGAppRefreshTask) { refresh() }

// After
func handleRefresh(task: BGAppRefreshTask) {
    scheduleNext()
    let op = RefreshOperation()
    task.expirationHandler = { op.cancel() }
    op.completionBlock = { task.setTaskCompleted(success: !op.isCancelled) }
    queue.addOperation(op)
}

まとめ

1. 登録のタイミング（優先度：高）： ハンドラーを App.init() に移動してください。そうしないと、バックグラウンド起動時に実行されません。
2. 完了の要件（優先度：高）： 有効期限ハンドラーを追加し、setTaskCompleted を必ず一度だけ呼び出してください。

例は以上です。

参考資料

• references/fundamentals.md - 実行モデル：フォアグラウンド／バックグラウンド／サスペンド、システムの実行予算、強制終了、ユーザー設定、5 つの原則、ライフサイクルとシーンの状態、「どの API を使うか」の対応表。
• references/bg-task-scheduler.md - BackgroundTasks：BGAppRefreshTask、BGProcessingTask、BGContinuedProcessingTask（iOS 26）、BGHealthResearchTask、登録、Info.plist キー、送信、有効期限、エラー。
• references/task-assertions.md - beginBackgroundTask／endBackgroundTask、backgroundTimeRemaining、ProcessInfo.performExpiringActivity、アサーションと BGTaskScheduler の違い。
• references/background-url-session.md - バックグラウンド URLSession の設定、必須のデリゲート、再起動／handleEventsForBackgroundURLSession のフロー、各種設定、再開データ。
• references/background-push.md - サイレント／バックグラウンドプッシュ（ペイロード、ヘッダー、ハンドラー、スロットリング）、PushKit／VoIP と CallKit の要件。
• references/background-modes.md - UIBackgroundModes の対応表、バックグラウンド位置情報、BLE／アクセサリ／PTT、非推奨のバックグラウンドフェッチ。
• references/background-audio.md - バックグラウンド再生と録音：AVAudioSession のカテゴリ／モード／オプション、ロック中の録音、マイクの許可、割り込み、ルート変更、AVAudioEngine タップと本番環境での注意点。
• references/swiftui-background-tasks.md - ScenePhase、.backgroundTask シーン修飾子、非同期キャンセル、スケジュール設定とハンドラー処理。
• references/macos-background.md - NSBackgroundActivityScheduler、ProcessInfo.beginActivity／App Nap、SMAppService、クロスプラットフォーム対応表。
• references/testing-and-debugging.md - lldb による起動／有効期限切れのシミュレーション、backgroundRefreshStatus、低電力モード、熱状態、実行を制御する条件。
• references/anti-patterns.md - LLM がバックグラウンド実行コードの生成時によく犯す間違い。