Giyilebilir cihaz verisini klinik bir sisteme taşırken zaman kaybettiren şey API çağrısı yazmak değil; izin modelinin sessiz davranışı, geçmiş veriye erişim sınırları ve platformların kapanma takvimi. Somut olarak: iOS'ta uygulamanız okuma izni alıp almadığını öğrenemez, Android'de varsayılan olarak yalnızca son 30 günü okuyabilirsiniz, Google Fit API'leri 2026'da kapanıyor ve Fitbit'in eski Web API'si bu ay deprecation sürecine girdi. Bu yazı, bu dört gerçeğin mimarinize ne yaptığını ve verinin FHIR tarafına nasıl doğru eşleneceğini anlatıyor.
HealthKit'te okuma izni verilip verilmediğini öğrenemezsiniz; bu bir hata değil, tasarım
En çok yanlış kullanılan API authorizationStatus(for:). Apple'ın kendi dokümanı gerekçesiyle birlikte açık: hassas sağlık bilgisinin sızmasını önlemek için uygulama, kullanıcının okuma izni verip vermediğini belirleyemez. İzin yoksa durum, "istenen türde veri yok" gibi görünür. Uygulamaya yazma izni verilip okuma izni verilmediyse, yalnızca kendi yazdığı veriyi görür; diğer kaynaklardan gelen veri gizli kalır.
Bunun ürün tarafındaki karşılığı şu: "izin verilmedi, lütfen Ayarlar'dan açın" ekranını authorizationStatus'a bakarak gösteremezsiniz. Yapılabilecek tek şey sorgu sonucuna bakmak ve boş sonuç ile izinsizliği ayırt edemediğinizi kabul eden bir arayüz tasarlamak. Uygun metin, "izin vermediniz" değil, "henüz veri göremiyoruz; Sağlık uygulamasındaki izinleri kontrol edin" olur.
Arka planda veri almanın entitlement'ı ve saatlik tavanı var
enableBackgroundDelivery(for:frequency:withCompletion:) iOS 15 ve watchOS 8'den itibaren com.apple.developer.healthkit.background-delivery entitlement'ını zorunlu kılıyor; entitlement yoksa çağrı errorAuthorizationDenied döndürüyor. iOS tarafında çoğu veri tipi için maksimum frekans hourly. immediate yalnızca watchOS'ta ve sınırlı bir olay kümesinde geçerli: yüksek ve düşük kalp hızı olayları, düzensiz kalp ritmi olayları, ortam ve kulaklık ses maruziyeti, düşük kardiyo fitness, düşme algılama, VO2 Max, el yıkama, diş fırçalama.
Üç ayrıntı daha üretimde sorun çıkarıyor:
- Observer query'ler
application(_:didFinishLaunchingWithOptions:)içinde kurulmalı. Başka bir yerde kurarsanız arka plan uyandırmaları kaybolur. - Completion handler çağrılmazsa HealthKit geri çekilme (backoff) uygular ve üç başarısızlıktan sonra güncelleme göndermeyi durdurur. Bu, "bir süre çalıştı sonra durdu" şikâyetlerinin en yaygın sebebi.
- watchOS'ta complication varsa saatte en fazla dört güncelleme bütçesi paylaşılıyor.
Artımlı senkronizasyon için doğru araç HKAnchoredObjectQuery. Sorgu, son alınan örneğe ya da silinen nesneye karşılık gelen bir anchor döndürüyor; bir sonraki sorguyu bu anchor ile çalıştırdığınızda yalnızca yeni eklenen ve silinen nesneler geliyor. Silinen nesneler HKDeletedObject olarak ayrı ayrı bildiriliyor, yani kendi tarafınızda da silme uygulamanız mümkün (bkz. Apple, HKAnchoredObjectQuery).
Anchor'ı kullanıcı hesabıyla ilişkilendirip sunucu tarafında saklayın. Cihazda saklarsanız uygulama yeniden kurulduğunda anchor sıfırlanır, tüm geçmiş yeniden çekilir ve mükerrer kayıt üretirsiniz. Mükerrer kaydı önlemek için sunucu tarafında cihaz UUID'si + ölçüm zamanı + tip üzerinden idempotent bir anahtar kullanın.
Android'de varsayılan geçmiş 30 gün; daha eskisi ayrı izin istiyor
Health Connect, Android 14 (API 34) ve üzerinde platforma gömülü; daha eski sürümlerde APK olarak kuruluyor. İzinler android.permission.health.READ_[VERİ_TİPİ] biçiminde tanımlı ve iki özel izin var: READ_HEALTH_DATA_IN_BACKGROUND ve READ_HEALTH_DATA_HISTORY.
İkincisi kritik. Google'ın dokümanı varsayılanı açıkça söylüyor: bir uygulama, herhangi bir izin ilk kez verildiği ana kadar geriye doğru 30 güne kadar veri okuyabilir. Daha eskisi için READ_HEALTH_DATA_HISTORY gerekiyor (bkz. Android Developers, Health Connect).
Android 14 ve üzerinde uygulamanın kendi yazdığı veride tarih sınırı yok; sınır diğer uygulamaların verisinde geçerli. Android 13 ve altında sınır tüm veriye uygulanıyor. Uygulama silinip yeniden kurulursa tarih sıfırlanıyor.
Bu, kronik hastalık takibi yapan bir ürün için doğrudan bir ürün kararı: kullanıcının geçmiş altı ayını göstermek istiyorsanız ek izin istemek zorundasınız, ve bu izin mağaza incelemesinde gerekçe ister.
Platform kapanma takvimi: mimariyi buna göre kurun
| Kaynak | Durum (25.09.2026) | Ne yapmalı |
|---|---|---|
| Google Fit API | 2026'da kapanıyor; 1 Mayıs 2024'ten beri yeni geliştirici kaydı alınmıyor. Android dokümanı desteğin 2026 sonuna kadar süreceğini söylüyor. | Yeni projede kullanmayın; mevcut entegrasyonu Health Connect'e taşıyın |
| Fitbit Web API (legacy) | Fitbit'in kendi duyurusu: eski Web API Eylül 2026'da deprecate ediliyor, yeni altyapıya geçiliyor | Entegrasyonu soyutlama katmanının arkasına alın; doğrudan çağrı yazmayın |
| Garmin Health API | OAuth 2.0 + PKCE; PING/PUSH webhook yapısı. Geliştirici programı şu anda yeni başvuru kabul etmiyor | Ürün planında Garmin'e bağımlılık varsa erişimi önce teyit edin |
| Apple HealthKit / Health Connect | Platforma gömülü, kapanma riski yok | Birincil kaynak bunlar olsun; bulut API'leri ikincil |
Fitbit tarafında bilinen bir sınır daha var: uygulama başına kullanıcı başına saatte 150 istek, sayaç yaklaşık her saat başında sıfırlanıyor. Access token'ın varsayılan ömrü 8 saat. On bin kullanıcılık bir taban için bu, senkronizasyonu kullanıcı başına planlamayı ve saat başlarında yığılmayı önlemek için istekleri saat içine dağıtmayı zorunlu kılıyor.
Cihaz verisini FHIR'a eşlerken doğru LOINC kodunu kullanın
Ölçümün FHIR karşılığı Observation kaynağı. R4'te bu kaynağın yalnızca iki zorunlu alanı var: status ve code (bkz. HL7 FHIR R4, Observation). Gerisi isteğe bağlı, ama klinik tarafta işe yaraması için subject, effectiveDateTime, valueQuantity ve device doldurulmalı. Observation.status için bağlayıcı değer kümesi sekiz kod içeriyor: registered, preliminary, final, amended, corrected, cancelled, entered-in-error, unknown.
Kodlama tarafında doğrulanmış LOINC karşılıkları:
| Ölçüm | LOINC | Resmî ad |
|---|---|---|
| Kalp hızı | 8867-4 | Heart rate |
| SpO2 (pulse oksimetre) | 59408-5 | Oxygen saturation in Arterial blood by Pulse oximetry |
| Adım sayısı | 41950-7 | Number of steps in 24 hour, Measured |
Sık yapılan hata: SpO2 için 2710-2 kullanmak. Bu kod LOINC tarafından DEPRECATED işaretli; kapiller kan ve oksimetre kombinasyonunu tanımlıyor, giyilebilir cihazın ürettiği veri bu değil. Kod tablonuzu bir defa doğru kurun ve LOINC sürüm güncellemelerini takip edin (bkz. LOINC 2710-2 kayıt sayfası).
Apple tarafında hasta kayıtları için ayrı bir yol var: Health Records, FHIR R4 (v4.0.1) ve DSTU2 destekliyor; R4 için US Core Implementation Guide v3.1.1 uyumu isteniyor ve yeni kaydolan kuruluşlara R4 öneriliyor. FHIR kaynak modelinin temellerine FHIR rehberimizden bakabilirsiniz.
Wellness mi, tıbbi cihaz mı? Cevabı kodunuz değil, beyanınız veriyor
Aynı kalp hızı verisi iki ayrı hukuki sonuç üretebilir. Belirleyici olan üreticinin beyan ettiği kullanım amacı: genel iyilik hâli ve fitness amacıyla sunulan bir uygulama tıbbi cihaz mevzuatına girmez; ölçümü yorumlayıp teşhis, tedavi veya izleme amacıyla bilgi üreten bir yazılım girer. Türkiye'de niteliklendirme kılavuzu olarak TİTCK, MDCG 2019-11 belgesinin Türkçe çevirisini yayımlamış durumda.
Pratik kural: ürün metninde "uyarır", "tespit eder", "riskli" gibi ifadeler kullanır kullanmaz sınıflandırma sorusu açılıyor. Bu, pazarlama metniyle regülasyonun kesiştiği nadir yerlerden biri; metni yazan kişiyle sınıflandırmayı değerlendiren kişi aynı masada olmalı.
Türkiye mevzuatı açısından iyi haber şu: Uzaktan Sağlık Hizmetlerinin Sunumu Hakkında Yönetmelik'in 7. maddesi, uzaktan verilebilecek hizmetler arasında giyilebilir teknolojiler ile sağlık verilerinin ölçülmesini açıkça sayıyor. Yani uzaktan takip senaryosunun mevzuatta tanımlı bir yeri var. Platform tarafındaki diğer şartlar için uzaktan sağlık platformu yazısına bakın.
Mimari: cihaz verisini olay akışı gibi ele alın, tablo gibi değil
Giyilebilir veri, ilişkisel bir tabloya satır satır yazıldığında hızla iki sorun üretiyor: hacim ve geriye dönük düzeltme. Bir kullanıcının tek bir günü, saniyelik kalp hızı örneklemesiyle binlerce satır olabiliyor; üstelik platform, daha önce gönderilmiş bir örneği sonradan silebiliyor.
Çalışan desen şu dört katmandan oluşuyor:
- Ham katman. Platformdan gelen yükü olduğu gibi, değiştirmeden saklayın. Sorun araştırmasında tek güvenilir kanıt bu.
- Normalize katman. Idempotent anahtarla (kaynak + cihaz + tip + zaman) tekilleştirilmiş ölçümler. Silme bildirimleri burada işlenir.
- Toplulaştırma katmanı. Klinik olarak anlamlı pencereler: günlük ortalama, gece istirahat nabzı, uyku evresi süreleri. Arayüz bu katmandan okur.
- FHIR dışa aktarım katmanı.
Observationkaynakları yalnızca dışarı veri verilirken üretilir. FHIR'ı iç depolama biçimi olarak kullanmayın; sorgulaması pahalı.
Dördüncü madde en çok tartışılanı. FHIR bir değişim standardı; kendi veritabanınızın şeması olmak zorunda değil ve olmaması genellikle daha ucuz.
Sırada ne var
Entegrasyona başlamadan önce üç soruyu yazılı olarak yanıtlayın: ürün kaç gün geçmiş veriye ihtiyaç duyuyor (Android izin kararını bu belirliyor), veriyi yorumlayıp uyarı üretecek mi (sınıflandırma kararını bu belirliyor), ve hangi kaynaklara bağımlı olacaksınız (kapanma takvimi riskini bu belirliyor). Üçüne de cevap verdikten sonra yazılacak kod şaşırtıcı derecede az.
Sağlık verisi tarafındaki yaklaşımımızı sağlık ve medikal yazılım sayfasında, entegrasyon katmanı kurulumunu API geliştirme sayfasında bulabilirsiniz. Kendi kapsamınız için bir tahmin almak isterseniz proje fiyat hesaplama aracı işinizi görür.
Teknik ayrıntılar 25 Eylül 2026 tarihinde birincil kaynaklardan doğrulanmıştır: Apple Developer dokümantasyonu (HKHealthStore.authorizationStatus, enableBackgroundDelivery, HKAnchoredObjectQuery, HKQuantityTypeIdentifier), Apple Health Records teknik gereksinimleri, Android Developers Health Connect kılavuzları, developers.google.com/fit deprecation duyurusu, dev.fitbit.com Web API referansı, loinc.org kod sayfaları ve HL7 FHIR R4 Observation tanımı. Platform API'leri ve kapanma takvimleri hızla değişiyor; üretime çıkmadan önce güncel dokümanı teyit edin. Mevzuat atıfları hukuki görüş yerine geçmez.
