Mengembangkan Pengalaman Tidur dengan Health Connect

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

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

• Menulis sesi tidur
• Menulis data fase tidur
• Menulis data tidur seperti detak jantung, saturasi oksigen, dan laju pernapasan
• Membaca data tidur dari aplikasi lain

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

Ringkasan: Membangun Pelacak Tidur yang Komprehensif

Anda dapat membangun pengalaman pemantauan pola tidur yang komprehensif menggunakan Health Connect dengan mengikuti langkah-langkah inti berikut:

• Menerapkan izin dengan benar berdasarkan Izin Kesehatan.
• Merekam sesi menggunakan SleepSessionRecord.
• Menulis jenis data seperti fase tidur, detak jantung, dan saturasi oksigen secara konsisten selama sesi.
• Mengelola eksekusi latar belakang dengan benar untuk memverifikasi pengambilan data berkelanjutan dalam semalam.
• Membaca data sesi untuk ringkasan dan analisis setelah tidur.

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

Sebelum memulai

Sebelum menerapkan fitur tidur:

• Integrasikan Health Connect menggunakan dependensi yang sesuai.
• Buat instance HealthConnectClient.
• Pastikan aplikasi Anda menerapkan alur izin runtime berdasarkan Izin Kesehatan.

Konsep utama

Health Connect merepresentasikan data tidur menggunakan beberapa komponen inti. SleepSessionRecord berfungsi sebagai catatan pusat untuk tidur, yang berisi detail seperti waktu mulai atau berakhir dan fase tidur. Selama sesi, berbagai jenis data seperti HeartRateRecord atau OxygenSaturationRecord dapat direkam.

Sesi tidur

Data tidur diwakili oleh SleepSessionRecord. Setiap data menyimpan:

• startTime
• endTime
• stages: Daftar SleepSessionRecord.Stage yang mencakup tidur nyenyak, ringan, REM, dan bangun.
• Metadata sesi opsional (judul, catatan)

Aplikasi dapat menulis beberapa jenis data yang terkait dengan sesi.

Jenis data

Jenis data umum yang dicatat selama sesi tidur meliputi:

• SleepSessionRecord: Mencatat durasi dan fase tidur, termasuk tidur dalam, tidur ringan, REM, dan bangun.
• HeartRateRecord: Merekam detak jantung selama tidur.
• OxygenSaturationRecord: Mencatat saturasi oksigen (SpO2) selama tidur.
• RespiratoryRateRecord: Mencatat laju pernapasan selama tidur.

Setiap jenis data disimpan sebagai data individual.

Pertimbangan pengembangan

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

Eksekusi latar belakang

Aplikasi pemantauan pola tidur biasanya berjalan semalaman dengan layar nonaktif. Saat dalam keadaan ini, Anda harus menggunakan:

• Layanan latar depan untuk pengumpulan data
• WorkManager untuk penulisan atau sinkronisasi yang ditangguhkan
• Strategi pengelompokan untuk penulisan data terperinci secara rutin seperti detak jantung

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 tidur. Untuk mengetahui daftar lengkap jenis data, lihat Jenis data Health Connect. Izin umum untuk tidur mencakup sesi tidur dan metrik seperti detak jantung atau saturasi oksigen.

Akses ke tidur dilindungi oleh izin berikut:

• android.permission.health.READ_SLEEP
• android.permission.health.WRITE_SLEEP

Untuk menambahkan kemampuan tidur ke aplikasi Anda, mulailah dengan meminta izin untuk jenis data SleepSession.

Berikut adalah izin yang harus Anda deklarasikan agar dapat menulis tidur:

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

Untuk membaca tidur, Anda perlu meminta izin berikut:

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

