Menulis data

Panduan ini membahas proses penulisan atau pembaruan data di Health Connect.

Menyiapkan struktur data

Sebelum menulis data, kita perlu menyiapkan kumpulan data terlebih dahulu. Lebih dari 50 jenis data memiliki strukturnya masing-masing. Lihat referensi Jetpack untuk mengetahui detail selengkapnya tentang jenis data yang tersedia.

Kumpulan data dasar

Jenis data Langkah di Health Connect mendeteksi jumlah langkah pengguna di sela-sela pembacaan. Jumlah langkah mewakili pengukuran umum di berbagai platform kesehatan dan kebugaran.

Contoh berikut menunjukkan cara menetapkan data jumlah langkah:

val stepsRecord = StepsRecord(
    count = 120,
    startTime = START_TIME,
    endTime = END_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endZoneOffset = END_ZONE_OFFSET
)

Kumpulan data dengan satuan pengukuran

Health Connect dapat menyimpan nilai bersama dengan satuan pengukurannya untuk memberikan akurasi. Salah satu contohnya adalah jenis data Nutrisi yang luas dan komprehensif. Jenis data ini mencakup berbagai bidang gizi opsional, mulai dari total karbohidrat hingga vitamin. Setiap titik data mewakili gizi yang berpotensi dikonsumsi sebagai bagian dari makanan atau item makanan.

Dalam jenis data ini, semua nutrisi ditampilkan dalam satuan Mass, sementara energy ditampilkan dalam satuan Energy.

Contoh berikut menunjukkan cara menetapkan data gizi untuk pengguna yang telah makan pisang:

val banana = NutritionRecord(
    name = "banana",
    energy = 105.0.kilocalories,
    dietaryFiber = 3.1.grams,
    potassium = 0.422.grams,
    totalCarbohydrate = 27.0.grams,
    totalFat = 0.4.grams,
    saturatedFat = 0.1.grams,
    sodium = 0.001.grams,
    sugar = 14.0.grams,
    vitaminB6 = 0.0005.grams,
    vitaminC = 0.0103.grams,
    startTime = START_TIME,
    endTime = END_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endZoneOffset = END_ZONE_OFFSET
)

Kumpulan data dengan data serial

Health Connect dapat menyimpan daftar data serial. Salah satu contohnya adalah jenis data Detak Jantung yang menangkap serangkaian contoh detak jantung yang terdeteksi di antara pembacaan.

Dalam jenis data ini, parameter samples direpresentasikan oleh daftar contoh Detak Jantung. Setiap sampel berisi nilai beatsPerMinute dan nilai time.

Contoh berikut menunjukkan cara menetapkan data seri detak jantung:

val heartRateRecord = HeartRateRecord(
    startTime = START_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endTime = END_TIME,
    endZoneOffset = END_ZONE_OFFSET,
    // records 10 arbitrary data, to replace with actual data
    samples = List(10) { index ->
        HeartRateRecord.Sample(
            time = START_TIME + Duration.ofSeconds(index.toLong()),
            beatsPerMinute = 100 + index.toLong(),
        )
    }
)

Menulis data

Salah satu alur kerja umum di Health Connect adalah menulis data. Untuk menambahkan kumpulan data, gunakan insertRecords.

Contoh berikut menunjukkan cara menulis data dengan menyisipkan jumlah langkah:

suspend fun insertSteps(healthConnectClient: HealthConnectClient) {
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = START_TIME,
            endTime = END_TIME,
            startZoneOffset = START_ZONE_OFFSET,
            endZoneOffset = END_ZONE_OFFSET
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling here
    }
}

Memperbarui data

Jika perlu mengubah satu atau beberapa kumpulan data, terutama saat Anda perlu menyinkronkan datastore aplikasi dengan data dari Health Connect, Anda dapat memperbarui data. Ada dua cara untuk memperbarui data yang ada, yang bergantung pada ID yang digunakan untuk menemukan kumpulan data.

