Health Connect ile antrenman deneyimleri geliştirme

Uygulamanızda antrenman deneyimi oluşturmak istiyorsanız Health Connect'i kullanarak şunları yapabilirsiniz:

• Egzersiz oturumlarını yazma
• Antrenman rotalarını yazma
• Nabız, hız ve mesafe gibi antrenman metriklerini yazma
• Diğer uygulamalardaki egzersiz verilerini okuma

Bu kılavuzda, veri türleri, arka planda yürütme, izinler, önerilen iş akışları ve en iyi uygulamalar ele alınarak bu antrenman özelliklerinin nasıl oluşturulacağı açıklanmaktadır.

Genel bakış: Kapsamlı bir antrenman takipçisi oluşturma

Aşağıdaki temel adımları uygulayarak Health Connect'i kullanarak kapsamlı bir egzersiz takibi deneyimi oluşturabilirsiniz:

• Sağlık İzinleri'ne göre izinlerin doğru şekilde uygulanması.
• ExerciseSessionRecord kullanarak oturumları kaydetme.
• Oturum sırasında egzersiz verilerini tutarlı bir şekilde yazma.
• Sürekli veri yakalamayı doğrulamak için arka planda yürütmeyi düzgün şekilde yönetme.
• Antrenman sonrası özetler ve analizler için oturum verilerini okuma

Bu iş akışı, diğer Health Connect uygulamalarıyla birlikte çalışabilirlik sağlar ve kullanıcı tarafından kontrol edilen veri erişimini doğrular.

Başlamadan önce

Antrenman özelliklerini uygulamadan önce:

• Uygun bağımlılığı kullanarak Health Connect'i entegre edin.
• HealthConnectClient örneği oluşturun.
• Uygulamanızın, Sağlık İzinleri'ne dayalı çalışma zamanı izin akışları uyguladığını doğrulayın.
• İş akışınızda GPS kullanılıyorsa konum iznini ve ön plan hizmetini ayarlayın.

Temel kavramlar

Health Connect, egzersiz verilerini birkaç temel bileşen kullanarak gösterir. ExerciseSessionRecord, başlangıç veya bitiş zamanları ve egzersiz türü gibi ayrıntıları içeren bir antrenmanın merkezi kaydı olarak işlev görür. Oturum sırasında HeartRateRecord veya SpeedRecord gibi çeşitli veri türleri kaydedilebilir. Açık hava etkinliklerinde ExerciseRoute, ilgili oturumla bağlantılı olan GPS verilerini depolar.

Egzersiz oturumları

ExerciseSessionRecord, tek bir antrenman seansını temsil eden antrenman verilerinin merkezi kaydıdır. Her kayıtta şunlar saklanır:

• startTime
• endTime
• exerciseType
• İsteğe bağlı oturum meta verileri (başlık, notlar)

ExerciseSessionRecord, verilerinin bir parçası olarak egzersiz rotaları, turlar ve segmentler de içerebilir. Ayrıca, bir oturum sırasında HeartRateRecord veya SpeedRecord gibi diğer veri türleri kaydedilip oturumla ilişkilendirilebilir.

İlişkili veri türleri

Antrenman seanslarıyla ilişkili veriler, ayrı kayıt türleriyle temsil edilir. Yaygın türler şunlardır:

• HeartRateRecord: Bir dizi nabız ölçümünü gösterir.
• SpeedRecord: Bir dizi hız ölçümünü gösterir.
• DistanceRecord: Okumalar arasında katedilen mesafeyi gösterir.
• TotalCaloriesBurnedRecord: Okumalar arasında yakılan toplam kaloriyi gösterir.
• ElevationGainedRecord: Okumalar arasında kazanılan yüksekliği gösterir.
• StepsCadenceRecord: Okumalar arasındaki adım ritmini gösterir.
• PowerRecord: Okumalar arasındaki güç çıkışını gösterir. Bisiklet gibi aktivitelerde yaygındır.

Veri türlerinin tam listesi için Health Connect veri türleri başlıklı makaleyi inceleyin.

Egzersiz rotaları

ExerciseRoute kullanarak bir rotayı açık hava egzersizleriyle ilişkilendirebilirsiniz. Rotalar, her biri aşağıdakileri içeren sıralı ExerciseRoute.Location nesnelerden oluşur:

