Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

新增運動路線

本指南適用於 1.1.0-alpha12 版的健康資料同步。

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

確認「健康資料同步」適用情形

嘗試使用健康資料同步前，應用程式應先確認使用者的裝置是否支援健康資料同步。部分裝置可能未預先安裝或已停用「健康資料同步」。您可以使用 HealthConnectClient.getSdkStatus() 方法檢查是否可以使用這項功能。

如何查看「健康資料同步」是否適用

fun checkHealthConnectAvailability(context: Context) {
    val providerPackageName = "com.google.android.apps.healthdata" // Or get from HealthConnectClient.DEFAULT_PROVIDER_PACKAGE_NAME
    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
}

根據 getSdkStatus() 傳回的狀態，您可以視需要引導使用者從 Google Play 商店安裝或更新「健康資料同步」應用程式。

本指南提供相關資訊，說明如何向使用者要求權限，並概略說明應用程式如何取得在運動時段中寫入路線資料的權限。

運動路線的讀取與寫入功能包括：

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

如果使用者沒有寫入權限，且未設定路線，路線就不會更新。

如果應用程式具備路線寫入權限，並嘗試傳遞不含路線的時段物件來更新時段，則現有路線會遭到刪除。

功能適用情況

如要判斷使用者的裝置是否支援「健康資料同步」的預定運動功能，請檢查用戶端是否提供 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_ROUTES
android.permission.health.WRITE_EXERCISE_ROUTE

附註：這個權限類型是複數，而 WRITE_EXERCISE_ROUTE 是單數。 READ_EXERCISE_ROUTES

如要為應用程式新增運動路線功能，請先要求 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>

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

如要要求權限，請在首次將應用程式連線至「健康資料同步」時使用 PermissionController.createRequestPermissionResultContract() 方法。您可能需要要求以下幾個權限：

讀取健康與健身資料，包括路線資料： HealthPermission.getReadPermission(ExerciseSessionRecord::class)
寫入健康與健身資料，包括路線資料： HealthPermission.getWritePermission(ExerciseSessionRecord::class)
寫入運動路線資料：HealthPermission.PERMISSION_WRITE_EXERCISE_ROUTE

要求使用者授予權限

建立用戶端執行個體後，應用程式必須要求使用者授予權限。使用者必須能隨時授予或拒絕權限。

如要這麼做，請為所需資料類型建立一組權限。請務必先在 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)
  }
}

由於使用者可以隨時授予或撤銷權限，應用程式每次使用權限前都必須先檢查，並處理權限遭撤銷的情況。

運動記錄中包含的資訊

每筆運動記錄都包含下列資訊：

運動類型，例如騎單車。
運動路線，包含緯度、經度和海拔高度等資訊。

支援的匯總

下列匯總值適用於 ExerciseSessionRecord：

EXERCISE_DURATION_TOTAL

使用範例

下列程式碼片段說明如何讀取及寫入運動路線。

讀取運動路線

應用程式在背景執行時，無法讀取其他應用程式建立的運動路線資料。

如果應用程式在背景執行，並嘗試讀取其他應用程式建立的運動路線，即使應用程式已一律允許存取運動路線資料，健康資料同步仍會傳回 ExerciseRouteResult.ConsentRequired 回應。

因此，強烈建議您在使用者與應用程式互動時，主動要求路線，也就是使用者積極參與應用程式 UI 時。

如要進一步瞭解背景讀取作業，請參閱「背景讀取範例」。

下列程式碼片段示範如何在「健康資料同步」中讀取時段，並要求該時段中的路線資料：

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)
    }
}MyWearableService.kt

寫入運動路線

以下程式碼示範如何記錄內含運動路線的時段：

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(
            device = Device(type = Device.TYPE_PHONE)
        )
    )

    // 4. Insert into Health Connect
    client.insertRecords(listOf(exerciseSessionRecord))
}MyWearableService.kt

運動課程

運動時段可包含跑步、打羽毛球等任何活動。

寫入運動時段

以下方法可建立包含時段的插入要求：

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

刪除運動時段

有兩種方法可以刪除運動時段：

依據時間範圍。
依據 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)
}HealthConnectManager.kt

您也可以依據 UID 刪除子類型資料，但這麼做只會刪除運動時段，不會刪除關聯資料：

suspend fun deleteExerciseSessionByUid(
    healthConnectClient: HealthConnectClient,
    exerciseRecord: ExerciseSessionRecord,
) {
    healthConnectClient.deleteRecords(
        ExerciseSessionRecord::class,
        recordIdsList = listOf(exerciseRecord.metadata.id),
        clientRecordIdsList = emptyList()
    )
}HealthConnectManager.kt