Metadata

Sebaiknya periksa class Metadata terlebih dahulu karena hal ini diperlukan saat memperbarui data. Saat pembuatan, setiap Record di Health Connect memiliki kolom metadata. Properti berikut relevan dengan sinkronisasi:

Properti Deskripsi
id Setiap Record di Health Connect memiliki nilai id yang unik.
Health Connect akan otomatis mengisi ini saat menyisipkan kumpulan data baru.
lastModifiedTime Setiap Record juga melacak kapan terakhir kali kumpulan data diubah.
Health Connect otomatis mengisinya.
clientRecordId Setiap Record dapat memiliki ID unik yang terkait dengannya untuk digunakan sebagai referensi di datastore aplikasi Anda.
Aplikasi Anda menyediakan nilai ini.
clientRecordVersion Jika kumpulan data memiliki clientRecordId, clientRecordVersion dapat digunakan untuk memungkinkan data tetap sinkron dengan versi di datastore aplikasi.
Aplikasi Anda menyediakan nilai ini.

Memperbarui melalui ID Kumpulan Data

Untuk memperbarui data, siapkan kumpulan data yang diperlukan terlebih dahulu. Lakukan perubahan pada kumpulan data jika diperlukan. Selanjutnya, panggil updateRecords untuk melakukan perubahan.

Contoh berikut menunjukkan cara mengupdate data. Untuk tujuan ini, setiap kumpulan data memiliki nilai offset zona yang disesuaikan menjadi PST.

suspend fun updateSteps(
    healthConnectClient: HealthConnectClient,
    prevRecordStartTime: Instant,
    prevRecordEndTime: Instant
) {
    try {
        val request = healthConnectClient.readRecords(
            ReadRecordsRequest(
                recordType = StepsRecord::class,
                timeRangeFilter = TimeRangeFilter.between(
                    prevRecordStartTime,
                    prevRecordEndTime
                )
            )
        )

        val newStepsRecords = arrayListOf<StepsRecord>()
        for (record in request.records) {
            // Adjusted both offset values to reflect changes
            val sr = StepsRecord(
                count = record.count,
                startTime = record.startTime,
                startZoneOffset = record.startTime.atZone(ZoneId.of("PST")).offset,
                endTime = record.endTime,
                endZoneOffset = record.endTime.atZone(ZoneId.of("PST")).offset,
                metadata = record.metadata
            )
            newStepsRecords.add(sr)
        }

        client.updateRecords(newStepsRecords)
    } catch (e: Exception) {
        // Run error handling here
    }
}

Memperbarui dan Menyisipkan melalui ID Kumpulan Data Klien

Jika Anda menggunakan nilai ID Kumpulan Data Klien dan Versi Kumpulan Data Klien opsional, sebaiknya gunakan insertRecords, bukan updateRecords.

Fungsi insertRecords memiliki kemampuan untuk memperbarui dan menyisipkan data. Jika data ada di Health Connect berdasarkan serangkaian ID Kumpulan Data Klien tertentu, data tersebut akan ditimpa. Jika tidak, data akan ditulis sebagai data baru. Skenario ini berguna setiap kali Anda perlu menyinkronkan data dari datastore aplikasi ke Health Connect.

Contoh berikut menunjukkan cara melakukan pembaruan dan penyisipan pada data yang diambil dari datastore aplikasi:

suspend fun pullStepsFromDatastore() : ArrayList<StepsRecord> {
    val appStepsRecords = arrayListOf<StepsRecord>()
    // Pull data from app datastore
    // ...
    // Make changes to data if necessary
    // ...
    // Store data in appStepsRecords
    // ...
    var sr = StepsRecord(
        // Assign parameters for this record
        metadata = Metadata(
            clientRecordId = cid
        )
    )
    appStepsRecords.add(sr)
    // ...
    return appStepsRecords
}

