エクササイズのルートを追加する

エクササイズのルートを使用すると、関連するエクササイズ アクティビティの GPS ルートを追跡し、ワークアウトのマップを他のアプリと共有できます。

このガイドでは、エクササイズ セッションの一部としてルートデータを書き込む権限をアプリがどのように取得するかを説明します。

エクササイズのルートの読み取り / 書き込み機能の概要は次のとおりです。

  1. アプリは、エクササイズのルート用の新しい書き込み権限を作成します。
  2. 挿入は、ルートをフィールドとしてエクササイズのセッションを書き込むことで行われます。
  3. 読み取り:
    1. セッション オーナーの場合、セッション読み取りを使用してデータにアクセスします。
    2. サードパーティ アプリで、ユーザーがルートの 1 回限りの読み取りを許可できるダイアログを表示します。

権限

エクササイズのルートには、独自のランタイム書き込み権限（android.permission.health.WRITE_EXERCISE_ROUTE）があります。

エクササイズのルート機能をアプリに追加するには、まず、特定のデータ型に対する書き込み権限をリクエストします。

Android 14 の権限のリクエスト

Android 14 の権限のリクエスト

Android 13 の権限のリクエスト

Android 13 の権限のリクエスト

また、各ルートはエクササイズ セッションに関連付けられているため、エクササイズ権限を宣言する必要があります（1 セッション = 1 ワークアウト）。

エクササイズのルートを記述するために宣言する必要がある権限は次のとおりです。

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

権限をリクエストするには、最初にアプリをヘルスコネクトに接続するときに PermissionController.createRequestPermissionResultContract() メソッドを使用します。必要に応じてリクエストする権限は次のとおりです。

  • 健康に関するデータ（ルートデータを含む）の読み取り: HealthPermission.getReadPermission(ExerciseSessionRecord::class)
  • 健康に関するデータ（ルートデータを含む）の書き込み: HealthPermission.getWritePermission(ExerciseSessionRecord::class)
  • エクササイズのルートデータの書き込み: HealthPermission.PERMISSION_WRITE_EXERCISE_ROUTE

ルートデータの読み取りと書き込み

アプリは、ルートをフィールドとして持つセッションを書き込むことで、ルートを挿入します。

ユーザーに書き込み権限がなく、ルートが設定されていない場合、ルートは更新されません。

アプリにルート書き込み権限があり、ルートのないセッション オブジェクトを渡してセッションを更新しようとすると、既存のルートが削除されます。

アプリがサードパーティ アプリから提供されたルートデータを読み取る必要があるたびに、読み取りオペレーションを許可するようにユーザーに求めるダイアログが表示されます。

セッションからルートをリクエストする

ヘルスコネクトでセッションを読み取り、そのセッションからルートをリクエストする方法は次のとおりです。

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