• Enlem ve boylam
• İsteğe bağlı yükseklik
• İsteğe bağlı merkez
• Doğruluk bilgileri
• Zaman damgası

Bağlantı oturumu rotaları

ExerciseRoute, egzersiz oturumunun sıralı konum verilerini içerir. Health Connect'te bağımsız bir kayıt olarak ele alınmaz. Bunun yerine, ExerciseRoute eklerken veya güncellerken ExerciseSessionRecord verileri sağlarsınız.

Geliştirme ile ilgili dikkat edilmesi gereken hususlar

Egzersiz izleme uygulamalarının genellikle uzun süre çalışması gerekir. Bu uygulamalar, ekran kapalıyken sıklıkla arka planda çalışır. Egzersiz özelliklerinizi oluştururken arka planda yürütmeyi nasıl yöneteceğinizi ve egzersiz verileri için gerekli izinleri nasıl isteyeceğinizi göz önünde bulundurmanız önemlidir.

Arka planda yürütme

Egzersiz uygulamaları genellikle ekran kapalıyken çalışır. Bu durumda şunları kullanmanız gerekir:

• Konum ve sensör örnekleme için ön plan hizmetleri
• Ertelenmiş yazma veya senkronizasyon için WorkManager
• Normal kayıt yazma için gruplandırma stratejileri

Tüm yazma işlemlerinde oturum kimliğini tutarlı tutarak sürekliliği koruyun.

İzinler

Uygulamanız, antrenman verilerini okumadan veya yazmadan önce ilgili Health Connect izinlerini istemelidir. Antrenmanlarla ilgili yaygın izinler arasında egzersiz seansları, egzersiz rotaları ve nabız ya da hız gibi metrikler yer alır. Bu alanlar/yollar aşağıdakileri içerir:

• Egzersiz oturumları: ExerciseSessionRecord için okuma ve yazma izinleri.
• Egzersiz rotaları: ExerciseRoute için okuma ve yazma izinleri.
• Nabız: HeartRateRecord için okuma ve yazma izinleri.
• Hız: SpeedRecord için okuma ve yazma izinleri.
• Drive: DistanceRecord için okuma ve yazma izinleri.
• Kaloriler: TotalCaloriesBurnedRecord için okuma ve yazma izinleri.
• Çıkılan Yükseklik: ElevationGainedRecord için okuma ve yazma izinleri.
• Adım ritmi: StepsCadenceRecord için okuma ve yazma izinleri.
• Güç: PowerRecord için okuma ve yazma izinleri.
• Adımlar: StepsRecord için okuma ve yazma izinleri.

Aşağıda, rota, nabız, mesafe, kalori, hız ve adım verilerini içeren bir antrenman seansı için birden fazla izin isteğinde bulunma örneği gösterilmektedir:

İstemci örneği oluşturduktan sonra uygulamanızın kullanıcıdan izin istemesi gerekir. Kullanıcılar, izinleri istedikleri zaman verebilmeli veya reddedebilmelidir. Bunu yapmak için gerekli veri türleri için bir dizi izin oluşturun. Gruptaki izinlerin önce Android manifestinizde tanımlandığından emin olun.

val permissions =
    setOf(
        HealthPermission.getReadPermission(ExerciseSessionRecord::class),
        HealthPermission.getWritePermission(ExerciseSessionRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class),
        HealthPermission.getReadPermission(SpeedRecord::class),
        HealthPermission.getWritePermission(SpeedRecord::class),
        HealthPermission.getReadPermission(DistanceRecord::class),
        HealthPermission.getWritePermission(DistanceRecord::class),
        HealthPermission.getReadPermission(TotalCaloriesBurnedRecord::class),
        HealthPermission.getWritePermission(TotalCaloriesBurnedRecord::class),
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class)
    )
HealthConnectManager.kt

val permissions = setOf(
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class)
    )

val requestPermissionsLauncher = rememberLauncherForActivityResult(
    contract = PermissionController.createRequestPermissionResultContract()
) { grantedPermissions ->
    if (grantedPermissions.containsAll(permissions)) {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions granted!") }
    } else {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions denied.") }
    }
}
HealthConnectActivity.kt

İzin istemek için checkPermissionsAndRun işlevini çağırın:

