新增運動路線

運動路線可讓使用者追蹤相關運動活動的 GPS 路線，並將健身地圖提供給其他應用程式。

本指南說明應用程式如何在運動時段中取得寫入路線資料的權限。

以下簡要說明運動路線的讀取和寫入功能：

1. 應用程式會為運動路線建立新的寫入權限。
2. 插入方式為使用路線做為欄位，寫入運動時段。
3. 讀取：
   1. 如果是時段擁有者，系統會使用時段讀取功能存取資料。
   2. 如果是第三方應用程式，系統會透過對話方塊讓使用者授予一次性路線讀取權限。

權限

運動路線具備專屬的執行階段寫入權限 (android.permission.health.WRITE_EXERCISE_ROUTE)。

如要為應用程式新增運動路線功能，請先要求特定資料類型的寫入權限。

Android 14 權限要求

Android 13 權限要求

您也必須宣告運動權限，因為每個路線都與一個運動時段相關聯 (一個時段 = 一項健身活動)。

您需要宣告以下權限，才能寫入運動路線：

<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 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()

    // 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.parse("2023-01-01T10:00:00.00Z")
    val sessionDuration = Duration.ofMinutes(20)

    val exerciseRoute =
      if (getPermissions.contains(PERMISSION_EXERCISE_ROUTE_WRITE) {
        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 = sessionStartTime.plus(sessionDuration)
              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 = /* starting time in milliseconds */,
            startZoneOffset = ZoneOffset.UTC,
            endTime = sessionStartTime.plus(sessionDuration),
            endZoneOffset = ZoneOffset.UTC,
            exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_BIKING,
            title = "Morning Bike Ride",
            exerciseRoute = exerciseRoute
        )

    healthConnectClient.insertRecords(listOf(exerciseSessionRecord))
}