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

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

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

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

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

Android 14

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

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

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

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

เปิดแอป Health Connect

Health Connect ไม่แสดงในหน้าจอหลักอีกต่อไปโดยค่าเริ่มต้น เพื่อเปิด Health เชื่อมต่อ ให้ไปที่การตั้งค่า > แอป > Health Connect หรือเพิ่ม Health Connect ลงใน เมนูการตั้งค่าด่วน

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

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

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

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

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

ดูเวอร์ชันล่าสุดได้จากรุ่นต่างๆ ของ Health Connect

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

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

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

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

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

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

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

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

หลังจากสร้างอินสแตนซ์ไคลเอ็นต์แล้ว แอปของคุณต้องขอสิทธิ์จาก ผู้ใช้ ผู้ใช้ต้องได้รับอนุญาตให้อนุญาตหรือปฏิเสธการให้สิทธิ์ได้ทุกเมื่อ

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

// 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)
)

ใช้ getGrantedPermissions เพื่อดูว่าแอปมี ได้รับสิทธิ์ที่จำเป็นแล้ว หากไม่ ให้ใช้ createRequestPermissionResultContract เพื่อส่งคำขอ สิทธิ์เหล่านั้น ซึ่งจะแสดงหน้าจอสิทธิ์ของ 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)
  }
}

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

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

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

เขียนข้อมูล

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

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

จากนั้นเขียนระเบียนโดยใช้ 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
    }
}

อ่านข้อมูล

คุณอ่านข้อมูลทีละรายการได้โดยใช้ 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.
    }
}

นอกจากนี้ คุณยังสามารถอ่านข้อมูลในแบบรวมได้โดยใช้ 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
    }
}

วิดีโอแนะนำ

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

แหล่งข้อมูล

ดูแหล่งข้อมูลต่อไปนี้ที่จะช่วยคุณได้ ในอนาคต

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

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

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