if (!granted.containsAll(permissions)) {
    // Check if required permissions are not granted, and return
    return emptySet()
}
// Permissions already granted; proceed with inserting or reading data
HealthConnectManager.kt

Yalnızca kalp atış hızı gibi tek bir veri türü için izin istemeniz gerekiyorsa izin kümenize yalnızca bu veri türünü ekleyin:

Nabza erişim aşağıdaki izinlerle korunur:

• android.permission.health.READ_HEART_RATE
• android.permission.health.WRITE_HEART_RATE

Uygulamanıza kalp atış hızı özelliği eklemek için HeartRateRecord veri türüyle ilgili izinleri isteyerek başlayın.

Kalp atış hızını yazabilmek için bildirmeniz gereken izin şudur:

<application>
  <uses-permission
android:name="android.permission.health.WRITE_HEART_RATE" />
...
</application>

Nabzı okumak için aşağıdaki izinleri istemeniz gerekir:

<application>
  <uses-permission
android:name="android.permission.health.READ_HEART_RATE" />
...
</application>

Antrenman oturumu uygulama

Bu bölümde, egzersiz verilerini kaydetmek için önerilen iş akışı açıklanmaktadır.

Oturumu başlatma

Yeni bir antrenman oluşturmak için:

1. Benzersiz bir oturum kimliği oluşturun: Bu kimliğin kararlı olduğunu doğrulayın. Uygulama işleminiz sonlandırılıp yeniden başlatılırsa parçalanmış oturumları önlemek için aynı kimliği kullanmaya devam edebilmeniz gerekir.
2. Senkronizasyon yeniden denemeleri sırasında yinelenen öğeleri önlemek için metadata.clientRecordId ayarlayın.
3. Yazma ExerciseSessionRecord: Başlangıç zamanını ekleyin.
4. Veri türü ve GPS verilerini toplamaya başlayın: Bunları yalnızca oturum kaydı başarıyla başlatıldıktan sonra başlatın.

Örnek:

val sessionClientId = UUID.randomUUID().toString()
val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)

val session =   ExerciseSessionRecord(
    startTime = startTime,
    startZoneOffset = zoneOffset,
    endTime = startTime.plusSeconds(3600),
    endZoneOffset = zoneOffset,
    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_RUNNING,
    metadata = Metadata(clientRecordId = sessionClientId),
)

healthConnectClient.insertRecords(listOf(session))
HealthConnectManager.kt

Egzersiz rotalarını kaydetme

Okuma kılavuzu hakkında daha fazla bilgi edinmek için Ham verileri okuma başlıklı makaleyi inceleyin.

Egzersiz rotası kaydederken verilerinizi toplu olarak göndermeniz gerekir. Bu, her bir GPS noktasını gerçekleştiği anda kaydetmek yerine bir grup nokta toplayıp tek bir çağrıda hepsini aynı anda kaydetmeniz gerektiği anlamına gelir.

Uygulamanız Health Connect'te her okuma veya yazma işlemi yaptığında çok az miktarda pil ve işlem gücü kullandığı için bu önemlidir.

Aşağıdaki kodda toplu olarak nasıl kayıt yapılacağı gösterilmektedir:

// 1. Create a list to hold your route locations
val routeLocations = mutableListOf<ExerciseRoute.Location>()

// 2. Add points to your list as the exercise happens
routeLocations.add(
    ExerciseRoute.Location(
        time = Instant.now(),
        latitude = 37.7749,
        longitude = -122.4194
    )
)

// ... keep adding points over a period of time ...

// 3. Save the whole list at once (Batching)
val session = ExerciseSessionRecord(
    startTime = startTime,
    endTime = endTime,
    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_RUNNING,
    // We pass the whole list here
    exerciseRoute = ExerciseRoute(routeLocations)
)

healthConnectClient.insertRecords(listOf(session))

Oturumu sonlandırma

Veri toplama durdurulduktan sonra:

• Kaydı güncelleme: Uygulamanız, ExerciseSessionRecord ile endTime bilgilerini günceller.
• Verileri sonlandırma: İsteğe bağlı olarak özet değerleri (ör. toplam mesafe veya ortalama hız) hesaplayın ve bunları ek kayıtlar olarak yazın.

val finishedSession = session.copy(endTime = Instant.now())
healthConnectClient.updateRecords(listOf(finishedSession))

Antrenman verilerini okuma

