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 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 izleyici oluşturma

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

• Sağlık İzinleri'ne göre izinlerin doğru şekilde uygulanması.
• ExerciseSessionRecord kullanılarak oturum kaydı yapılması.
• 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ışabilmeyi sağlar ve kullanıcı kontrollü 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, çalışma zamanı izin akışlarını Sağlık İzinleri'ne göre 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 seansları

ExerciseSessionRecord, antrenman verilerinin merkezi kaydıdır ve tek bir antrenman oturumunu temsil eder. Her kayıt şu bilgileri saklar:

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

Bir 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 de kaydedilip oturumla ilişkilendirilebilir.

İlişkili veri türleri

Antrenman seanslarıyla ilişkili veriler, ayrı kayıt türleriyle gösterilir. 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 antrenmanlarıyla 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, bir egzersiz oturumunun sıralı konum verilerini içerir. Health Connect'te bağımsız bir kayıt olarak ele alınmaz. Bunun yerine, ExerciseSessionRecord eklerken veya güncellerken ExerciseRoute 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. Antrenman özelliklerinizi oluştururken arka planda yürütmeyi nasıl yöneteceğinizi ve antrenman 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 destek, şunları 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.
• Distance: 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.
• 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ın izinleri istedikleri zaman vermesine veya reddetmesine izin verilmelidir.

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.

// Create a set of permissions for required data types
val PERMISSIONS =
    setOf(
  HealthPermission.getReadPermission(ExerciseSessionRecord::class),
  HealthPermission.getWritePermission(ExerciseSessionRecord::class),
  HealthPermission.getReadPermission(ExerciseRoute::class),
  HealthPermission.getWritePermission(ExerciseRoute::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)
)

Uygulamanıza gerekli izinlerin verilip verilmediğini görmek için getGrantedPermissions aracını kullanın. Aksi takdirde, bu izinleri istemek için createRequestPermissionResultContract seçeneğini kullanın. Bu işlem, Health Connect izinleri ekranını gösterir.

// Create the permissions launcher
val requestPermissionActivityContract = PermissionController.createRequestPermissionResultContract()

val requestPermissions = registerForActivityResult(requestPermissionActivityContract) { granted ->
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions successfully granted
  } else {
    // Lack of required permissions
  }
}

suspend fun checkPermissionsAndRun(healthConnectClient: HealthConnectClient) {
  val granted = healthConnectClient.permissionController.getGrantedPermissions()
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions already granted; proceed with inserting or reading data
  } else {
    requestPermissions.launch(PERMISSIONS)
  }
}

Kullanıcılar izinleri istedikleri zaman verebilir veya iptal edebilir. Bu nedenle, uygulamanız izinleri kullanmadan önce her seferinde kontrol etmeli ve izinlerin kaybedildiği senaryoları ele almalıdır.

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

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

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:

Kalp atış hızına 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. ExerciseSessionRecord yazın: 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 sessionId = UUID.randomUUID().toString()
val sessionClientId = UUID.randomUUID().toString()

val session = ExerciseSessionRecord(
    id = sessionId,
    exerciseType = ExerciseType.EXERCISE_TYPE_RUNNING,
    startTime = Instant.now(),
    endTime = null,
    metadata = Metadata(clientRecordId = sessionClientId),
)

healthConnectClient.insertRecords(listOf(session))

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 kaydettiğiniz 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, aktiviteyi ö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, bir ExerciseSessionRecord okuyabilir ve ardından aynı zaman aralığında gerçekleşen HeartRateRecord veya DistanceRecord hakkında sorgu oluşturabilirsiniz.

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 okunmalıdır. Oturumun rota verilerini okumak için oturum 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 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:

• Yazma Sıklığı
  • Etkin İzleme(Ön Plan): Etkin egzersizler için verileri kullanılabilir hale geldikçe veya en fazla 15 dakikalık aralıklarla yazın.
  • Arka plan senkronizasyonu: Ertelenmiş yazma işlemleri için WorkManager kullanın. Anlık veriler ve pil verimliliği arasında denge kurmak için 15 dakikalık bir aralık hedefleyin.
  • Toplu işleme: Her bir 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 antrenman olarak değerlendirilmesini engeller.
• 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 değerini 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, yinelenen kaydı yoksayar veya yeni bir kayıt oluşturmak yerine mevcut kaydı günceller. Senkronizasyon yeniden denemeleri veya uygulama yeniden yüklemeleri sırasında yinelenen öğeleri önlemenin en etkili yolu metadata.clientRecordId ayarlamaktır.

  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'a 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, bir ö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, "Koşularınızı haritalandırmak ve yakılan kaloriyi hesaplamak 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 edin: 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 (ör. GPS için 1 Hz) 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 sık kullanılan test senaryoları dokümanına 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ı