คู่มือนี้ใช้ได้กับ 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
- การอ่านและการเขียนใน Health Connect
- เคล็ดลับสำหรับการผสานรวม 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 เช่น