Mengembangkan Pengalaman Olahraga dengan Health Connect

Panduan ini kompatibel dengan Health Connect versi 1.1.0 atau yang lebih baru.

Jika ingin membangun pengalaman olahraga di aplikasi, Anda dapat menggunakan Health Connect untuk melakukan hal-hal seperti:

• Menulis sesi latihan
• Menulis rute olahraga
• Menulis metrik olahraga seperti detak jantung, kecepatan, dan jarak
• Membaca data latihan fisik dari aplikasi lain

Panduan ini menjelaskan cara membuat fitur olahraga ini, yang mencakup jenis data, eksekusi latar belakang, izin, alur kerja yang direkomendasikan, dan praktik terbaik.

Ringkasan: Membangun Pelacak Latihan yang Komprehensif

Anda dapat membangun pengalaman pelacakan olahraga yang komprehensif menggunakan Health Connect dengan mengikuti langkah-langkah inti berikut:

• Menerapkan izin dengan benar berdasarkan Izin Kesehatan.
• Merekam sesi menggunakan ExerciseSessionRecord.
• Menulis data latihan secara konsisten selama sesi.
• Mengelola eksekusi latar belakang dengan benar untuk memverifikasi pengambilan data berkelanjutan.
• Membaca data sesi untuk ringkasan dan analisis pasca-latihan.

Alur kerja ini memungkinkan interoperabilitas dengan aplikasi Health Connect lainnya dan memverifikasi akses data yang dikontrol pengguna.

Sebelum memulai

Sebelum menerapkan fitur olahraga:

• Integrasikan Health Connect menggunakan dependensi yang sesuai.
• Buat instance HealthConnectClient.
• Pastikan aplikasi Anda menerapkan alur izin runtime berdasarkan Izin Kesehatan.
• Jika alur kerja Anda menggunakan GPS, siapkan izin akses lokasi dan layanan latar depan.

Konsep utama

Health Connect merepresentasikan data olahraga menggunakan beberapa komponen inti. ExerciseSessionRecord berfungsi sebagai catatan pusat untuk latihan, yang berisi detail seperti waktu mulai atau berakhir dan jenis latihan. Selama sesi, berbagai jenis data seperti HeartRateRecord atau SpeedRecord dapat direkam. Untuk aktivitas luar ruangan, ExerciseRoute menyimpan data GPS, yang ditautkan ke sesi yang sesuai.

Sesi olahraga

ExerciseSessionRecord adalah data pusat untuk data olahraga, yang mewakili satu sesi olahraga. Setiap data menyimpan:

• startTime
• endTime
• exerciseType
• Metadata sesi opsional (judul, catatan)

ExerciseSessionRecord juga dapat berisi rute, putaran, dan segmen latihan sebagai bagian dari datanya. Selain itu, jenis data lain seperti HeartRateRecord atau SpeedRecord dapat dicatat selama sesi dan dikaitkan dengannya.

Jenis data terkait

Data yang terkait dengan sesi olahraga diwakili oleh jenis data individual. Jenis yang umum meliputi:

• HeartRateRecord: Mewakili serangkaian pengukuran detak jantung.
• SpeedRecord: Mewakili serangkaian pengukuran kecepatan.
• DistanceRecord: Menunjukkan jarak yang ditempuh di antara pembacaan.
• TotalCaloriesBurnedRecord: Menampilkan total kalori yang terbakar di antara pembacaan.
• ElevationGainedRecord: Mewakili elevasi yang diperoleh di antara pembacaan.
• StepsCadenceRecord: Mewakili ritme langkah di antara pembacaan.
• PowerRecord: Menampilkan output daya di antara pembacaan, yang umum dalam aktivitas seperti bersepeda.

Untuk mengetahui daftar lengkap jenis data, lihat Jenis data Health Connect.

Rute olahraga

Anda dapat mengaitkan rute dengan olahraga di luar ruangan menggunakan ExerciseRoute. Rute terdiri dari objek ExerciseRoute.Location berurutan yang masing-masing berisi:

• Lintang dan bujur
• Ketinggian opsional
• Arah opsional
• Informasi akurasi
• Stempel waktu

Rute sesi link

ExerciseRoute berisi data lokasi berurutan untuk sesi latihan. Data ini tidak diperlakukan sebagai data independen di Health Connect. Sebagai gantinya, Anda memberikan data ExerciseRoute saat menyisipkan atau mengupdate ExerciseSessionRecord.

Pertimbangan pengembangan

Aplikasi pelacakan olahraga sering kali perlu berjalan dalam waktu lama, sering kali di latar belakang saat layar nonaktif. Saat membuat fitur olahraga, penting untuk mempertimbangkan cara mengelola eksekusi latar belakang dan meminta izin yang diperlukan untuk data olahraga.

Eksekusi latar belakang

Aplikasi olahraga biasanya berjalan dengan layar nonaktif. Saat dalam status ini, Anda harus menggunakan:

• Layanan latar depan untuk pengambilan sampel lokasi dan sensor
• WorkManager untuk penulisan atau sinkronisasi yang ditangguhkan
• Strategi pengelompokan untuk penulisan data reguler

