คู่มือนี้ใช้ได้กับ Health Connect เวอร์ชัน 1.1.0-alpha12 ขึ้นไป
เส้นทางการออกกำลังกายช่วยให้ผู้ใช้ติดตามเส้นทาง GPS สำหรับกิจกรรมการออกกำลังกายที่เกี่ยวข้องและแชร์แผนที่การออกกำลังกายกับแอปอื่นๆ ได้
ตรวจสอบความพร้อมใช้งานของ Health Connect
ก่อนพยายามใช้ Health Connect แอปของคุณควรยืนยันว่า Health Connect พร้อมใช้งานในอุปกรณ์ของผู้ใช้ Health Connect อาจไม่ได้ติดตั้งไว้ล่วงหน้าในอุปกรณ์บางเครื่องหรืออาจปิดใช้อยู่
คุณตรวจสอบความพร้อมให้บริการได้โดยใช้เมธอด HealthConnectClient.getSdkStatus()
วิธีตรวจสอบความพร้อมใช้งานของ Health Connect
fun checkHealthConnectAvailability(context: Context) { val providerPackageName = "com.google.android.apps.healthdata" val availabilityStatus = HealthConnectClient.getSdkStatus(context, providerPackageName) if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) { // Health Connect is not available. Guide the user to install/enable it. // For example, show a dialog. return // early return as there is no viable integration } if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE_PROVIDER_UPDATE_REQUIRED) { // Health Connect is available but requires an update. // 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 } // Health Connect is available, obtain a HealthConnectClient instance val healthConnectClient = HealthConnectClient.getOrCreate(context) // Issue operations with healthConnectClient }
คุณสามารถแนะนำให้ผู้ใช้ติดตั้งหรืออัปเดต Health Connect จาก Google Play Store ได้หากจำเป็น ทั้งนี้ขึ้นอยู่กับสถานะที่ getSdkStatus() แสดงผล
คู่มือนี้จะให้ข้อมูลเกี่ยวกับวิธีขอสิทธิ์จากผู้ใช้ และยังอธิบายวิธีที่แอปได้รับสิทธิ์ในการเขียนข้อมูลเส้นทางซึ่งเป็นส่วนหนึ่งของเซสชันการออกกำลังกายด้วย
ฟังก์ชันการอ่านและเขียนสำหรับเส้นทางการออกกำลังกายมีดังนี้
- แอปสร้างสิทธิ์เขียนใหม่สำหรับเส้นทางการออกกำลังกาย
- การแทรกจะเกิดขึ้นโดยการเขียนเซสชันการออกกำลังกายที่มีเส้นทางเป็นช่อง
- การอ่าน:
- สำหรับเจ้าของเซสชัน ระบบจะเข้าถึงข้อมูลโดยใช้การอ่านเซสชัน
- จากแอปของบุคคลที่สาม ผ่านกล่องโต้ตอบที่อนุญาตให้ผู้ใช้ให้สิทธิ์อ่านเส้นทางแบบครั้งเดียว
หากผู้ใช้ไม่มีสิทธิ์เขียนและไม่ได้ตั้งค่าเส้นทาง เส้นทางจะไม่อัปเดต
หากแอปมีสิทธิ์เขียนเส้นทางและพยายามอัปเดตเซสชันโดยส่งออบเจ็กต์เซสชันที่ไม่มีเส้นทาง ระบบจะลบเส้นทางที่มีอยู่
ความพร้อมใช้งานของฟีเจอร์
หากต้องการตรวจสอบว่าอุปกรณ์ของผู้ใช้รองรับการออกกำลังกายที่วางแผนไว้ใน Health Connect หรือไม่ ให้ตรวจสอบความพร้อมใช้งานของFEATURE_PLANNED_EXERCISE ในไคลเอ็นต์โดยทำดังนี้
if (healthConnectClient
.features
.getFeatureStatus(
HealthConnectFeatures.FEATURE_PLANNED_EXERCISE
) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE) {
// Feature is available
} else {
// Feature isn't available
}
สิทธิ์ที่จำเป็น
การเข้าถึงเส้นทางการออกกำลังกายได้รับการปกป้องด้วยสิทธิ์ต่อไปนี้
android.permission.health.READ_EXERCISE_ROUTESandroid.permission.health.WRITE_EXERCISE_ROUTE
READ_EXERCISE_ROUTES เป็นพหูพจน์ ส่วน
WRITE_EXERCISE_ROUTE เป็นเอกพจน์
หากต้องการเพิ่มความสามารถของเส้นทางการออกกำลังกายลงในแอป ให้เริ่มด้วยการขอสิทธิ์สำหรับประเภทข้อมูล ExerciseSession
สิทธิ์ที่คุณต้องประกาศเพื่อให้สามารถเขียนเส้นทางการออกกำลังกายมีดังนี้
<application>
<uses-permission
android:name="android.permission.health.WRITE_EXERCISE_ROUTE" />
...
</application>
หากต้องการอ่านเส้นทางการออกกำลังกาย คุณต้องขอสิทธิ์ต่อไปนี้
<application>
<uses-permission
android:name="android.permission.health.READ_EXERCISE_ROUTES" />
...
</application>
นอกจากนี้ คุณยังต้องประกาศสิทธิ์การออกกำลังกายด้วย เนื่องจากแต่ละเส้นทางจะเชื่อมโยงกับเซสชันการออกกำลังกาย (1 เซสชัน = การออกกำลังกาย 1 ครั้ง)
หากต้องการขอสิทธิ์ ให้ใช้เมธอด PermissionController.createRequestPermissionResultContract() เมื่อเชื่อมต่อแอปกับ Health Connect เป็นครั้งแรก สิทธิ์หลายรายการที่คุณอาจต้องการขอมีดังนี้
- อ่านข้อมูลสุขภาพและการออกกำลังกาย รวมถึงข้อมูลเส้นทาง
HealthPermission.getReadPermission(ExerciseSessionRecord::class) - เขียนข้อมูลสุขภาพและการออกกำลังกาย รวมถึงข้อมูลเส้นทาง
HealthPermission.getWritePermission(ExerciseSessionRecord::class) - เขียนข้อมูลเส้นทางการออกกำลังกาย:
HealthPermission.PERMISSION_WRITE_EXERCISE_ROUTE
ขอสิทธิ์จากผู้ใช้
หลังจากสร้างอินสแตนซ์ไคลเอ็นต์แล้ว แอปของคุณจะต้องขอสิทธิ์จากผู้ใช้ ผู้ใช้ต้องได้รับอนุญาตให้ให้สิทธิ์หรือปฏิเสธสิทธิ์ได้ทุกเมื่อ โดยสร้างชุดสิทธิ์สำหรับประเภทข้อมูลที่จำเป็น ตรวจสอบว่าได้ประกาศสิทธิ์ในชุดสิทธิ์ในไฟล์ Manifest ของ Android ก่อน
val permissions = setOf( HealthPermission.getReadPermission(ExerciseSessionRecord::class), HealthPermission.getWritePermission(ExerciseSessionRecord::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.") } } }
ข้อมูลที่รวมอยู่ในบันทึกเซสชันการออกกำลังกาย
บันทึกเซสชันการออกกำลังกายแต่ละรายการจะมีข้อมูลต่อไปนี้
- ประเภทการออกกำลังกาย เช่น การปั่นจักรยาน
- เส้นทางออกกำลังกาย ซึ่งมีข้อมูลต่างๆ เช่น ละติจูด ลองจิจูด และระดับความสูง
การรวมที่รองรับ
ค่ารวมต่อไปนี้ใช้ได้กับ ExerciseSessionRecord
ตัวอย่างการใช้
ข้อมูลโค้ดต่อไปนี้แสดงวิธีอ่านและเขียนเส้นทางการออกกำลังกาย
อ่านเส้นทางออกกำลังกาย
แอปของคุณจะอ่านข้อมูลเส้นทางการออกกำลังกายที่สร้างโดยแอปอื่นๆ ไม่ได้เมื่อทำงานอยู่เบื้องหลัง
เมื่อแอปทำงานอยู่เบื้องหลังและพยายามอ่านเส้นทางการออกกำลังกายที่สร้างโดยแอปอื่น Health Connect จะแสดงผลลัพธ์เป็น ExerciseRouteResult.ConsentRequired แม้ว่าแอปจะมีสิทธิ์เข้าถึงข้อมูลเส้นทางการออกกำลังกายแบบอนุญาตเสมอก็ตาม
ด้วยเหตุนี้ เราขอแนะนำอย่างยิ่งให้คุณขอเส้นทางเมื่อผู้ใช้โต้ตอบกับแอปโดยเจตนา เมื่อผู้ใช้มีส่วนร่วมกับ UI ของแอปอย่างต่อเนื่อง
ดูข้อมูลเพิ่มเติมเกี่ยวกับการอ่านในเบื้องหลังได้ที่ตัวอย่างการอ่านในเบื้องหลัง
ข้อมูลโค้ดต่อไปนี้แสดงวิธีอ่านเซสชันใน Health Connect และขอเส้นทางจากเซสชันนั้น
private suspend fun readExerciseSessionAndRoute() { val client = healthConnectClient ?: return val endTime = Instant.now() val startTime = endTime.minus(Duration.ofHours(1)) val grantedPermissions = client.permissionController.getGrantedPermissions() // 1. Verify basic Exercise Session permissions if (!grantedPermissions.contains( HealthPermission.getReadPermission(ExerciseSessionRecord::class) ) ) { return } // 2. Read the sessions val readResponse = client.readRecords( ReadRecordsRequest( ExerciseSessionRecord::class, TimeRangeFilter.between(startTime, endTime) ) ) val exerciseRecord = readResponse.records.firstOrNull() ?: return val recordId = exerciseRecord.metadata.id // 3. Read the specific record to check for the route val sessionResponse = client.readRecord(ExerciseSessionRecord::class, recordId) // 4. Handle the Route Result directly from the response when (val routeResult = sessionResponse.record.exerciseRouteResult) { is ExerciseRouteResult.Data -> { displayExerciseRoute(routeResult.exerciseRoute) } is ExerciseRouteResult.ConsentRequired -> { // Since you are in a Service, you cannot launch ActivityResultLauncher. // Send a notification to the user to grant route-specific consent. handleConsentRequired(recordId) } is ExerciseRouteResult.NoData -> Unit else -> Unit } } private fun displayExerciseRoute(route: ExerciseRoute) { val locations = route.route.orEmpty() for (location in locations) { println(location) } }
เขียนเส้นทางการออกกำลังกาย
โค้ดต่อไปนี้แสดงวิธีบันทึกเซสชันที่มีเส้นทางการออกกำลังกาย
private suspend fun insertExerciseRoute() { val client = healthConnectClient ?: return val grantedPermissions = client.permissionController.getGrantedPermissions() // 1. Verify Session Write Permission val hasWriteSession = grantedPermissions.contains( HealthPermission.getWritePermission(ExerciseSessionRecord::class) ) if (!hasWriteSession) return val sessionStartTime = Instant.now() val sessionDuration = Duration.ofMinutes(20) val sessionEndTime = sessionStartTime.plus(sessionDuration) // 2. Build the route if route-specific write permission is granted val hasWriteRoute = grantedPermissions.contains(HealthPermission.PERMISSION_WRITE_EXERCISE_ROUTE) val exerciseRoute = if (hasWriteRoute) { ExerciseRoute( listOf( ExerciseRoute.Location( time = sessionStartTime, latitude = 6.5483, longitude = 0.5488, horizontalAccuracy = Length.meters(2.0), verticalAccuracy = Length.meters(2.0), altitude = Length.meters(9.0), ), ExerciseRoute.Location( time = sessionEndTime.minusSeconds(1), latitude = 6.4578, longitude = 0.6577, horizontalAccuracy = Length.meters(2.0), verticalAccuracy = Length.meters(2.0), altitude = Length.meters(9.2), ) ) ) } else { null } // 3. Create the session record val exerciseSessionRecord = ExerciseSessionRecord( startTime = sessionStartTime, startZoneOffset = ZoneOffset.UTC, endTime = sessionEndTime, endZoneOffset = ZoneOffset.UTC, exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_BIKING, title = "Morning Bike Ride", exerciseRoute = exerciseRoute, metadata = Metadata.activelyRecorded( device = Device(type = Device.TYPE_PHONE) ) ) // 4. Insert into Health Connect client.insertRecords(listOf(exerciseSessionRecord)) }
เซสชันการออกกำลังกาย
เซสชันการออกกำลังกายอาจรวมถึงกิจกรรมต่างๆ ตั้งแต่การวิ่งไปจนถึงแบดมินตัน
เขียนข้อมูลเซสชันการออกกำลังกาย
วิธีสร้างคำขอแทรกที่มีเซสชันมีดังนี้
suspend fun writeExerciseSession(healthConnectClient: HealthConnectClient) {
healthConnectClient.insertRecords(
listOf(
ExerciseSessionRecord(
startTime = START_TIME,
startZoneOffset = START_ZONE_OFFSET,
endTime = END_TIME,
endZoneOffset = END_ZONE_OFFSET,
exerciseType = ExerciseSessionRecord.ExerciseType.RUNNING,
title = "My Run",
metadata = Metadata.manualEntry()
),
// ... other records
)
)
}
อ่านเซสชันการออกกำลังกาย
ต่อไปนี้เป็นตัวอย่างวิธีอ่านเซสชันการออกกำลังกาย
suspend fun readExerciseSessions(
healthConnectClient: HealthConnectClient,
startTime: Instant,
endTime: Instant
) {
val response =
healthConnectClient.readRecords(
ReadRecordsRequest(
ExerciseSessionRecord::class,
timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
)
)
for (exerciseRecord in response.records) {
// Process each exercise record
// Optionally pull in with other data sources of the same time range.
val distanceRecord =
healthConnectClient
.readRecords(
ReadRecordsRequest(
DistanceRecord::class,
timeRangeFilter =
TimeRangeFilter.between(
exerciseRecord.startTime,
exerciseRecord.endTime
)
)
)
.records
}
}
เขียนข้อมูลประเภทย่อย
นอกจากนี้ เซสชันยังอาจประกอบด้วยข้อมูลประเภทย่อยที่ไม่บังคับ ซึ่งจะช่วยเพิ่มข้อมูลเพิ่มเติมให้กับเซสชัน
ตัวอย่างเช่น เซสชันการออกกำลังกายอาจรวมคลาส ExerciseSegment, ExerciseLap และ ExerciseRoute ดังนี้
val segments = listOf(
ExerciseSegment(
startTime = Instant.parse("2022-01-02T10:10:10Z"),
endTime = Instant.parse("2022-01-02T10:10:13Z"),
segmentType = ActivitySegmentType.BENCH_PRESS,
repetitions = 373
)
)
val laps = listOf(
ExerciseLap(
startTime = Instant.parse("2022-01-02T10:10:10Z"),
endTime = Instant.parse("2022-01-02T10:10:13Z"),
length = 0.meters
)
)
ExerciseSessionRecord(
exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_CALISTHENICS,
startTime = Instant.parse("2022-01-02T10:10:10Z"),
endTime = Instant.parse("2022-01-02T10:10:13Z"),
startZoneOffset = ZoneOffset.UTC,
endZoneOffset = ZoneOffset.UTC,
segments = segments,
laps = laps,
route = route,
metadata = Metadata.manualEntry()
)
ลบเซสชันการออกกำลังกาย
การลบเซสชันการออกกำลังกายทำได้ 2 วิธีดังนี้
- ตามช่วงเวลา
- ตาม UID
วิธีลบข้อมูลประเภทย่อยตามช่วงเวลา
suspend fun deleteExerciseSessionByTimeRange( healthConnectClient: HealthConnectClient, exerciseRecord: ExerciseSessionRecord, ) { val timeRangeFilter = TimeRangeFilter.between(exerciseRecord.startTime, exerciseRecord.endTime) healthConnectClient.deleteRecords(ExerciseSessionRecord::class, timeRangeFilter) // delete the associated distance record healthConnectClient.deleteRecords(DistanceRecord::class, timeRangeFilter) }
นอกจากนี้ คุณยังลบข้อมูลประเภทย่อยตาม UID ได้ด้วย การดำเนินการนี้จะลบเฉพาะเซสชันการออกกำลังกายเท่านั้น โดยจะไม่ลบข้อมูลที่เกี่ยวข้อง ดังนี้
suspend fun deleteExerciseSessionByUid( healthConnectClient: HealthConnectClient, exerciseRecord: ExerciseSessionRecord, ) { healthConnectClient.deleteRecords( ExerciseSessionRecord::class, recordIdsList = listOf(exerciseRecord.metadata.id), clientRecordIdsList = emptyList() ) }