Menyinkronkan data

Panduan ini kompatibel dengan Health Connect versi 1.1.0-alpha12.

Sebagian besar aplikasi yang terintegrasi dengan Health Connect memiliki datastore sendiri yang berfungsi sebagai sumber kebenaran. Health Connect memberikan cara untuk membuat aplikasi Anda tetap sinkron.

Bergantung pada arsitektur aplikasi Anda, proses sinkronisasi mungkin melibatkan beberapa atau semua tindakan berikut:

  • Memasukkan data baru atau yang diperbarui dari datastore aplikasi ke Health Connect.
  • Mengambil perubahan data dari Health Connect ke datastore aplikasi Anda.
  • Menghapus data dari Health Connect saat dihapus di datastore aplikasi Anda.

Dalam setiap kasus, pastikan proses sinkronisasi menjaga Health Connect dan datastore aplikasi Anda tetap selaras.

Memasukkan data ke Health Connect

Bagian pertama proses sinkronisasi adalah memasukkan data dari datastore aplikasi ke datastore Health Connect.

Menyiapkan data Anda

Biasanya, data di datastore aplikasi memiliki detail berikut:

  • Kunci unik, seperti UUID.
  • Versi atau stempel waktu.

Saat menyinkronkan data ke Health Connect, identifikasi dan masukkan hanya data yang telah disisipkan, diperbarui, atau dihapus sejak sinkronisasi terakhir.

Menulis data ke Health Connect

Untuk memasukkan data ke Health Connect, lakukan langkah-langkah berikut:

  1. Dapatkan daftar entri baru, yang diperbarui, atau yang dihapus dari datastore aplikasi Anda.
  2. Untuk setiap entri, buat objek Record yang sesuai untuk jenis data tersebut. Misalnya, buat objek WeightRecord untuk data yang terkait dengan berat.

  3. Tentukan objek Metadata dengan setiap Record. Hal ini mencakup clientRecordId, yang merupakan ID dari datastore aplikasi yang dapat Anda gunakan untuk mengidentifikasi data secara unik. Anda dapat menggunakan kunci unik yang sudah ada untuk tindakan ini. Jika data Anda diberi versi, berikan juga clientRecordVersion yang sesuai dengan pemberian versi yang digunakan dalam data Anda. Jika tidak memiliki versi, Anda dapat menggunakan nilai Long dari stempel waktu saat ini sebagai alternatif.

    val recordVersion = 0L
// Specify as needed
// The clientRecordId is an ID that you choose for your record. This
// is often the same ID you use in your app's datastore.
val clientRecordId = "<your-record-id>"

val record = WeightRecord(
    metadata = Metadata.activelyRecorded(
        clientRecordId = clientRecordId,
        clientRecordVersion = recordVersion,
        device = Device(type = Device.TYPE_SCALE)
    ),
    weight = Mass.kilograms(62.0),
    time = Instant.now(),
    zoneOffset = ZoneOffset.UTC,
)
healthConnectClient.insertRecords(listOf()(record))

  4. Perbarui dan masukkan data ke Health Connect menggunakan insertRecords. Memperbarui dan memasukkan data berarti bahwa setiap data yang ada di Health Connect akan ditimpa selama nilai clientRecordId ada di datastore Health Connect, dan clientRecordVersion lebih tinggi dari nilai yang ada. Jika tidak, data yang telah diperbarui dan dimasukkan akan ditulis sebagai data baru.

    healthConnectClient.insertRecords(arrayListOf(record))

Untuk mempelajari pertimbangan praktis terkait memasukkan data, lihat praktik terbaik untuk Menulis data.

Menyimpan ID Health Connect

Jika aplikasi Anda juga membaca data dari Health Connect, simpan id Health Connect untuk data setelah Anda memperbarui dan memasukkannya. Anda memerlukan id ini untuk memproses penghapusan saat Anda menarik perubahan data dari Health Connect.