suspend fun upsertSteps(
    healthConnectClient: HealthConnectClient,
    newStepsRecords: ArrayList<StepsRecord>
) {
    try {
        healthConnectClient.insertRecords(newStepsRecords)
    } catch (e: Exception) {
        // Run error handling here
    }
}

Setelah itu, Anda dapat memanggil fungsi ini di thread utama.

upsertSteps(healthConnectClient, pullStepsFromDatastore())

Pemeriksaan nilai di Versi Kumpulan Data Klien

Jika proses pembaruan dan penyisipan data Anda mencakup Versi Kumpulan Data Klien, Health Connect akan melakukan pemeriksaan perbandingan dalam nilai clientRecordVersion. Jika versi dari data yang disisipkan lebih tinggi daripada versi dari data yang ada, pembaruan dan penyisipan akan terjadi. Jika tidak, proses akan mengabaikan perubahan dan nilainya tetap sama.

Untuk menyertakan pembuatan versi dalam data, Anda harus menyediakan Metadata.clientRecordVersion dengan nilai Long berdasarkan logika pembuatan versi.

val sr = StepsRecord(
    count = count,
    startTime = startTime,
    startZoneOffset = startZoneOffset,
    endTime = endTime,
    endZoneOffset = endZoneOffset,
    metadata = Metadata(
        clientRecordId = cid,
        clientRecordVersion = version
    )
)

Pembaruan dan penyisipan tidak otomatis menambah version setiap kali ada perubahan, sehingga mencegah instance yang tidak terduga menimpa data. Dengan demikian, Anda harus menyediakannya dengan nilai yang lebih tinggi secara manual.

Praktik terbaik untuk menulis data

Aplikasi hanya boleh menulis data yang berasal dari aplikasi sendiri ke Health Connect.

Jika data di aplikasi Anda telah diimpor dari aplikasi lain, aplikasi tersebut yang bertanggung jawab untuk menulis data ke Health Connect.

Sebaiknya terapkan logika yang menangani pengecualian penulisan seperti data berada di luar batas, atau error sistem internal. Anda dapat menerapkan strategi backoff dan percobaan ulang pada mekanisme penjadwalan tugas. Jika penulisan ke Health Connect pada akhirnya gagal, pastikan aplikasi Anda dapat melewati titik ekspor tersebut. Jangan lupa mencatat dan melaporkan error untuk membantu diagnosis.

Saat melacak data, ada beberapa saran yang dapat Anda ikuti, bergantung pada cara aplikasi Anda menulis data.

Pelacakan pasif

Mencakup aplikasi yang melakukan pelacakan kebugaran atau kesehatan pasif, seperti mencatat langkah atau detak jantung secara terus-menerus di latar belakang.

Aplikasi Anda perlu menulis data secara berkala ke Health Connect dengan cara berikut:

  • Di setiap sinkronisasi, hanya operasi tulis data baru dan data terbaru yang diubah sejak sinkronisasi terakhir.
  • Tentukan batas permintaan maksimal ke 1.000 data per permintaan tulis.
  • Gunakan WorkManager untuk menjadwalkan tugas latar belakang berkala, dengan jangka waktu minimal 15 menit.
  • Batasi tugas yang akan dijalankan, hanya saat perangkat sedang tidak ada aktivitas dan tidak kehabisan baterai.

    val constraints = Constraints.Builder()
        .requiresBatteryNotLow()
        .requiresDeviceIdle(true)
        .build()
    
    val writeDataWork = PeriodicWorkRequestBuilder<WriteDataToHealthConnectWorker>(
            15,
            TimeUnit.MINUTES,
            5,
            TimeUnit.MINUTES
        )
        .setConstraints(constraints)
        .build()
    

Pelacakan aktif

Ini mencakup aplikasi yang melakukan pelacakan berbasis peristiwa, seperti olahraga dan tidur, atau input pengguna manual seperti nutrisi. Kumpulan data ini dibuat saat aplikasi berada di latar depan, atau dalam peristiwa yang jarang terjadi ketika aplikasi digunakan beberapa kali dalam sehari.