Uygulamalar, etkinliği özetlemek, sağlık analizleri sağlamak veya verileri harici bir sunucuyla senkronize etmek için egzersiz oturumlarını ve bunlarla ilişkili verileri okuyabilir. Örneğin, ExerciseSessionRecord okuyabilir ve ardından aynı zaman aralığında gerçekleşen HeartRateRecord veya DistanceRecord sorgulayabilirsiniz.

Egzersiz verilerini bir arka uç sunucusuyla senkronize etmeniz veya uygulamanızın veri deposunu Health Connect ile güncel tutmanız gerekiyorsa ChangeLogs'u kullanın. Bu yöntem, belirli bir zamandan beri eklenen, güncellenen veya silinen kayıtların listesini almanıza olanak tanır. Bu, değişiklikleri manuel olarak izlemekten veya tüm verileri tekrar tekrar okumaktan daha verimlidir. Daha fazla bilgi için Verileri Health Connect ile senkronize etme başlıklı makaleyi inceleyin.

Oturumları okuma

Egzersiz oturumlarını okumak için tür olarak ExerciseSessionRecord ile ReadRecordsRequest kullanın. Genellikle bunu belirli bir zaman aralığına göre filtreleyebilirsiniz.

suspend fun readExerciseSessions(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    val response = healthConnectClient.readRecords(
        ReadRecordsRequest(
            recordType = ExerciseSessionRecord::class,
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
        )
    )

    for (exerciseRecord in response.records) {
        // Process each session
        val exerciseType = exerciseRecord.exerciseType
        val notes = exerciseRecord.notes
    }
}

Rotaları okuma

ExerciseRoute verileri egzersiz oturumunun bir parçası olarak yazılsa da ayrı olarak okunması gerekir. Rota verilerini okumak için oturumun kimliğiyle birlikte getExerciseRoute() yöntemini kullanın:

suspend fun readExerciseRoute(
    healthConnectClient: HealthConnectClient,
    exerciseSessionRecord: ExerciseSessionRecord
) {
    // Check if the session has a route
    val route = healthConnectClient.getExerciseRoute(
        exerciseSessionRecordId = exerciseSessionRecord.metadata.id
    )

    when (route) {
        is ExerciseRouteResponse.Success -> {
            val locations = route.exerciseRoute.locations
            for (location in locations) {
                // Use latitude, longitude, and altitude
            }
        }
        is ExerciseRouteResponse.NoData -> {
            // Handle case where no route exists
        }
        is ExerciseRouteResponse.ConsentRequired -> {
            // Handle case where permissions are missing
        }
    }
}

Veri türlerini okuma

Bir oturum sırasında gerçekleşen belirli ayrıntılı verileri (ör. kalp atış hızı) okumak için bu veri türüyle ilgili isteği filtrelemek üzere oturumun startTime ve endTime değerlerini kullanın.

suspend fun readHeartRateData(
    healthConnectClient: HealthConnectClient,
    exerciseSession: ExerciseSessionRecord
) {
    val response = healthConnectClient.readRecords(
        ReadRecordsRequest(
            recordType = HeartRateRecord::class,
            timeRangeFilter = TimeRangeFilter.between(
                exerciseSession.startTime,
                exerciseSession.endTime
            )
        )
    )

    for (heartRateRecord in response.records) {
        for (sample in heartRateRecord.samples) {
            val bpm = sample.beatsPerMinute
        }
    }
}

En iyi uygulamalar

Veri güvenilirliğini ve kullanıcı deneyimini iyileştirmek için aşağıdaki yönergelere uyun:

