Mengembangkan Pengalaman Tidur dengan Health Connect

Jika ingin membuat pengalaman pemantauan pola tidur di aplikasi Anda, 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 di 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 semalaman.
• Membaca data sesi untuk ringkasan dan analisis pasca-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.
• Verifikasi bahwa aplikasi Anda menerapkan alur izin runtime berdasarkan Health Permissions.

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 tahapan tidur. Selama sesi, berbagai jenis data seperti HeartRateRecord atau OxygenSaturationRecord dapat dicatat.

Sesi tidur

Data tidur ditampilkan dengan SleepSessionRecord. Setiap catatan menyimpan:

• startTime
• endTime
• stages: Daftar SleepSessionRecord.Stage termasuk tidur nyenyak, ringan, REM, dan terjaga.
• 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 tahapan tidur, termasuk tidur dalam, tidur ringan, tidur REM, dan terjaga.
• HeartRateRecord: Mencatat detak jantung selama tidur.
• OxygenSaturationRecord: Mencatat saturasi oksigen (SpO2) selama tidur.
• RespiratoryRateRecord: Mencatat laju pernapasan saat tidur.

Setiap jenis data disimpan sebagai data individual.

Pertimbangan pengembangan

Aplikasi pemantauan pola tidur sering kali perlu berjalan dalam jangka waktu yang lama, sering kali di latar belakang saat layar mati. Saat membangun fitur tidur, penting untuk mempertimbangkan cara mengelola eksekusi di 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 status ini, Anda harus menggunakan:

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

Pertahankan kontinuitas dengan menjaga konsistensi ID sesi 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 data tidur, Anda perlu meminta izin berikut:

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

Berikut menunjukkan 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 merekam data tidur.

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

Menulis sesi

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

Untuk menulis sesi tidur:

1. Buat ID catatan klien yang unik.
2. Saat pengguna bangun, atau pemantauan pola tidur dihentikan, kumpulkan semua fase tidur dan buat SleepSessionRecord.
3. Sisipkan rekaman 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 dan kemudian 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 menurut 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 berikut untuk meningkatkan keandalan data dan pengalaman pengguna:

• Sering menulis selama pelacakan aktif: Untuk pelacakan aktif, tulis data saat tersedia atau pada interval maksimum 15 menit.
• Menggunakan WorkManager untuk sinkronisasi latar belakang: Gunakan WorkManager untuk penulisan yang ditangguhkan. Tetapkan interval 15 menit untuk menyeimbangkan data real-time dan efisiensi baterai.
• Permintaan tulis batch: Jangan menulis setiap peristiwa sensor satu per satu. Kelompokkan permintaan Anda. Health Connect menangani hingga 1.000 data per permintaan tulis.
• Menjaga 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 secara terpisah.
• Hindari penulisan data duplikat: Gunakan ID Klien: Saat membuat rekaman, tetapkan metadata.clientRecordId. Health Connect menggunakan 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, kueri rentang waktu untuk melihat apakah ada data dari aplikasi Anda.
• Pastikan stempel waktu tidak tumpang-tindih: Verifikasi bahwa sesi baru tidak dimulai sebelum sesi sebelumnya berakhir. Sesi yang tumpang-tindih dapat menyebabkan konflik di dasbor kebugaran dan perhitungan 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 batching dan penggunaan sensor tidak menguras baterai perangkat.
• Menyelaraskan stempel waktu dengan kecepatan sensor: Cocokkan stempel waktu rekaman Anda dengan frekuensi sebenarnya dari sensor untuk mempertahankan kesetiaan data yang tinggi.

Pengujian

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

Alat verifikasi

• Toolbox Health Connect: Gunakan aplikasi pendamping ini untuk memeriksa catatan secara manual, menghapus data pengujian, dan menyimulasikan perubahan pada database. Cara ini adalah cara terbaik untuk memverifikasi bahwa catatan 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 umum untuk men-debug