Pertahankan kontinuitas dengan menjaga ID sesi tetap konsisten di semua penulisan.

Izin

Aplikasi Anda harus meminta izin Health Connect yang relevan sebelum membaca atau menulis data olahraga. Izin umum untuk olahraga mencakup sesi olahraga, rute olahraga, dan metrik seperti detak jantung atau kecepatan. Ini mencakup hal-hal berikut:

• Sesi latihan: Izin baca dan tulis untuk ExerciseSessionRecord.
• Rute olahraga: Izin baca dan tulis untuk ExerciseRoute.
• Detak jantung: Izin baca dan tulis untuk HeartRateRecord.
• Kecepatan: Izin baca dan tulis untuk SpeedRecord.
• Jarak: Izin baca dan tulis untuk DistanceRecord.
• Kalori: Izin baca dan tulis untuk TotalCaloriesBurnedRecord.
• Elevasi Naik: Izin baca dan tulis untuk ElevationGainedRecord.
• Ritme Langkah: Izin baca dan tulis untuk StepsCadenceRecord.
• Power: Izin baca dan tulis untuk PowerRecord.
• Langkah-langkah: Izin baca dan tulis untuk StepsRecord.

Berikut adalah contoh cara meminta beberapa izin untuk sesi olahraga yang mencakup data rute, detak jantung, jarak, kalori, kecepatan, dan langkah:

Setelah membuat instance klien, aplikasi Anda perlu meminta izin dari pengguna. Pengguna harus diizinkan untuk memberikan atau menolak izin kapan saja. Untuk melakukannya, buat kumpulan izin untuk jenis data yang diperlukan. Pastikan izin dalam kumpulan dideklarasikan dalam manifes Android Anda terlebih dahulu.

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

Untuk meminta izin, panggil fungsi checkPermissionsAndRun:

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

Jika Anda hanya perlu meminta izin untuk satu jenis data, seperti detak jantung, sertakan hanya jenis data tersebut dalam set izin Anda:

Akses ke detak jantung dilindungi oleh izin berikut:

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

Untuk menambahkan kemampuan detak jantung ke aplikasi Anda, mulailah dengan meminta izin untuk jenis data HeartRateRecord.

Berikut adalah izin yang harus Anda deklarasikan agar dapat menulis detak jantung:

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

Untuk membaca detak jantung, Anda perlu meminta izin berikut:

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

Menerapkan sesi latihan fisik

Bagian ini menjelaskan alur kerja yang direkomendasikan untuk mencatat data latihan.

Mulai sesi

Untuk membuat latihan fisik baru:

1. Buat ID sesi yang unik: Pastikan ID ini stabil. Jika proses aplikasi Anda dihentikan dan dimulai ulang, Anda harus dapat melanjutkan penggunaan ID yang sama untuk mencegah sesi yang terfragmentasi.
2. Tetapkan metadata.clientRecordId untuk mencegah duplikat selama percobaan ulang sinkronisasi.
3. Tulis ExerciseSessionRecord: Sertakan waktu mulai.
4. Mulai mengumpulkan Jenis data dan data GPS: Hanya mulai setelah data sesi berhasil diinisialisasi.

Contoh:

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

Mencatat rute olahraga

Untuk mempelajari lebih lanjut panduan pembacaan, lihat Membaca data mentah.

Saat merekam rute olahraga, Anda harus mengelompokkan data. Artinya, alih-alih menyimpan setiap titik GPS saat terjadi, Anda mengumpulkan sekelompok titik dan menyimpan semuanya sekaligus dalam satu panggilan.

Hal ini penting karena setiap kali aplikasi Anda membaca atau menulis ke Health Connect, aplikasi tersebut menggunakan sedikit daya baterai dan pemrosesan.

Kode berikut menunjukkan cara mencatat dalam batch:

// 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))

Mengakhiri sesi

Setelah menghentikan pengumpulan data:

• Memperbarui data: Aplikasi Anda mengupdate ExerciseSessionRecord dengan endTime.
• Menyelesaikan data: Secara opsional, hitung nilai ringkasan (seperti total jarak atau kecepatan rata-rata) dan tulis sebagai data tambahan.

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

Membaca data olahraga

Aplikasi dapat membaca sesi latihan dan data terkaitnya untuk meringkas aktivitas, memberikan insight kesehatan, atau menyinkronkan data dengan server eksternal. Misalnya, Anda dapat membaca ExerciseSessionRecord, lalu mengkueri HeartRateRecord atau DistanceRecord yang terjadi selama interval waktu yang sama.

Jika Anda perlu menyinkronkan data olahraga dengan server backend, atau terus memperbarui datastore aplikasi dengan Health Connect, gunakan ChangeLogs. Dengan begitu, Anda dapat mengambil daftar data yang disisipkan, diperbarui, atau dihapus sejak waktu tertentu, yang lebih efisien daripada melacak perubahan secara manual atau membaca semua data berulang kali. Untuk mengetahui informasi selengkapnya, lihat Menyinkronkan data dengan Health Connect.

Membaca sesi

