Health Connect ile antrenman deneyimleri geliştirme

Bu kılavuz, Health Connect 1.1.0 veya sonraki sürümlerle uyumludur.

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

• Egzersiz seanslarını yazma
• Antrenman rotalarını yazma
• Nabız, hız ve mesafe gibi antrenman metriklerini yazma
• Diğer uygulamalardaki antrenman 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 ile kapsamlı bir antrenman takibi deneyimi oluşturabilirsiniz:

• Sağlık İzinleri'ne dayalı izinleri doğru şekilde uygulama
• ExerciseSessionRecord kullanarak oturumları kaydetme
• Oturum sırasında antrenman 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ışabilirliği 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ında istenen izin akışlarını uyguladığını doğrulayın.
• İş akışınızda GPS kullanılıyorsa konum izni ve ön plan hizmeti ayarlayın.

Temel kavramlar

Health Connect, antrenman verilerini birkaç temel bileşen kullanarak temsil eder. 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. Bir oturum sırasında HeartRateRecord veya SpeedRecord gibi çeşitli veri türleri kaydedilebilir. Açık hava etkinlikleri için ExerciseRoute, ilgili oturuma bağlı GPS verilerini depolar.

Egzersiz seansları

ExerciseSessionRecord, antrenman verilerinin merkezi kaydı olup tek bir antrenman oturumunu temsil eder. Her kayıt şunları depolar:

• 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, oturum sırasında HeartRateRecord veya SpeedRecord gibi diğer veri türleri kaydedilebilir ve oturumla ilişkilendirilebilir.

İlişkili veri türleri

Antrenman oturumları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ü temsil eder.
• SpeedRecord: Bir dizi hız ölçümünü temsil eder.
• DistanceRecord: Ölçümler arasında kat edilen mesafeyi gösterir.
• TotalCaloriesBurnedRecord: Ölçümler arasında yakılan toplam kaloriyi temsil eder.
• ElevationGainedRecord: Ölçümler arasında çıkılan yüksekliği gösterir.
• StepsCadenceRecord: Ölçümler arasındaki adım ritmini gösterir.
• PowerRecord: Ölçümler arasındaki güç çıkışını temsil eder. Bisiklet sürme 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 antrenmanlarıyla ilişkilendirebilirsiniz. Rotalar, her biri aşağıdakileri içeren sıralı ExerciseRoute.Location nesnelerinden oluşur:

• Enlem ve boylam
• İsteğe bağlı rakım
• İsteğe bağlı merkez
• Doğruluk bilgileri
• Zaman damgası

Oturum rotalarını bağlama

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

Geliştirme ile ilgili dikkat edilmesi gereken noktalar

Antrenman takip uygulamalarının genellikle uzun süre, çoğu zaman da ekran kapalıyken arka planda çalışması gerekir. Antrenman özelliklerinizi oluştururken arka planda yürütmeyi nasıl yöneteceğinizi düşünmeniz ve antrenman verileri için gerekli izinleri istemeniz önemlidir.

Arka planda yürütme

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

• Konum ve sensör örnekleme için ön plan hizmetleri
• Ertelenen yazma veya senkronizasyon için WorkManager
• Düzenli kayıt yazma için gruplandırma stratejileri

Oturum kimliğini tüm yazma işlemlerinde tutarlı tutarak sürekliliği sağlayın.

İ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 seansları: 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.
• Mesafe: DistanceRecord için okuma ve yazma izinleri.
• Kalori: TotalCaloriesBurnedRecord için okuma ve yazma izinleri.
• Çıkılan yükseklik: ElevationGainedRecord için okuma ve yazma izinleri.
• Steps Cadence: 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 oturumu için birden fazla izin isteme örneği gösterilmektedir:

Uygulamanız, istemci örneği oluşturduktan sonra kullanıcıdan izin istemelidir. Kullanıcıların diledikleri zaman izin vermelerine veya izinleri reddetmelerine olanak tanınmalıdır. Bunun için gerekli veri türlerine yönelik bir izin grubu oluşturun. Öncelikle, kümedeki izinlerin Android manifest dosyanızda beyan edildiğinden 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 tek bir veri türü (ör. nabız) için izin istemeniz gerekiyorsa izin setinize yalnızca bu veri türünü ekleyin:

Nabız verilerine erişim aşağıdaki izinlerle korunur:

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

Uygulamanıza nabız özelliği eklemek için HeartRateRecord veri türüyle ilgili izinleri isteyin.

