Rork Max の健康アプリで、朝になると歩数が更新されない — HKObserverQuery が無言で止まる background delivery の設計

observer が「一度きりで死ぬ」問題を completionHandler で防ぐ

三段目の observer query こそ、無言の失敗が最も起きる場所です。HKObserverQuery のハンドラには completionHandler（HealthKit 側では HKObserverQueryCompletionHandler）が渡されます。これを呼ばないと、システムは「まだ処理が終わっていない」と判断し、以後の background 起動を止めてしまいます。フォアグラウンドでは呼び忘れても動いてしまうため、リリースまで気づけません。

extension HealthObservation {
    func startObserver() {
        let query = HKObserverQuery(
            sampleType: stepType,
            predicate: nil
        ) { [weak self] _, completionHandler, error in
            guard let self else { completionHandler(); return }
            if let error {
                healthLog.error("observer error: \(error.localizedDescription)")
                completionHandler()   // エラー時も必ず呼ぶ
                return
            }
            // 実データの取得は anchored query に委譲
            Task {
                await self.fetchIncremental()
                healthLog.info("observer fired, incremental fetched")
                completionHandler()   // 取得完了後に呼ぶ
            }
        }
        store.execute(query)
    }
}

ここでの要点は二つです。第一に、completionHandler() を成功・失敗・early return のすべての経路で必ず一度だけ呼ぶこと。第二に、observer 自体はデータを運んでこないという事実です。observer は「何かが変わった」という合図しか渡しません。呼び忘れという小さな罠の対処を先に固めておくと、後段の切り分けがずっと楽になります。実際の差分取得は別途 anchored query で行います。

差分だけを取る HKAnchoredObjectQuery を組み合わせる

observer が起きるたびに全期間を舐め直すと、バックグラウンドの実行時間をすぐ使い切ります。HKAnchoredObjectQuery は前回位置を表す anchor を返すので、それを保存しておけば次回は増えた分だけを引けます。この anchor の永続化を怠ると、毎回フル取得になり、結局スロットリングされて「たまに欠ける」症状に戻ります。

extension HealthObservation {
    private var anchorKey: String { "health.anchor.stepCount" }
 
    private func loadAnchor() -> HKQueryAnchor? {
        guard let data = UserDefaults.standard.data(forKey: anchorKey) else { return nil }
        return try? NSKeyedUnarchiver.unarchivedObject(
            ofClass: HKQueryAnchor.self, from: data)
    }
 
    private func saveAnchor(_ anchor: HKQueryAnchor) {
        let data = try? NSKeyedArchiver.archivedData(
            withRootObject: anchor, requiringSecureCoding: true)
        UserDefaults.standard.set(data, forKey: anchorKey)
    }
 
    func fetchIncremental() async {
        await withCheckedContinuation { continuation in
            let query = HKAnchoredObjectQuery(
                type: stepType,
                predicate: nil,
                anchor: loadAnchor(),
                limit: HKObjectQueryNoLimit
            ) { [weak self] _, samples, _, newAnchor, error in
                if let error {
                    healthLog.error("anchored error: \(error.localizedDescription)")
                }
                if let newAnchor { self?.saveAnchor(newAnchor) }
                let count = samples?.count ?? 0
                healthLog.info("incremental samples: \(count)")
                // ここで samples を自前のストアへ反映する
                continuation.resume()
            }
            store.execute(query)
        }
    }
}

anchor は UserDefaults でも十分ですが、App Group を使ってウィジェットと共有すると、ウィジェット側の表示も同じ差分基準で揃えられます。私は複数の小さなアプリを運用する中で、この anchor の保存先を最初から共有ストレージにしておくと後の拡張が楽だと感じています。

Rork Max の生成コードが書ききれない三つの穴

Rork Max は Swift のクエリロジックまでは自然言語から十分に生成してくれます。しかし background delivery を実機で成立させるには、コードの外側にある設定を自分で埋める必要があり、ここが AI の生成物だけでは埋まりません。私が毎回手で確認しているのは次の三点です。

1. Info.plist の利用目的文

NSHealthShareUsageDescription（読み取り）と、書き込むなら NSHealthUpdateUsageDescription の両方を、審査で拒否されない具体的な文面で入れます。ここが空だと実機で権限ダイアログ自体が出ず、App Store 審査でも指摘されます。

2. Capabilities の有効化

HealthKit の capability を有効化し、background delivery を使うなら Background Modes ではなく HealthKit の設定側で有効になっていること（enableBackgroundDelivery の呼び出しと対になる）を確認します。

3. ワークアウト連動の追加設定

ワークアウト中の高頻度更新を受けたいなら、Background Modes の Workout processing を有効化します。歩数だけなら不要ですが、心拍のリアルタイム取得へ拡張する段で必ず必要になります。

「閉じている間だけ欠ける」を再現テストする段取り

この種の不具合はフォアグラウンドでは再現しません。私が使っている確認手順は、アプリを完全にバックグラウンドへ送り（ホーム画面へ戻す）、別途 iPhone のヘルスケアアプリやワークアウトで実データを増やし、数十分後にアプリを開いて log の observer fired が閉じている間に出ていたかを見る、というものです。

もし background delivery enabled は出ているのに observer fired が閉じている間に一度も出ていなければ、原因は observer の登録タイミングにあることが多いです。observer query はアプリ起動のたびに execute し直す必要があり、application(_:didFinishLaunchingWithOptions:) 相当の早い段階で張り直していないと、システムからの background 起動時に query が存在せず取りこぼします。Rork Max の生成コードでは observer の起動が画面表示後になりがちなので、ここを起動直後へ引き上げるのが実機で効く一手です。AdMob やサブスクの計測をヘルスデータに紐づける拡張でも、この起動タイミングの前倒しが土台になります。

次に手を動かすなら、まずは上の HealthObservation を起動直後に bootstrap() する形で組み込み、実機で一晩放置してから log を確認してみてください。三段のどこで切れているかが log から一目でわかる状態を先に作ることが、この無言の失敗を短時間で終わらせる近道になります。