Pastikan aplikasi Anda tidak membuat Health Connect tetap berjalan selama peristiwa berlangsung.

Data harus ditulis ke Health Connect dengan salah satu dari dua cara:

  • Menyinkronkan data ke Health Connect setelah peristiwa selesai. Misalnya, menyinkronkan data saat pengguna mengakhiri sesi olahraga yang dilacak.
  • Menjadwalkan tugas satu kali menggunakan WorkManager untuk menyinkronkan data nanti.

Praktik terbaik untuk perincian dan frekuensi penulisan

Saat menulis data ke Health Connect, gunakan resolusi yang sesuai. Menggunakan resolusi yang tepat akan membantu mengurangi beban penyimpanan, sambil tetap mempertahankan data yang konsisten dan akurat. Resolusi data mencakup 2 hal:

  1. Frekuensi penulisan: seberapa sering aplikasi Anda mendorong data baru ke Health Connect. Misalnya, tulis data baru setiap 15 menit.
  2. Perincian data tertulis: seberapa sering data yang didorong masuk diambil sampelnya. Misalnya, tulis sampel detak jantung setiap 5 dtk. Tidak semua jenis data memerlukan frekuensi sampel yang sama. Tidak banyak manfaat dari memperbarui jumlah langkah data setiap detik, dibandingkan dengan ritme yang lebih jarang, seperti setiap 60 detik. Namun, frekuensi sampel yang lebih tinggi dapat memberikan data kesehatan dan kebugaran mereka. Frekuensi sampel harus mencapai keseimbangan antara detail dan performa.

Menulis data yang dipantau sepanjang hari

Untuk data yang dikumpulkan secara berkelanjutan, seperti langkah-langkah, aplikasi Anda harus menulis ke Health Connect setidaknya setiap 15 menit sepanjang hari.

Jenis data

Satuan

Diperkirakan

Contoh

Langkah

langkah

Setiap 1 menit

23.14 - 23.15 - 5 langkah

23:16 - 23:17 - 22 langkah

23:17 - 23:18 - 8 langkah

Rangkaian Langkah Penjualan

langkah/mnt

Setiap 1 menit

23.14 - 23.15 - 5 spm

23.16 - 23.17 - 22 spm

23.17 - 23.18 - 8 spm

Dorongan kursi roda

mendorong

Setiap 1 menit

23:14 - 23:15 - 5 dorongan

23:16 - 23:17 - 22 dorongan

23:17 - 23:18 - 8 dorongan

Kalori Aktif yang Dibakar

Kalori

Setiap 15 menit

23:15 - 23:30 - 2 Kalori

23:30 - 23:45 - 25 Kalori

23:45 - 00:00 - 5 Kalori

Total Kalori yang Terbakar

Kalori

Setiap 15 menit

23:15 - 23:30 - 16 Kalori

23:30 - 23:45 - 16 Kalori

23:45 - 00:00 - 16 Kalori

Jarak

km/mnt

Setiap 1 menit

23.14-23.15 - 0,008 km

23:16 - 23:16 - 0,021 km

23:17 - 23:18 - 0,012 km

Elevasi yang Dicapai

m

Setiap 1 menit

20.36 - 20.37 - 3.048m

20.39 - 20.40 - 3.048m

23.23 - 23.24 - 9.144m

Lantai yang Dinaiki

lantai

Setiap 1 menit

23:14 - 23:15 - 5 lantai

23:16 - 23:16 - 22 lantai

23:17 - 23:18 - 8 lantai

Detak Jantung

bpm

Setiap 1 menit

06.11 - 55 bpm

Detak JantungVariabilitasRmssd

md

Setiap 1 menit

06.11 - 23 md

Tingkat Pernapasan

napas/menit

Setiap 1 menit

23.14 - 23.15 - 60 napas/menit

23:16 - 23:16 - 62 napas/menit