Nabız verilerini yazabilmek için beyan etmeniz 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, antrenman 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 sabit olduğunu doğrulayın. Uygulama işleminiz sonlandırılıp yeniden başlatılırsa parçalı oturumları önlemek için aynı kimliği kullanarak devam edebilmeniz gerekir.
2. Senkronizasyonun yeniden denenmesi sırasında yinelenenleri önlemek için metadata.clientRecordId ayarlayın.
3. ExerciseSessionRecord yazın: Başlangıç zamanını ekleyin.
4. Veri türü ve GPS verilerini toplamaya başlama: Bu işlemleri 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.activelyRecorded(clientRecordId = sessionClientId, device = Device(type = Device.TYPE_PHONE)),
)

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 gruplandırmanız gerekir. Yani her GPS noktasını gerçekleştiği anda kaydetmek yerine bir grup nokta toplar ve hepsini tek bir çağrıda kaydedersiniz.

Uygulamanız Health Connect'te her okuma veya yazma işlemi yaptığında az miktarda pil ve işlem gücü kullandığından 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 toplamayı durdurduktan sonra:

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

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

Antrenman verileri okunuyor

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

Antrenman 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 sayede, belirli bir zaman noktasından sonra eklenen, güncellenen veya silinen kayıtların listesini alabilirsiniz. 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 seanslarını okumak için türü ExerciseSessionRecord olan bir ReadRecordsRequest kullanın. Bu verileri genellikle belirli bir zaman aralığına göre filtrelersiniz.

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 bir egzersiz oturumunun parçası olarak yazılsa da ayrı olarak okunmalıdır. 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. nabız) okumak için oturumun startTime ve endTime değerlerini kullanarak bu veri türüyle ilgili isteği filtreleyin.

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önergeleri uygulayın:

• Aktif izleme sırasında sık sık yazma: Aktif izleme için verileri kullanılabilir olduğunda veya maksimum 15 dakikalık aralıklarla yazın.
• Arka plan senkronizasyonları için WorkManager'ı kullanın: Ertelenen yazma işlemleri için WorkManager kullanın. Gerçek zamanlı veriler ile pil verimliliği arasında denge kurmak için 15 dakikalık bir aralık hedefleyin.
• Yazma isteklerini toplu olarak gönderin: Her sensör etkinliğini ayrı ayrı yazmayın. İsteklerinizi parçalara ayırın. Health Connect, yazma isteği başına en fazla 1.000 kayıt 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 toplu işlem kullanın: Giriş/çıkış ek yükünü azaltmak ve pil ömrünü korumak için veri noktalarınızı tek tek yazmak yerine tek bir insertRecords çağrısında gruplandırın.
• Yinelenen veriler yazmaktan kaçınma: İstemci kimliklerini kullanma: Kayıt oluştururken metadata.clientRecordId ayarlayın. Health Connect, benzersiz kayıtları tanımlamak için bu bilgiyi kullanır. Zaten mevcut olan bir clientRecordId ile kayıt yazmaya çalışırsanız Health Connect, yeni bir kayıt oluşturmak yerine kopyayı yok sayar veya mevcut kaydı günceller. metadata.clientRecordId ayarlamak, senkronizasyon yeniden denemeleri veya uygulamanın yeniden yüklenmesi sırasında yinelenenleri ö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 etme: 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 dosyasına yazmadan önce düşük doğruluklu GPS örneklerini (örneğin, 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 sağlık verilerine neden erişmesi gerektiğini açıklamak için Permission.createIntent akışını kullanın. Örneğin: "Tansiyonunuzda gözlemlenen değişimleri izlemek ve analizler sunmak için."
• Duraklatma ve devam ettirme desteği: Uygulamanızın duraklatma işlemlerini doğru şekilde işlediğini doğrulayın. Kullanıcı durakladığında, ortalama tempo ve sürenin doğru kalması için güzergah üzerindeki nokta ve veri türleri toplanmaz.
• Uzun süreli oturumları test edin: Birkaç saat süren oturumlar sırasında pil tüketimini izleyerek toplu iş aralığınızın ve sensör kullanımınızın cihazı tüketmediğini doğrulayın.
• Zaman damgalarını sensör hızlarıyla hizalama: Verilerin yüksek doğruluğunu korumak için kayıt zaman damgalarınızı sensörlerinizin gerçek frekansıyla eşleştirin.

Test

Verilerin doğruluğunu ve yüksek kaliteli bir kullanıcı deneyimini doğrulamak için bu 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ındaki değişiklikleri simüle etmek için bu tamamlayıcı uygulamayı kullanın. Kayıtlarınızın doğru şekilde saklandığını doğrulamanın en iyi yolu budur.
• FakeHealthConnectClient ile birim testi: Uygulamanızın, izin iptali veya API istisnaları gibi uç durumları fiziksel bir cihaza ihtiyaç duymadan 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 kullanılan hata ayıklama adımları