HealthKit entegrasyon örüntüleri: 3 app'ten pratik notlar

HealthKit Apple’ın en güçlü framework’lerinden biri. Ama tuzaklı da. Privacy zorlukları, background delivery şaşırtıcılıkları, veri birimlerinin karmaşıklığı. Üç uygulamamda HealthKit kullandım, hepsinden farklı dersler aldım.

Bu yazıda 3 ana konuyu anlatacağım: authorization doğru yapmak, background delivery, veri interpretation.

1. Authorization: en sık yanlış yapılan kısım

HealthKit’e erişim için kullanıcı izni gerekli. Apple bu konuda çok sıkı çünkü sağlık verisi hassas. En sık hatalar:

Hata 1: Tüm permission’ları bir defada istemek.

Yanlış yaklaşım: app ilk açıldığında 15 farklı HealthKit veri tipini birden isteyen alert’i göstermek. Kullanıcı overwhelmed oluyor, “Don’t Allow” basıyor.

Doğru yaklaşım: kullanıcı ilgili feature’a geldiğinde izin iste. “Uyku takibi” feature’ına girdiğinde sleepAnalysis izni sor. “Aktivite” bölümünde step count izni sor. Just-in-time permission.

Hata 2: Read ve write izin kontrolünü karıştırmak.

HKHealthStore.authorizationStatus(for:)

Bu fonksiyon SADECE WRITE izni için doğru sonuç dönüyor. Read permission için Apple hiç bilgi vermiyor (privacy). Yani kullanıcı read izni verdi mi diye doğrudan soramazsın.

Workaround: veri query’le. Eğer sonuç boş ve önceki query’de sonuç olduğunu biliyorsan, kullanıcı izni kaldırmış olabilir. Direct query başka bir yolla kontrol etmek zor.

Hata 3: Info.plist’teki description string’ler generik.

App store review’da reject edilir. “This app reads your health data” yerine spesifik olmalı: “ByteBreak step count verinizi kullanarak günlük hareket hedefinize ulaşmanıza yardımcı olur.”

Hata 4: Permission denied sonrası recovery planı yok.

Kullanıcı izni reddetti, app feature’ı çalışmıyor. Ne yapıyorsun? Sessizce kaybet mi? Veya kullanıcıya “ayarlardan izin ver” diye söyle mi?

Ben her permission check’ten sonra graceful fallback UI gösteriyorum: “HealthKit izni alınmamış, settings’te vermek ister misiniz?” direct settings deep link’iyle.

2. Background delivery

HealthKit’in en güzel özelliklerinden biri: kullanıcı uyurken Apple Watch’tan gelen veriyi background’da işleyebiliyorsun. Ama setup tricky.

HKObserverQuery: Veri değiştikçe callback’i tetikleyen query. Background’da bile çalışıyor.

let query = HKObserverQuery(
    sampleType: HKQuantityType(.stepCount),
    predicate: nil
) { _, completionHandler, error in
    // Yeni step data var
    // İşlemini yap, sonra completion çağır
    completionHandler()
}
healthStore.execute(query)
healthStore.enableBackgroundDelivery(
    for: HKQuantityType(.stepCount),
    frequency: .immediate
) { _, _ in }

Dikkat: enableBackgroundDelivery çağrıldıktan sonra iOS senin app’ini HealthKit değişikliklerinde uyandırıyor. App launch’ta observer query’leri register etmezsen iOS “senin delivery’ni durdururum” diye cezalandırıyor.

ByteBreak’te bu hatayı yaptım: user notification permission yok, background delivery aktif, ama application(_:didFinishLaunchingWithOptions:)’da observer query register etmiyorum. 2 hafta sonra data gelmemeye başladı. iOS delivery’i suspend etmişti.

Çözüm: App launch’ta her zaman (permission varsa) observer query’lerini register et. Hatta UIBackgroundModes’a da “health” ekle.

3. Veri yorumlama: unit hell

