เริ่มต้นใช้งาน Health Connect

คู่มือนี้ใช้ได้กับ Health Connect เวอร์ชัน 1.1.0-alpha12 ขึ้นไป

คู่มือนี้จะแสดงวิธีเริ่มใช้ Health Connect ในแอปของคุณ

ขั้นตอนที่ 1: เตรียมแอป Health Connect

แอป Health Connect มีหน้าที่จัดการคำขอทั้งหมดที่แอปพลิเคชันของคุณส่งผ่าน Health Connect SDK คำขอเหล่านี้รวมถึงการจัดเก็บข้อมูลและการจัดการสิทธิ์การอ่านและเขียนข้อมูล

การเข้าถึง Health Connect จะขึ้นอยู่กับเวอร์ชัน Android ที่ติดตั้งในโทรศัพท์ ส่วนต่อไปนี้จะอธิบายวิธีจัดการ Android เวอร์ชันล่าสุดหลายเวอร์ชัน

Android 14

ตั้งแต่ Android 14 (API ระดับ 34) เป็นต้นไป Health Connect จะเป็นส่วนหนึ่งของเฟรมเวิร์ก Android Health Connect เวอร์ชันนี้เป็นโมดูลเฟรมเวิร์ก ซึ่งคุณไม่จำเป็นต้องตั้งค่าใดๆ

Android 13 และต่ำกว่า

ใน Android 13 (ระดับ API 33) และเวอร์ชันที่ต่ำกว่า Health Connect ไม่ได้เป็นส่วนหนึ่งของเฟรมเวิร์ก Android คุณจึงต้องติดตั้งแอป Health Connect จาก Google Play Store

หากคุณผสานรวมแอปกับ Health Connect ใน Android 13 และต่ำกว่า และต้องการย้ายข้อมูลใน Android 14 โปรดดูหัวข้อย้ายข้อมูลจาก Android 13 ไปยัง 14

เปิดแอป Health Connect

Health Connect จะไม่ปรากฏในหน้าจอหลักโดยค่าเริ่มต้นอีกต่อไป คุณเปิด Health Connect ได้ผ่านการตั้งค่า โดยเส้นทางจะแตกต่างกันไปตามเวอร์ชัน Android ดังนี้

  • ใน Android 14 ขึ้นไป: ไปที่การตั้งค่า > ความปลอดภัยและความเป็นส่วนตัว > การควบคุมความเป็นส่วนตัว > Health Connect หรือค้นหา Health Connect ในการตั้งค่า
  • ใน Android 13 และต่ำกว่า: ไปที่การตั้งค่า > แอป > Health Connect หรือเพิ่ม Health Connect ลงในเมนูการตั้งค่าด่วน

ขั้นตอนที่ 2: เพิ่ม SDK ของ Health Connect ลงในแอป

SDK ของ Health Connect มีหน้าที่ใช้ Health Connect API เพื่อส่งคำขอในการดำเนินการกับ Datastore ในแอป Health Connect

เพิ่มทรัพยากร Dependency ของ SDK ของ Health Connect ในไฟล์ build.gradle ระดับโมดูล

dependencies {
  ...
  implementation "androidx.health.connect:connect-client:1.2.0-alpha06"
  ...
}

ดูเวอร์ชันล่าสุดได้ที่รุ่นของ Health Connect

connect-client เวอร์ชัน 1.1.0 ขึ้นไปต้องใช้ compileSdk = 36 และปลั๊กอิน Android Gradle (AGP) เวอร์ชัน 8.9.1 ขึ้นไป อัปเดต compileSdk ในไฟล์ build.gradle ระดับโมดูล

android {
  compileSdk = 36
}

ใช้ฟีเจอร์ของเวอร์ชันการเผยแพร่ Canary

หากต้องการใช้ฟีเจอร์ในเวอร์ชันการเผยแพร่ Canary ให้แก้ไขเวอร์ชันของ compileSdk ในไฟล์ build.gradle ระดับโมดูล ดังนี้