23:17 - 23:18 - 64 napas/menit

Saturasi Oksigen

%

Setiap 1 jam

6.11 - 95,208%

Menulis sesi

Data harus ditulis ke Health Connect di akhir latihan fisik atau tidur sesi.

Sebagai praktik terbaik, setiap sesi tidur atau sesi latihan harus ditulis dengan perangkat perekam dan metadata yang sesuai, termasuk RecordingMethod.

Setidaknya, aplikasi Anda harus mengikuti panduan dalam laporan "yang diharapkan" di bawah. Lokasi mungkin, ikuti jawaban "terbaik" panduan.

Data yang dilacak selama latihan

Jenis data

Satuan

Diperkirakan

Hormat kami,

Contoh

Langkah

langkah

Setiap 1 menit

Setiap 1 detik

23:14-23:15 - 5 langkah

23:16 - 23:17 - 22 langkah

23:17 - 23:18 - 8 langkah

Rangkaian Langkah Penjualan

langkah/mnt

Setiap 1 menit

Setiap 1 detik

23.14-23.15 - 35 spm

23.16 - 23.17 - 37 spm

23.17—23.18—40 spm

Dorongan kursi roda

mendorong

Setiap 1 menit

Setiap 1 detik

23:14-23:15 - 5 dorongan

23:16 - 23:17 - 22 dorongan

23:17 - 23:18 - 8 dorongan

Rangkaian Langkah PenjualanPedal Sepeda

napas per menit; npm [abbrv., use per context]

Setiap 1 menit

Setiap 1 detik

23.14-23.15 - 65 rpm

23.16 - 23.17 - 70 rpm

23.17 - 23.18 - 68 rpm

Daya

watt

Setiap 1 menit

Setiap 1 detik

23:14-23:15 - 250 watt

23:16 - 23:17 - 255 watt

23:17 - 23:18 - 245 watt

Kecepatan

km/mnt

Setiap 1 menit

Setiap 1 detik

23:14-23:15 - 0,3 km/mnt

23:16 - 23:17 - 0,4 km/mnt

23:17 - 23:18 -0,4 km/mnt

Jarak

km/m

Setiap 1 menit

Setiap 1 detik

23.14-23.15 - 0,008 km

23:16 - 23:16 - 0,021 km

23:17 - 23:18 - 0,012 km

Kalori Aktif yang Dibakar

Kalori

Setiap 1 menit

Setiap 1 detik

23:14-23:15 - 20 Kalori

23:16 - 23:17 - 20 Kalori

23:17 - 23:18 - 25 Kalori

Total Kalori yang Terbakar

Kalori

Setiap 1 menit

Setiap 1 detik

23:14-23:15 - 36 Kalori

23:16 - 23:17 - 36 Kalori

23:17 - 23:18 - 41 Kalori

Elevasi yang Dicapai

m

Setiap 1 menit

Setiap 1 detik

20.36 - 20.37 - 3.048m

20.39 - 20.40 - 3.048m

23.23 - 23.24 - 9.144m

ExerciseRoutes

lat/lng/alt

Setiap 3-5 detik

Setiap 1 detik

Detak Jantung

bpm

Setiap 1 menit

Setiap 1 detik

23.14-23.15 - 150 bpm

23.16 - 23.17 -152 bpm

23.17 - 23.18 - 155 bpm

Data yang dilacak saat tidur

Jenis data

Satuan

Contoh yang diharapkan

Contoh

Pengaturan Tidur

tahap

Periode waktu terperinci per tahapan tidur

23.46 - 23.50 - terbangun

23.50 - 23.56 - tidur ringan

23:56 - 00:16 - tidur nyenyak

Detak Jantung Istirahat

bpm

Satu nilai harian (hal pertama yang diharapkan di pagi hari)

06.11 - 60 bpm

Saturasi Oksigen

%

Satu nilai harian (hal pertama yang diharapkan di pagi hari)

6.11 - 95,208%