Fungsi insertRecords menampilkan InsertRecordsResponse yang berisi daftar nilai id. Gunakan respons untuk mendapatkan ID Data dan menyimpannya.

val response = healthConnectClient.insertRecords(arrayListOf(record))

for (recordId in response.recordIdsList) {
    // Store recordId to your app's datastore
}

Mengambil data dari Health Connect

Bagian kedua dari proses sinkronisasi adalah mengambil perubahan data apa pun dari Health Connect ke datastore aplikasi Anda. Perubahan data dapat mencakup pembaruan dan penghapusan.

Mendapatkan token Perubahan

Untuk mendapatkan daftar perubahan yang akan diambil dari Health Connect, aplikasi Anda harus melacak token Perubahan. Anda dapat menggunakannya saat meminta Perubahan untuk menampilkan daftar perubahan data, dan token Perubahan baru untuk digunakan pada waktu berikutnya.

Untuk mendapatkan token Perubahan, panggil getChangesToken dan berikan jenis data yang diperlukan.

val changesToken = healthConnectClient.getChangesToken(
    ChangesTokenRequest(recordTypes = setOf(WeightRecord::class))
)

Memeriksa perubahan data

Setelah Anda mendapatkan token Perubahan, gunakan token tersebut untuk mendapatkan semua Perubahan. Sebaiknya buat loop untuk menyelesaikan semua Perubahan tempat loop memeriksa apakah ada perubahan data yang tersedia. Ikuti langkah-langkah berikut:

  1. Panggil getChanges menggunakan token untuk mendapatkan daftar Perubahan.
  2. Periksa setiap perubahan apakah jenis perubahannya adalah UpsertionChange atau DeletionChange, dan lakukan operasi yang diperlukan.
    • Untuk UpsertionChange, hanya ambil perubahan yang tidak berasal dari aplikasi panggilan untuk memastikan Anda tidak mengimpor ulang data.
  3. Tetapkan token Perubahan berikutnya sebagai token baru.
  4. Ulangi Langkah 1-3 hingga tidak ada Perubahan yang tersisa.
  5. Simpan token berikutnya dan cadangkan untuk impor pada masa mendatang.
suspend fun processChanges(token: String): String {
    var nextChangesToken = token
    do {
        val response = healthConnectClient.getChanges(nextChangesToken)
        response.changes.forEach { change ->
            when (change) {
                is UpsertionChange ->
                    if (change.record.metadata.dataOrigin.packageName != context.packageName) {
                        processUpsertionChange(change)
                    }
                is DeletionChange -> processDeletionChange(change)
            }
        }
        nextChangesToken = response.nextChangesToken
    } while (response.hasMore)
    // Return and store the changes token for use next time.
    return nextChangesToken
}

Guna mempelajari pertimbangan praktis untuk mengambil data, lihat praktik terbaik untuk Menyinkronkan data.

Memproses perubahan data

Cerminkan perubahan pada datastore aplikasi Anda. Untuk UpsertionChange, gunakan id dan lastModifiedTime dari metadata-nya guna memperbarui dan memasukkan data. Untuk DeletionChange, gunakan id yang disediakan guna menghapus data. Hal ini mengharuskan Anda menyimpan id catatan seperti yang disebutkan dalam Menyimpan ID Health Connect.

Menghapus data dari Health Connect

Saat pengguna menghapus datanya sendiri dari aplikasi Anda, pastikan data tersebut juga dihapus dari Health Connect. Gunakan deleteRecords untuk melakukannya. Tindakan ini memerlukan jenis data dan daftar nilai id dan clientRecordId, yang memudahkan pengelompokan beberapa data untuk dihapus. deleteRecords alternatif yang menerima timeRangeFilter juga tersedia.

Praktik terbaik untuk menyinkronkan data

Faktor-faktor berikut memengaruhi proses sinkronisasi.

Akhir masa berlaku token