• Aktif izleme sırasında sık sık yazma: Aktif izleme için verileri kullanılabilir hale geldikçe veya en fazla 15 dakikalık aralıklarla yazın.
• Arka plan senkronizasyonları için WorkManager'ı kullanın: Ertelenmiş yazma işlemleri için WorkManager kullanın. Gerçek zamanlı veriler ve pil verimliliği arasında denge kurmak için 15 dakikalık bir aralık hedefleyin.
• Toplu yazma istekleri: Her bir sensör etkinliğini ayrı ayrı yazmayın. İsteklerinizi parçalara ayırın. Health Connect, yazma isteği başına 1.000 kaydı işler.
• Oturum kimliklerini sabit ve benzersiz tutun: Oturumlarınız için tutarlı tanımlayıcılar kullanın. Bir oturum düzenlenir veya güncellenirse aynı kimliğin kullanılması, oturumun yeni ve ayrı bir oturum olarak değerlendirilmesini önler.
• Hem veri türleri hem de rota noktaları için gruplandırma kullanın: Giriş/çıkış ek yükünü azaltmak ve pil ömrünü korumak için veri noktalarınızı tek bir insertRecords çağrısında gruplandırın. Her noktayı ayrı ayrı yazmayın.
• Yinelenen veriler yazmaktan kaçının: İstemci kimliklerini kullanın: Kayıt oluştururken metadata.clientRecordId ayarlayın. Health Connect, benzersiz kayıtları tanımlamak için bunu kullanır. Zaten mevcut olan bir clientRecordId ile kayıt yazmaya çalışırsanız Health Connect, yineleneni yoksayar veya yeni bir kayıt oluşturmak yerine mevcut kaydı günceller. metadata.clientRecordId ayarlamak, senkronizasyon yeniden denemeleri veya uygulamanın yeniden yüklenmesi sırasında yinelenen kayıtları önlemenin en etkili yoludur.
  

  val record = StepsRecord(
      count = 100,
      startTime = startTime,
      endTime = endTime,
      startZoneOffset = ZoneOffset.UTC,
      endZoneOffset = ZoneOffset.UTC,
      metadata = Metadata(
          // Use a unique ID from your own database
          clientRecordId = "daily_steps_2023_10_27_user_123"
      )
  )

• Mevcut verileri kontrol edin: Senkronizasyondan önce, uygulamanızdaki kayıtların zaten mevcut olup olmadığını görmek için zaman aralığını sorgulayın.
• GPS doğruluğunu doğrulama: Haritanın temiz ve profesyonel görünmesini sağlamak için ExerciseRoute konumuna yazmadan önce düşük doğruluklu GPS örneklerini (ör. yüksek yatay doğruluk yarıçapına sahip noktalar) filtreleyin.
• Zaman damgalarının çakışmadığından emin olun: Yeni bir oturumun, önceki oturum sona ermeden başlamadığını doğrulayın. Çakışan oturumlar, fitness kontrol panellerinde ve özet hesaplamalarında çakışmalara neden olabilir.
• İzin için net gerekçeler sunun: Uygulamanızın neden sağlık verilerine erişmesi gerektiğini açıklamak için Permission.createIntent akışını kullanın. Örneğin: "Tansiyon trendlerinizi izlemek ve analizler sunmak için."
• Duraklatma ve devam ettirme desteği: Uygulamanızın duraklatma işlemlerini doğru şekilde yaptığını doğrulayın. Kullanıcı duraklattığında, ortalama hız ve sürenin doğru kalması için rota noktalarını ve veri türlerini toplamayı durdurun.
• Uzun süren oturumları test etme: Toplu işleme aralığınızın ve sensör kullanımınızın cihazın pilini tüketmediğini doğrulamak için birkaç saat süren oturumlar sırasında pil tüketimini izleyin.
• Zaman damgalarını sensör hızlarıyla eşleştirin: Verilerin yüksek doğruluğunu korumak için kayıt zaman damgalarınızı sensörlerinizin gerçek sıklığıyla eşleştirin.

Test

Verilerin doğruluğunu ve yüksek kaliteli bir kullanıcı deneyimi sağlamak için aşağıdaki test stratejilerini uygulayın ve resmi En önemli kullanım alanlarını test etme belgelerine bakın.

Doğrulama araçları

• Health Connect Araç Kutusu: Kayıtları manuel olarak incelemek, test verilerini silmek ve veritabanında değişiklikleri simüle etmek için bu yardımcı uygulamayı kullanın. Bu, kayıtlarınızın doğru şekilde saklandığını doğrulamanın en iyi yoludur.
• FakeHealthConnectClient ile birim testi: Uygulamanızın, fiziksel bir cihaza ihtiyaç duymadan izin iptali veya API istisnaları gibi uç durumları nasıl işlediğini doğrulamak için test kitaplığını kullanın.

Kalite kontrol listesi

Tipik mimari

Antrenman uygulaması genellikle şunları içerir:

Sorun giderme

Sık karşılaşılan hata ayıklama adımları