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

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

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

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

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

สิทธิ์เข้าถึง 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 ลงในแอป

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

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

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

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

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

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

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

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

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

if (healthConnectClient
     .features
     .getFeatureStatus(
       HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_IN_BACKGROUND
     ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE) {

  // Feature is available
  ...
} else {
  // Feature is not available
  ...
}

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

การเข้าถึงข้อมูลสุขภาพและการออกกำลังกายเป็นเรื่องละเอียดอ่อน 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, 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: ขอสิทธิ์จากผู้ใช้

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

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

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

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

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

แอปจำนวนมากมีขั้นตอนการเริ่มต้นใช้งานที่กำหนดเอง เช่น การให้ความรู้เกี่ยวกับฟีเจอร์หรือการขอความยินยอมจากผู้ใช้ หากต้องการให้ 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

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) {
    val endTime = Instant.now()
    val startTime = endTime.minus(Duration.ofMinutes(15))
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = startTime,
            endTime = endTime,
            startZoneOffset = ZoneOffset.UTC,
            endZoneOffset = ZoneOffset.UTC,
            metadata = Metadata.autoRecorded(
                device = Device(type = Device.TYPE_WATCH)
            ),
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling here
    }
}

อ่านข้อมูล

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

suspend fun readHeartRateByTimeRange(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.readRecords(
            ReadRecordsRequest(
                HeartRateRecord::class,
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
        for (record in response.records) {
            // Process each 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 เช่น