android {
  compileSdkPreview = "CANARY"
}

ขั้นตอนที่ 3: กำหนดค่าแอป

ส่วนต่อไปนี้จะอธิบายวิธีกำหนดค่าแอปเพื่อผสานรวมกับ Health Connect

ตรวจสอบความพร้อมใช้งานของฟีเจอร์

เมื่อมีการเพิ่มฟีเจอร์ใหม่ลงใน Health Connect ผู้ใช้อาจไม่ได้อัปเดต Health Connect เป็นเวอร์ชันล่าสุดเสมอไป Feature Availability API เป็นวิธีตรวจสอบว่าฟีเจอร์ใน Health Connect พร้อมใช้งานในอุปกรณ์ของผู้ใช้หรือไม่ และตัดสินใจว่าจะดำเนินการใด

ฟังก์ชันหลักในการตรวจสอบความพร้อมใช้งานของฟีเจอร์คือ getFeatureStatus() ซึ่งจะแสดงค่าคงที่จำนวนเต็ม FEATURE_STATUS_AVAILABLE หรือ FEATURE_STATUS_UNAVAILABLE ดังนี้

fun enqueueBackgroundReadWorker(context: Context, healthConnectClient: HealthConnectClient) {
    if (healthConnectClient
            .features
            .getFeatureStatus(
                HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_IN_BACKGROUND
            ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE
    ) {

        val periodicWorkRequest = PeriodicWorkRequestBuilder<ScheduleWorker>(1, TimeUnit.HOURS)
            .build()

        WorkManager.getInstance(context).enqueueUniquePeriodicWork(
            "read_health_connect",
            ExistingPeriodicWorkPolicy.KEEP,
            periodicWorkRequest
        )
    }
}

ประกาศสิทธิ์

การเข้าถึงข้อมูลสุขภาพและการออกกำลังกายเป็นเรื่องที่ละเอียดอ่อน Health Connect ใช้การรักษาความปลอดภัยอีกชั้นหนึ่งสำหรับการดำเนินการอ่านและเขียน เพื่อรักษาความไว้วางใจของผู้ใช้

ในแอป ให้ประกาศสิทธิ์อ่านและเขียนในไฟล์ AndroidManifest.xml โดยอิงตามประเภทข้อมูลที่จำเป็น ซึ่งควรตรงกับประเภทข้อมูลที่คุณประกาศสิทธิ์เข้าถึงใน Play Console

Health Connect ใช้รูปแบบการประกาศสิทธิ์มาตรฐานของ Android มอบหมายสิทธิ์ด้วยแท็ก <uses-permission> ฝังไว้ในแท็ก <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>

ดูรายการสิทธิ์และประเภทข้อมูลที่เกี่ยวข้องทั้งหมดได้ที่รายการประเภทข้อมูล

แสดงกล่องโต้ตอบนโยบายความเป็นส่วนตัวของแอป

ไฟล์ Manifest ของ Android ต้องมีกิจกรรมที่แสดงนโยบายความเป็นส่วนตัวของแอป ซึ่งเป็นเหตุผลของแอปสำหรับสิทธิ์ที่ขอ โดยอธิบายวิธีใช้และจัดการข้อมูลของผู้ใช้

ประกาศกิจกรรมนี้เพื่อจัดการ Intent ACTION_SHOW_PERMISSIONS_RATIONALE ซึ่งจะส่งไปยังแอปเมื่อผู้ใช้คลิกลิงก์นโยบายความเป็นส่วนตัวในหน้าจอสิทธิ์ของ 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>
...

รับไคลเอ็นต์ Health Connect

HealthConnectClient เป็นจุดแรกเข้าของ Health Connect API ซึ่งช่วยให้แอปใช้ Datastore ในแอป Health Connect ได้ โดยจะจัดการการเชื่อมต่อกับเลเยอร์พื้นที่เก็บข้อมูลที่จำเป็นโดยอัตโนมัติ และจัดการ IPC ทั้งหมด รวมถึงการจัดเรียงข้อมูลคำขอขาออกและการตอบกลับขาเข้า

หากต้องการรับอินสแตนซ์ไคลเอ็นต์ ให้ประกาศชื่อแพ็กเกจ Health Connect ในไฟล์ Manifest ของ Android ก่อน

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

จากนั้นในกิจกรรม ให้ตรวจสอบว่ามีการติดตั้ง Health Connect โดยใช้ getSdkStatus หรือไม่ หากเป็นเช่นนั้น ให้รับอินสแตนซ์ HealthConnectClient

val availabilityStatus = HealthConnectClient.getSdkStatus(context)
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
    Box(modifier = modifier.padding(16.dp), contentAlignment = Alignment.Center) {
        Text(
            text = "Health Connect is not available on this device. Please ensure it is installed and updated.",
            style = MaterialTheme.typography.bodyLarge,
            textAlign = TextAlign.Center
        )
    }
    return
}

