Mulai menggunakan Health Connect

Panduan ini menunjukkan cara mulai menggunakan Health Connect di aplikasi Anda.

Langkah 1: Menyiapkan aplikasi Health Connect

Aplikasi Health Connect bertanggung jawab menangani semua permintaan yang dikirim aplikasi Anda melalui Health Connect SDK. Permintaan ini termasuk menyimpan data dan mengelola akses baca dan tulisnya.

Akses ke Health Connect bergantung pada versi Android yang diinstal di ponsel. Bagian berikut menguraikan cara menangani beberapa versi terbaru Android.

Android 14

Mulai Android 14 (Level API 34), Health Connect adalah bagian dari Framework Android. Health Connect versi ini adalah modul framework. Dengan demikian, tidak perlu penyiapan.

Android 13 dan yang lebih lama

Di Android 13 (Level API 33) dan versi yang lebih lama, Health Connect bukan merupakan bagian dari Framework Android. Dengan demikian, Anda perlu menginstal aplikasi Health Connect dari Google Play Store.

Jika Anda telah mengintegrasikan aplikasi dengan Health Connect di Android 13 dan yang lebih lama, dan ingin bermigrasi di Android 14, lihat Bermigrasi dari Android 13 ke 14.

Membuka aplikasi Health Connect

Secara default, Health Connect tidak lagi muncul di Layar utama. Untuk membuka Health Connect, buka Setelan > Aplikasi > Health Connect atau tambahkan Health Connect ke menu Setelan Cepat.

Selain itu, Health Connect mengharuskan pengguna mengaktifkan kunci layar dengan PIN, pola, atau sandi agar data kesehatan yang disimpan di Health Connect terlindungi dari pihak berbahaya saat perangkat terkunci. Untuk menyetel kunci layar, buka Setelan > Keamanan > Kunci layar.

Langkah 2: Menambahkan Health Connect SDK ke aplikasi

Health Connect SDK bertanggung jawab untuk menggunakan Health Connect API guna mengirim permintaan dalam menjalankan operasi terhadap datastore di aplikasi Health Connect.

Tambahkan dependensi Health Connect SDK di file build.gradle level modul:

dependencies {
  ...
  implementation "androidx.health.connect:connect-client:1.1.0-alpha02"
  ...
}

Lihat rilis Health Connect untuk versi terbaru.

Catatan: Health Connect SDK mendukung Android 8 (level API 26) atau yang lebih tinggi, sedangkan aplikasi Health Connect hanya kompatibel dengan Android 9 (level API 28) atau yang lebih tinggi. Ini berarti aplikasi pihak ketiga dapat mendukung pengguna dengan Android 8, tetapi hanya pengguna dengan Android 9 atau yang lebih tinggi yang dapat menggunakan Health Connect.

Langkah 3: Mengonfigurasi aplikasi Anda

Bagian berikut menjelaskan cara mengonfigurasi aplikasi Anda untuk diintegrasikan ke Health Connect.

Mendeklarasikan izin

Akses ke data kesehatan dan kebugaran bersifat sensitif. Health Connect menerapkan lapisan keamanan untuk operasi baca dan tulis, sehingga menjaga kepercayaan pengguna.

Deklarasikan izin baca dan tulis pada file AndroidManifest.xml berdasarkan jenis data yang diperlukan. Pastikan Anda menggunakan kumpulan izin yang diminta setelah melengkapi [form]{:.external}.

Health Connect menggunakan format pernyataan izin Android standar. Tetapkan izin dengan tag <uses-permission>. Tempatkan keduanya di dalam tag <manifest>.

<manifest>
  <uses-permission android:name="android.permission.health.READ_HEART_RATE"/>
  <uses-permission android:name="android.permission.health.WRITE_HEART_RATE"/>
  <uses-permission android:name="android.permission.health.READ_STEPS"/>
  <uses-permission android:name="android.permission.health.WRITE_STEPS"/>

  <application>
  ...
  </application>
