運動路線可讓使用者追蹤相關運動活動的 GPS 路線，並將健身地圖提供給其他應用程式。
本指南將說明如何向使用者要求權限，並概略說明應用程式如何取得在運動時段中寫入路線資料的權限。
以下簡要說明運動路線的讀取與寫入功能：
- 應用程式會為運動路線建立新的寫入權限。
- 插入方式為使用路線做為欄位，寫入運動時段。
- 讀取：
- 如果是時段擁有者，系統會使用時段讀取功能存取資料。
- 如果是第三方應用程式，系統會透過對話方塊讓使用者授予一次性路線讀取權限。
要求使用者授權
建立用戶端執行個體後，應用程式必須要求使用者授予權限。使用者必須能隨時授予或拒絕權限。
如要這麼做，請為所需資料類型建立一組權限。請務必先在 Android 資訊清單中聲明該組權限。
// Create a set of permissions for required data types
val PERMISSIONS =
setOf(
HealthPermission.getReadPermission(ExerciseSessionRecord::class),
HealthPermission.getWritePermission(ExerciseSessionRecord::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)
}
}
由於使用者可隨時授予或撤銷權限，因此您的應用程式需要定期檢查已授予的權限，並處理權限遺失的情況。
運動路線寫入和讀取權限
運動路線具備專屬的執行階段寫入權限 (android.permission.health.WRITE_EXERCISE_ROUTE)。
如要為應用程式新增運動路線功能，請先要求特定資料類型的寫入權限。
您也必須宣告運動權限，因為每個路線都與一個運動時段相關聯 (一個時段 = 一項健身活動)。
您需要宣告以下權限，才能寫入運動路線：
<application>
<uses-permission
android:name="android.permission.health.WRITE_EXERCISE_ROUTE" />
<uses-permission
android:name="android.permission.health.WRITE_EXERCISE" />
...
</application>
如要讀取運動路線，您必須要求下列權限：
<application>
<uses-permission
android:name="android.permission.health.READ_EXERCISE_ROUTES" />
<uses-permission
android:name="android.permission.health.READ_EXERCISE" />
...
</application>
如要要求權限，請在首次將應用程式連線至 Health Connect 時使用 PermissionController.createRequestPermissionResultContract() 方法。您可能需要要求以下幾個權限：
- 讀取健康資料，包括路線資料：
HealthPermission.getReadPermission(ExerciseSessionRecord::class) - 寫入健康資料，包括路線資料：
HealthPermission.getWritePermission(ExerciseSessionRecord::class) - 寫入運動路線資料：
HealthPermission.PERMISSION_WRITE_EXERCISE_ROUTE
讀取及寫入路線資料
應用程式插入路線時，會將路線做為欄位寫入時段。
如果使用者沒有寫入權限，且未設定路線，路線就不會更新。
如果應用程式具備路線寫入權限，並嘗試傳遞不含路線的時段物件來更新時段，則現有路線會遭到刪除。
每當應用程式需要讀取第三方應用程式提供的路線資料時，系統會顯示對話方塊，要求使用者允許執行讀取作業。
要求時段中的路線資料
以下說明如何在 Health Connect 中讀取時段，並要求該時段中的路線資料：
suspend fun readExerciseSessionAndRoute() {
val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofHours(1))
val grantedPermissions =
healthConnectClient.permissionController.getGrantedPermissions()
if (!grantedPermissions.contains(
HealthPermission.getReadPermission(ExerciseSessionRecord::class))) {
// The user doesn't allow the app to read exercise session data.
return
}
val readResponse =
healthConnectClient.readRecords(
ReadRecordsRequest(
ExerciseSessionRecord::class,
TimeRangeFilter.between(startTime, endTime)
)
)
val exerciseRecord = readResponse.records.first()
val recordId = exerciseRecord.metadata.id
// See https://developer.android.com/training/basics/intents/result#launch
// for appropriately handling ActivityResultContract.
val requestExerciseRouteLauncher = fragment.registerForActivityResul
(ExerciseRouteRequestContract()) { exerciseRoute: ExerciseRoute? ->
if (exerciseRoute != null) {
displayExerciseRoute(exerciseRoute)
} else {
// Consent was denied
}
}
val exerciseSessionRecord =
healthConnectClient.readRecord(ExerciseSessionRecord::class, recordId).record
when (val exerciseRouteResult = exerciseSessionRecord.exerciseRouteResult) {
is ExerciseRouteResult.Data ->
displayExerciseRoute(exerciseRouteResult.exerciseRoute)
is ExerciseRouteResult.ConsentRequired ->
requestExerciseRouteLauncher.launch(recordId)
is ExerciseRouteResult.NoData -> Unit // No exercise route to show
else -> Unit
}
}
fun displayExerciseRoute(route: ExerciseRoute?) {
val locations = route.route.orEmpty()
for (location in locations) {
// Handle location.
}
}
寫入時段中的路線資料
以下程式碼示範如何記錄內含運動路線的時段：
suspend fun InsertExerciseRoute(healthConnectClient: HealthConnectClient) {
val grantedPermissions =
healthConnectClient.permissionController.getGrantedPermissions()
if (!grantedPermissions.contains(
getWritePermission(ExerciseSessionRecord::class))) {
// The user doesn't allow the app to write exercise session data.
return
}
val sessionStartTime = Instant.now()
val sessionDuration = Duration.ofMinutes(20)
val sessionEndTime = sessionStartTime.plus(sessionDuration)
val exerciseRoute =
if (grantedPermissions.contains(PERMISSION_WRITE_EXERCISE_ROUTE)) ExerciseRoute(
listOf(
ExerciseRoute.Location(
// Location times must be on or after the session start time
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(
// Location times must be before the session end time
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
// The user doesn't allow the app to write exercise route data.
null
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.manualEntry(
device = Device(type = Device.TYPE_PHONE)
),
)
val response = healthConnectClient.insertRecords(listOf(exerciseSessionRecord))
}