เริ่มต้นใช้งาน 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 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 ให้ไปที่การตั้งค่า > แอป > Health Connect หรือเพิ่ม Health Connect ลงในเมนูการตั้งค่าด่วน

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

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

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

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

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

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

หมายเหตุ: Health Connect SDK รองรับ Android 8 (API ระดับ 26) ขึ้นไป ส่วนแอป Health Connect ใช้ได้กับ Android 9 (API ระดับ 28) ขึ้นไปเท่านั้น ซึ่งหมายความว่าแอปของบุคคลที่สามจะรองรับผู้ใช้ที่ใช้ Android 8 ได้ แต่มีเพียงผู้ใช้ที่ใช้ Android 9 ขึ้นไปเท่านั้นที่จะใช้ Health Connect ได้

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

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

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

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

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

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

วิดีโอแนะนำ

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

• การจัดการสิทธิ์ใน Health Connect
• การอ่านและการเขียนใน Health Connect
• เคล็ดลับในการผสานรวม Health Connect ที่ยอดเยี่ยม

แหล่งข้อมูล

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

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

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

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

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

• เขียนข้อมูล
• อ่านข้อมูลดิบ
• อ่านข้อมูลที่รวบรวม