HealthKit’in veri unit’leri kafa karıştırıcı. .count(), .kilocalorie(), .meter(), .gram()… Bir kullanıcının adım sayısını “steps” olarak mı yoksa başka bir unit’te mi alacaksın?

Her HKQuantitySample’ın unit’i kontrol etmelisin:

let sample: HKQuantitySample = ...
let steps = sample.quantity.doubleValue(for: HKUnit.count())
let calories = sample.quantity.doubleValue(for: HKUnit.kilocalorie())

Yanlış unit ile okuman compile error vermiyor, runtime’da crash oluyor.

Dentii’de öğrendiğim dersler:

Brushing time minute mı second mı? Apple “toothbrushing” sample’ı second olarak kaydediyor ama document edilmemiş. Ben ilk implementation’da dakika sanıp 60x yanlış veri gösterdim.
Timezone’lar karışık. Kullanıcı Ankara’dan Frankfurt’a uçtu, verisini iki timezone’dan karışık alıyor. startDate ile endDate hangi saat dilimi? HKSample’ların sourceTimeZone özelliği yok, kendi çözümünü bulmalısın.
Aggregate query’ler farklı davranıyor. HKStatisticsCollectionQuery ile günlük average alıyorsun ama kaynak farklı (Apple Watch vs iPhone vs manual) ise merge nasıl yapılıyor? Apple “.strictStartDate” veya “.strictEndDate” option’larıyla kontrol ediyor, ama documentation zayıf.

Örnek: sleep tracking akışı

Snoozio’da uyku verisini nasıl işliyorum:

Kullanıcı ilk açtığında sleep data için izin iste.
Daha önce gelmiş verileri check et (önceki 30 gün).
Background delivery enable et, observer query register et.
Gece boyunca Apple Watch’tan gelen sleep sample’ları observer’ı tetikliyor.
Her tetiklemede, son 24 saatin sleep data’sını analize et.
Analysis sonucunu local storage + CloudKit’e yaz.
Sabah kullanıcı app’i açtığında detaylı view hazır.

Bütün işlem kullanıcı hiçbir şey yapmadan gerçekleşiyor. En zor kısım observer query’nin background’da düzgün çalışmasını sağlamak.

Privacy detayları

HealthKit privacy’yi çok seriously alıyor:

HealthKit verisi iCloud backup’lara dahil değil. Kullanıcı cihazını kaybederse veri de gider.
HealthKit extension’lara erişim sınırlı. Widget veya share extension’dan direct erişim yok, app context gerekli.
App Store review HealthKit kullanımını detaylı kontrol ediyor. Privacy manifest + usage description + actual implementation uyumlu olmalı.
Apple Watch app’i varsa companion iPhone app’ine otomatik izin gelmiyor. İkisi ayrı ayrı authorized olmalı.

Test etmek

HealthKit simulator’da zor. Gerçek cihaz ve gerçek Apple Watch kullan. Test stratejim:

Fake data injection. Health app’ten manuel veri gir, app’inin nasıl reaksiyon verdiğini gör.
Permission edge cases. Izin ver, kaldır, partial izin. Her durumda app doğru davranıyor mu?
Background delivery stress test. Apple Watch ile 3 gün gerçek kullanım.
Device handoff. Farklı cihazlarda aynı iCloud hesabı. Sync doğru çalışıyor mu?

Sonuç

HealthKit güçlü ama tuzaklı. Authorization doğru, background delivery disiplinli, unit handling dikkatli olmalı. İlk projede 3-4 gün boşuna debug yaparsın, ikinci projede yarı zamanda halledersin. Üçüncüde pattern’ler net olur.

En büyük tavsiyem: privacy-first yaklaşım. Kullanıcıya ne kadar az izin sorarsan ve neden istediğini net söylersen o kadar iyi. HealthKit veri dünyanın en hassas veri tiplerinden biri, sorumlu davranman hem legal hem ethical.

HealthKit entegrasyon örüntüleri: 3 app’ten pratik notlar