val healthConnectClient = remember {
    if (availabilityStatus == HealthConnectClient.SDK_AVAILABLE) {
        HealthConnectClient.getOrCreate(context)
    } else {
        null
    }
}

ขั้นตอนที่ 4: ขอสิทธิ์จากผู้ใช้

หลังจากสร้างอินสแตนซ์ไคลเอ็นต์แล้ว แอปของคุณจะต้องขอสิทธิ์จากผู้ใช้ ผู้ใช้ต้องได้รับอนุญาตให้ให้สิทธิ์หรือปฏิเสธสิทธิ์ได้ทุกเมื่อ โดยสร้างชุดสิทธิ์สำหรับประเภทข้อมูลที่จำเป็น ตรวจสอบว่าได้ประกาศสิทธิ์ในชุดสิทธิ์ในไฟล์ Manifest ของ Android ก่อน

val permissions =
    setOf(
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class),
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class)
    )
ใช้ getGrantedPermissions เพื่อดูว่าแอปของคุณได้รับสิทธิ์ที่จำเป็นแล้วหรือยัง หากไม่มี ให้ใช้ createRequestPermissionResultContract เพื่อขอสิทธิ์เหล่านั้น หน้าจอแสดงสิทธิ์ของ Health Connect จะปรากฏขึ้น
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.") }
    }
}
เนื่องจากผู้ใช้สามารถให้หรือเพิกถอนสิทธิ์ได้ทุกเมื่อ แอปของคุณจึงต้องตรวจสอบสิทธิ์ทุกครั้งก่อนใช้งานและจัดการสถานการณ์ที่สิทธิ์หายไป

เริ่มต้นใช้งานผู้ใช้

แอปจำนวนมากมีขั้นตอนการเตรียมความพร้อมผู้ใช้งานใหม่ที่กำหนดเอง เช่น การให้ความรู้เกี่ยวกับฟีเจอร์หรือการขอความยินยอมของผู้ใช้ หากต้องการเปิดใช้ Health Connect เพื่อเปิดขั้นตอนการเริ่มต้นใช้งาน ให้เพิ่มสิ่งต่อไปนี้ลงในไฟล์ Manifest

<!-- Required to support pre-Android 14 devices with APK Health Connect -->
<activity
  android:name=".OnboardingActivity"
  android:exported="true"
  android:permission="com.google.android.apps.healthdata.permission.START_ONBOARDING">
  <intent-filter>
    <action android:name="androidx.health.ACTION_SHOW_ONBOARDING"/>
  </intent-filter>
</activity>
<!-- Required to support Android 14+ devices with platform Health Connect -->
<activity-alias
  android:name="UAndAboveOnboardingActivity"
  android:exported="true"
  android:targetActivity=".OnboardingActivity"
  android:permission="android.permission.health.START_ONBOARDING">
  <intent-filter>
    <action android:name="android.health.connect.action.SHOW_ONBOARDING" />
  </intent-filter>
</activity-alias>