</manifest>

Untuk mengetahui daftar lengkap izin dan jenis data yang sesuai, lihat Daftar jenis data.

Menampilkan dialog kebijakan privasi aplikasi

Manifes Android Anda harus memiliki Aktivitas yang menampilkan kebijakan privasi aplikasi, yang merupakan alasan aplikasi meminta izin, yang menjelaskan cara data pengguna digunakan dan ditangani.

Deklarasikan aktivitas ini untuk menangani intent ACTION_SHOW_PERMISSIONS_RATIONALE yang dikirim ke aplikasi saat pengguna mengklik link kebijakan privasi di layar izin Health Connect.

...
<application>
  ...
  <!-- For supported versions through Android 13, create an activity to show the rationale
       of Health Connect permissions once users click the privacy policy link. -->
  <activity
      android:name=".PermissionsRationaleActivity"
      android:exported="true">
    <intent-filter>
      <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
    </intent-filter>
  </activity>

  <!-- For versions starting Android 14, create an activity alias to show the rationale
       of Health Connect permissions once users click the privacy policy link. -->
  <activity-alias
      android:name="ViewPermissionUsageActivity"
      android:exported="true"
      android:targetActivity=".PermissionsRationaleActivity"
      android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
    <intent-filter>
      <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
      <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
    </intent-filter>
  </activity-alias>
  ...
</application>
...

Mendapatkan klien Health Connect

HealthConnectClient adalah titik entri ke Health Connect API. Health Connect memungkinkan aplikasi menggunakan datastore di aplikasi Health Connect. API ini otomatis mengelola koneksinya ke lapisan penyimpanan dasar serta menangani semua IPC dan serialisasi permintaan keluar dan respons masuk.

Untuk mendapatkan instance klien, deklarasikan nama paket Health Connect dalam manifes Android Anda terlebih dahulu.

<application> ... </application>
...
<!-- Check if Health Connect is installed -->
<queries>
    <package android:name="com.google.android.apps.healthdata" />
</queries>

Kemudian, di Aktivitas Anda, periksa apakah Health Connect diinstal menggunakan getSdkStatus. Jika ya, dapatkan Instance HealthConnectClient.

val availabilityStatus = HealthConnectClient.getSdkStatus(context, providerPackageName)
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
  return // early return as there is no viable integration
}
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE_PROVIDER_UPDATE_REQUIRED) {
  // Optionally redirect to package installer to find a provider, for example:
  val uriString = "market://details?id=$providerPackageName&url=healthconnect%3A%2F%2Fonboarding"
  context.startActivity(
    Intent(Intent.ACTION_VIEW).apply {
      setPackage("com.android.vending")
      data = Uri.parse(uriString)
      putExtra("overlay", true)
      putExtra("callerId", context.packageName)
    }
  )
  return
}
val healthConnectClient = HealthConnectClient.getOrCreate(context)
// Issue operations with healthConnectClient

Langkah 4: Meminta izin dari pengguna

Setelah membuat instance klien, aplikasi Anda perlu meminta izin dari pengguna. Pengguna harus diizinkan untuk memberikan atau menolak izin setiap saat.

Untuk melakukannya, buat kumpulan izin untuk jenis data yang diperlukan. Pastikan izin dalam kumpulan dinyatakan dalam manifes Android Anda terlebih dahulu.

// Create a set of permissions for required data types
val PERMISSIONS =
setOf(
  HealthPermission.getReadPermission(HeartRateRecord::class),
  HealthPermission.getWritePermission(HeartRateRecord::class),
  HealthPermission.getReadPermission(StepsRecord::class),
  HealthPermission.getWritePermission(StepsRecord::class)
)

Gunakan getGrantedPermissions untuk mengetahui apakah aplikasi Anda sudah mendapatkan izin yang diperlukan. Jika belum, gunakan createRequestPermissionResultContract untuk meminta izin tersebut. Tindakan ini akan menampilkan layar izin Health Connect.