Karena masa berlaku token Changes yang tidak digunakan akan habis dalam waktu 30 hari, Anda harus menggunakan strategi sinkronisasi agar tidak kehilangan informasi dalam kasus tersebut. Strategi Anda dapat mencakup pendekatan berikut:

  • Mencari datastore aplikasi Anda untuk menemukan data yang baru saja digunakan dan juga memiliki id dari Health Connect.
  • Meminta kumpulan data dari Health Connect yang dimulai dengan stempel waktu tertentu, lalu sisipkan atau perbarui kumpulan data tersebut di datastore aplikasi.
  • Meminta token Changes untuk memesannya pada saat berikutnya diperlukan.

Strategi manajemen Changes yang direkomendasikan

Jika aplikasi Anda mendapatkan token Changes yang tidak valid atau sudah tidak berlaku lagi, sebaiknya gunakan strategi pengelolaan berikut, bergantung pada penerapannya dalam logika Anda:

  • Membaca dan menghapus duplikat semua data. Ini adalah strategi yang paling ideal.
    • Simpan stempel waktu terakhir saat data dari Health Connect dibaca.
    • Saat masa berlaku token habis, baca ulang semua data dari stempel waktu terbaru atau selama 30 hari terakhir. Kemudian, hapus duplikat data tersebut dari data yang sebelumnya dibaca menggunakan ID.
    • Idealnya, implementasikan Client ID karena bersifat wajib untuk pembaruan data.
  • Hanya membaca data sejak stempel waktu baca terakhir. Hal ini menyebabkan beberapa perbedaan data saat masa berlaku token Changes berakhir, tetapi jangka waktunya lebih singkat dan dapat memerlukan waktu beberapa jam hingga beberapa hari.
    • Simpan stempel waktu terakhir saat data dari Health Connect dibaca.
    • Saat masa berlaku token berakhir, baca semua data dari stempel waktu ini dan seterusnya.
  • Menghapus, lalu membaca data dari 30 hari terakhir. Hal ini lebih sesuai dengan hal yang terjadi pada integrasi pertama.
    • Hapus semua data yang dibaca aplikasi dari Health Connect selama 30 hari terakhir.
    • Setelah dihapus, baca lagi semua data ini.
  • Membaca data dari 30 hari terakhir tanpa menghapus duplikat. Ini adalah strategi yang paling tidak ideal, dan membuat data duplikat ditampilkan kepada pengguna.
    • Hapus semua data yang dibaca aplikasi dari Health Connect selama 30 hari terakhir.
    • Izinkan entri duplikat.

Token Changes jenis data

Jika aplikasi Anda menggunakan lebih dari satu jenis data secara terpisah, gunakan Token Changes yang berbeda untuk setiap jenis data. Hanya gunakan daftar beberapa jenis data dengan Changes Sync API jika jenis data ini dipakai bersama atau tidak sama sekali.

Pembacaan latar depan

Aplikasi hanya dapat membaca data dari Health Connect saat berada di latar depan. Saat menyinkronkan data dari Health Connect, akses ke Health Connect dapat terganggu. Misalnya, aplikasi Anda harus menangani gangguan di tengah sinkronisasi saat membaca data dalam jumlah besar dari Health Connect, dan melanjutkan saat berikutnya aplikasi dibuka.

Pembacaan latar belakang

Anda dapat meminta agar aplikasi Anda berjalan di latar belakang dan membaca data dari Health Connect. Jika Anda meminta izin Background Read, pengguna Anda dapat memberikan akses kepada aplikasi Anda untuk membaca data di latar belakang.

Penentuan waktu impor

Saat aplikasi Anda tidak dapat menerima notifikasi data baru, periksa data baru di dua titik:

  • Setiap kali aplikasi Anda menjadi aktif di latar depan. Dalam hal ini, gunakan peristiwa siklus proses.
  • Secara berkala, saat aplikasi Anda tetap berada di latar depan. Beri tahu pengguna saat data baru tersedia, sehingga pengguna dapat memperbarui layar untuk menampilkan perubahan.