ผู้ใช้อาจเริ่มการเชื่อมต่อกับแอปของคุณโดยตรงจากแอป Health Connect แทนที่จะเป็นจากภายในแอปของคุณ หากแอปของคุณต้องการการโต้ตอบเพิ่มเติมใดๆ นอกเหนือจากการได้รับสิทธิ์ในการอ่านหรือเขียนข้อมูล ให้ระบุกิจกรรมการเริ่มต้นใช้งาน

โปรดทราบว่ากิจกรรมการเริ่มต้นใช้งานอาจเปิดขึ้นมากกว่า 1 ครั้ง เช่น หากผู้ใช้เพิกถอนสิทธิ์ในแอปของคุณในภายหลังแล้วเชื่อมต่ออีกครั้ง

ขั้นตอนที่ 5: ดำเนินการ

เมื่อตั้งค่าทุกอย่างเรียบร้อยแล้ว ให้ดำเนินการอ่านและเขียนในแอป

ผู้ใช้อาจใช้แอปอื่นๆ ที่ซิงค์ข้อมูลกับ Health Connect เพื่อให้แอปของคุณเข้าถึงได้ หากผู้ใช้ยังไม่ได้ตั้งค่าแอปเหล่านี้ให้เขียนข้อมูลลงใน Health Connect คุณสามารถใช้ Matchmaking API เพื่อเชื่อมต่อแอปเหล่านี้ให้ผู้ใช้ได้อย่างราบรื่น

เขียนข้อมูล

จัดโครงสร้างข้อมูลเป็นระเบียน ดูรายการประเภทข้อมูลที่ใช้ได้ใน Health Connect

val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)
val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = zoneOffset,
    endZoneOffset = zoneOffset,
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))

จากนั้นเขียนระเบียนโดยใช้ insertRecords

val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)
val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = zoneOffset,
    endZoneOffset = zoneOffset,
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))

อ่านข้อมูล

คุณอ่านข้อมูลแต่ละรายการได้โดยใช้ readRecords

val response = healthConnectClient.readRecords(
    ReadRecordsRequest(
        HeartRateRecord::class,
        timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
    )
)
response.records.forEach { record ->
    /* Process records */
}

นอกจากนี้ คุณยังอ่านข้อมูลในลักษณะรวมได้โดยใช้ aggregate

suspend fun readStepsAggregate(startTime: Instant, endTime: Instant): Long {
    val response = healthConnectClient.aggregate(
        AggregateRequest(
            metrics = setOf(StepsRecord.COUNT_TOTAL),
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
        )
    )
    return response[StepsRecord.COUNT_TOTAL] ?: 0L
}

วิดีโอแนะนำ

ดูวิดีโอเหล่านี้ที่อธิบายเพิ่มเติมเกี่ยวกับฟีเจอร์ของ Health Connect รวมถึงหลักเกณฑ์แนวทางปฏิบัติแนะนำเพื่อให้การผสานรวมเป็นไปอย่างราบรื่น

แหล่งข้อมูล

ลองดูแหล่งข้อมูลต่อไปนี้ซึ่งจะช่วยในการพัฒนาในภายหลัง

  • Health Connect SDK (พร้อมใช้งานใน Jetpack): รวม SDK นี้ไว้ในแอปพลิเคชันเพื่อใช้ Health Connect API
  • เอกสารอ้างอิง API: ดูเอกสารอ้างอิง Jetpack สำหรับ Health Connect API
  • ประกาศการใช้ประเภทข้อมูล: ใน Play Console ให้ประกาศการเข้าถึงประเภทข้อมูล Health Connect ที่แอปของคุณอ่านและเขียน
  • ตัวอย่างโค้ด GitHub และ Codelab (ไม่บังคับ): ดูที่เก็บตัวอย่างโค้ด GitHub และแบบฝึกหัด Codelab เพื่อช่วยคุณเริ่มต้นใช้งาน

ขั้นตอนถัดไป

ดูเวิร์กโฟลว์ทั่วไปเพื่อดูวิธีดำเนินการต่างๆ ใน Health Connect เช่น