// Create the permissions launcher
val requestPermissionActivityContract = PermissionController.createRequestPermissionResultContract()

val requestPermissions = registerForActivityResult(requestPermissionActivityContract) { granted ->
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions successfully granted
  } else {
    // Lack of required permissions
  }
}

suspend fun checkPermissionsAndRun(healthConnectClient: HealthConnectClient) {
  val granted = healthConnectClient.permissionController.getGrantedPermissions()
  if (granted.containsAll(PERMISSIONS)) {
    // Permissions already granted; proceed with inserting or reading data
  } else {
    requestPermissions.launch(PERMISSIONS)
  }
}

Jangan berasumsi bahwa izin bersifat konstan, karena pengguna dapat memberikan atau mencabutnya kapan saja. Aplikasi Anda harus memeriksa izin yang diberikan secara berkala, dan menangani skenario saat izin tersebut hilang.

Langkah 5: Melakukan operasi

Setelah semuanya siap, lakukan operasi baca dan tulis di aplikasi Anda.

Menulis data

Susun data Anda ke dalam kumpulan data. Lihat daftar jenis data yang tersedia di Health Connect.

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

Kemudian, tulis kumpulan data Anda menggunakan insertRecords.

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

Membaca data

Anda dapat membaca data satu per satu menggunakan readRecords.

suspend fun readStepsByTimeRange(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response =
            healthConnectClient.readRecords(
                ReadRecordsRequest(
                    StepsRecord::class,
                    timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
                )
            )
        for (stepRecord in response.records) {
            // Process each step record
        }
    } catch (e: Exception) {
        // Run error handling here.
    }
}

Anda juga dapat membaca data secara agregat menggunakan aggregate.

suspend fun aggregateSteps(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.aggregate(
            AggregateRequest(
                metrics = setOf(StepsRecord.COUNT_TOTAL),
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
        // The result may be null if no data is available in the time range
        val stepCount = response[StepsRecord.COUNT_TOTAL]
    } catch (e: Exception) {
        // Run error handling here
    }
}

Penting: Health Connect dapat membaca data hingga 30 hari sebelum izin pertama kali diberikan. Namun, jika pengguna menghapus aplikasi Anda, histori izin akan hilang. Jika pengguna menginstal ulang aplikasi Anda dan memberikan izin lagi, Health Connect dapat membaca data hingga 30 hari sebelum tanggal pemberiannya.

Video tutorial

Tonton video berikut yang menjelaskan lebih lanjut fitur Health Connect, serta panduan praktik terbaik untuk mencapai integrasi yang lancar:

• Mengelola izin di Health Connect
• Membaca dan menulis di Health Connect
• Tips untuk integrasi Health Connect yang hebat

Referensi

Lihat referensi berikut yang membantu pengembangan di lain waktu.

• Health Connect SDK (tersedia di Jetpack): Sertakan SDK ini di aplikasi Anda untuk menggunakan Health Connect API.
• Referensi API: Baca tentang Health Connect API di referensi Jetpack.
• Deklarasikan penggunaan jenis data: Di Konsol Play, deklarasikan akses ke jenis data Health Connect yang dibaca dan ditulis oleh aplikasi Anda.
• Contoh kode GitHub opsional dan codelab: Lihat repositori contoh kode GitHub dan latihan codelab untuk membantu Anda memulai.

Catatan: Jika Anda mengajukan permintaan lain jika aplikasi memerlukan data baru Anda harus menyertakan jenis data baru dan yang sudah ada, serta mengecualikan tipe data yang tidak lagi diperlukan. Jika Anda hanya perlu menghapus akses ke jenis data tertentu, sertakan semua jenis data yang ada, tetapi kecualikan jenis data yang tidak diperlukan lagi.

Langkah berikutnya

Lihat Alur kerja umum untuk mempelajari cara menjalankan operasi di Health Connect seperti:

• Menulis data
• Membaca data mentah
• Membaca data gabungan