Untuk membaca sesi olahraga, gunakan ReadRecordsRequest dengan ExerciseSessionRecord sebagai jenisnya. Anda biasanya memfilter ini berdasarkan rentang waktu tertentu.

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
    }
}

Membaca rute

Meskipun data ExerciseRoute ditulis sebagai bagian dari sesi latihan, data tersebut harus dibaca secara terpisah. Gunakan metode getExerciseRoute() dengan ID sesi untuk membaca data rutenya:

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
        }
    }
}

Membaca jenis data

Untuk membaca data terperinci tertentu (seperti detak jantung) yang terjadi selama sesi, gunakan startTime dan endTime sesi untuk memfilter permintaan untuk jenis data tersebut.

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
        }
    }
}

Praktik terbaik

Ikuti panduan ini untuk meningkatkan keandalan data dan pengalaman pengguna:

• Tulis data secara rutin selama pelacakan aktif: Untuk pelacakan aktif, tulis data saat tersedia atau dengan interval maksimum 15 menit.
• Gunakan WorkManager untuk sinkronisasi latar belakang: Gunakan WorkManager untuk penulisan yang ditangguhkan. Tetapkan interval 15 menit untuk mencapai keseimbangan antara data real-time dan efisiensi baterai.
• Permintaan tulis batch: Jangan menulis setiap peristiwa sensor satu per satu. Membagi permintaan Anda menjadi beberapa bagian. Health Connect menangani hingga 1.000 data per permintaan tulis.
• Pastikan ID sesi tetap stabil dan unik: Gunakan ID yang konsisten untuk sesi Anda. Jika sesi diedit atau diperbarui, penggunaan ID yang sama akan mencegah sesi tersebut diperlakukan sebagai sesi baru yang terpisah.
• Gunakan pengelompokan untuk jenis data dan titik rute: Untuk mengurangi overhead Input/Output dan menghemat masa pakai baterai, kelompokkan titik data Anda ke dalam satu panggilan insertRecords, bukan menulis setiap titik satu per satu.
• Menghindari penulisan data duplikat: Gunakan Client ID: Saat membuat data, tetapkan metadata.clientRecordId. Health Connect menggunakan ID ini untuk mengidentifikasi data unik. Jika Anda mencoba menulis data dengan clientRecordId yang sudah ada, Health Connect akan mengabaikan duplikat atau memperbarui data yang ada, bukan membuat data baru. Menetapkan metadata.clientRecordId adalah cara paling efektif untuk mencegah duplikat selama percobaan ulang sinkronisasi atau penginstalan ulang aplikasi.
  

  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"
      )
  )

• Periksa data yang ada: Sebelum menyinkronkan, buat kueri rentang waktu untuk melihat apakah data dari aplikasi Anda sudah ada.
• Validasi akurasi GPS: Filter sampel GPS dengan akurasi rendah (Misalnya, titik dengan radius akurasi horizontal tinggi) sebelum menulis ke ExerciseRoute untuk memverifikasi bahwa peta terlihat bersih dan profesional.
• Pastikan stempel waktu tidak tumpang-tindih: Pastikan sesi baru tidak dimulai sebelum sesi sebelumnya berakhir. Sesi yang tumpang-tindih dapat menyebabkan konflik di dasbor kebugaran dan penghitungan ringkasan.
• Berikan alasan yang jelas untuk izin: Gunakan alur Permission.createIntent untuk menjelaskan alasan aplikasi Anda memerlukan akses ke data kesehatan, misalnya: 'Untuk memantau tren tekanan darah Anda dan memberikan insight'.
• Mendukung jeda dan lanjutkan: Pastikan aplikasi Anda menangani jeda dengan benar. Saat pengguna menjeda, berhenti mengumpulkan titik rute dan jenis data agar kecepatan dan durasi rata-rata tetap akurat.
• Uji sesi yang berjalan lama: Pantau konsumsi baterai selama sesi yang berlangsung beberapa jam untuk memverifikasi bahwa interval pengelompokan dan penggunaan sensor tidak menguras daya perangkat.
• Selaraskan stempel waktu dengan kecepatan sensor: Cocokkan stempel waktu data Anda dengan frekuensi sebenarnya sensor Anda untuk mempertahankan fidelitas tinggi data.

Pengujian

Untuk memverifikasi kebenaran data dan pengalaman pengguna yang berkualitas tinggi, ikuti strategi pengujian ini dan lihat dokumentasi resmi Menguji kasus penggunaan teratas.

Alat verifikasi

• Toolbox Health Connect: Gunakan aplikasi pendamping ini untuk memeriksa data secara manual, menghapus data pengujian, dan menyimulasikan perubahan pada database. Ini adalah cara terbaik untuk memverifikasi bahwa data Anda disimpan dengan benar.
• Pengujian unit dengan FakeHealthConnectClient: Gunakan library pengujian untuk memverifikasi cara aplikasi Anda menangani kasus ekstrem, seperti pencabutan izin atau pengecualian API tanpa memerlukan perangkat fisik.

Checklist kualitas

Arsitektur umum

Penerapan olahraga biasanya mencakup:

Pemecahan masalah

Langkah-langkah proses debug umum