Berikut adalah contoh cara meminta izin untuk sesi tidur yang mencakup data detak jantung, saturasi oksigen, dan laju pernapasan:

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(SleepSessionRecord::class),
        HealthPermission.getWritePermission(SleepSessionRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class),
        HealthPermission.getReadPermission(OxygenSaturationRecord::class),
        HealthPermission.getWritePermission(OxygenSaturationRecord::class),
        HealthPermission.getReadPermission(RespiratoryRateRecord::class),
        HealthPermission.getWritePermission(RespiratoryRateRecord::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

Menerapkan sesi tidur

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

Untuk menyelaraskan jenis data seperti HeartRateRecord atau OxygenSaturationRecord dengan sesi tidur, catat data tersebut dengan stempel waktu yang berada di antara startTime dan endTime sesi. Health Connect tidak menggunakan ID sesi untuk menautkan sesi tidur dengan data terperinci. Sebagai gantinya, pengaitan bersifat implisit melalui interval waktu yang tumpang-tindih. Saat membaca data tidur, Anda dapat menggunakan rentang waktu sesi untuk mengkueri jenis data terkait, seperti yang ditunjukkan dalam Membaca data tidur.

Menulis sesi

Meskipun data terperinci seperti detak jantung dapat dicatat selama sesi tidur, SleepSessionRecord itu sendiri hanya boleh ditulis ke Health Connect setelah sesi selesai, misalnya saat pengguna bangun. Data harus menyertakan startTime, endTime sesi, dan daftar objek SleepSessionRecord.Stage yang dicatat selama sesi, karena SleepSessionRecord mengharuskan endTime berada setelah startTime.

Untuk menulis sesi tidur:

1. Buat ID data klien yang unik.
2. Saat pengguna bangun, atau pemantauan pola tidur dihentikan, kumpulkan semua fase tidur dan buat SleepSessionRecord.
3. Sisipkan data menggunakan insertRecords.

Contoh:

val clientRecordId = UUID.randomUUID().toString()
val sessionStartTime = LocalDateTime.of(2023, 10, 30, 22, 0).toInstant(ZoneOffset.UTC)
val sessionEndTime = LocalDateTime.of(2023, 10, 31, 7, 0).toInstant(ZoneOffset.UTC)

val stages = mutableListOf<SleepSessionRecord.Stage>()
// Add recorded stages, for example:
stages.add(SleepSessionRecord.Stage(
    startTime = sessionStartTime.plusSeconds(3600),
    endTime = sessionStartTime.plusSeconds(7200),
    stage = SleepSessionRecord.STAGE_TYPE_LIGHT)
)
stages.add(SleepSessionRecord.Stage(
    startTime = sessionStartTime.plusSeconds(7200),
    endTime = sessionStartTime.plusSeconds(10800),
    stage = SleepSessionRecord.STAGE_TYPE_DEEP)
)
// ... other stages

val session = SleepSessionRecord(
    startTime = sessionStartTime,
    startZoneOffset = ZoneOffset.UTC,
    endTime = sessionEndTime,
    endZoneOffset = ZoneOffset.UTC,
    stages = stages,
    metadata = Metadata(clientRecordId = clientRecordId)
)

healthConnectClient.insertRecords(listOf(session))

Membaca data tidur

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

Sesi baca dengan data terkait

Anda dapat membaca sesi tidur menggunakan ReadRecordsRequest dengan SleepSessionRecord sebagai jenis data, yang difilter menurut rentang waktu. Untuk membaca data terkait untuk sesi tertentu, buat permintaan kedua untuk jenis data yang dipilih, seperti HeartRateRecord—memfilter berdasarkan startTime dan endTime sesi tidur.

Contoh berikut menunjukkan cara membaca sesi tidur dengan data detak jantung terkait untuk rentang waktu tertentu:

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

    for (sleepRecord in response.records) {
        // Process each session
        val stages = sleepRecord.stages
        val notes = sleepRecord.notes

        // To read specific granular data (like heart rate) that occurred during
        // this session, use the session's startTime and endTime to filter
        // the request for that data type.
        val hrResponse = healthConnectClient.readRecords(
            ReadRecordsRequest(
                recordType = HeartRateRecord::class,
                timeRangeFilter = TimeRangeFilter.between(
                    sleepRecord.startTime,
                    sleepRecord.endTime
                )
            )
        )
        for (heartRateRecord in hrResponse.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: 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.
• 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'.
• 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 pemantauan pola tidur biasanya mencakup:

Pemecahan masalah

Langkah-langkah proses debug umum