Trainingsrouten hinzufügen

Trainingsrouten ermöglichen es Benutzern, eine GPS-Route für ein verknüpftes Training zu verfolgen. und Trainingskarten mit anderen Apps teilen.

In diesem Leitfaden wird beschrieben, wie Apps die Berechtigung erhalten, Routendaten im Rahmen eines eine Trainingseinheit.

Hier ist eine kurze Zusammenfassung der Lese- und Schreibfunktion für Trainingsrouten:

  1. Apps erstellen eine neue Schreibberechtigung für Trainingsrouten.
  2. Das Einfügen erfolgt durch Schreiben einer Übungssitzung mit einer Route als Feld.
  3. Lesematerialien: <ph type="x-smartling-placeholder">
      </ph>
    1. Für den Sitzungsinhaber wird über einen Sitzungslesevorgang auf die Daten zugegriffen.
    2. In einer Drittanbieter-App über ein Dialogfeld, in dem der Nutzer einer Route einmalig gelesen werden.

Berechtigungen

Trainingsrouten haben ihre eigene Laufzeitschreibberechtigung (android.permission.health.WRITE_EXERCISE_ROUTE)

Um Ihrer App eine Funktion für Trainingsrouten hinzuzufügen, fordern Sie zuerst Folgendes an: Berechtigungen für einen bestimmten Datentyp.

Android 14-Berechtigungsanfrage

Android 14-Berechtigungsanfrage

Android 13-Berechtigungsanfrage

Android 13-Berechtigungsanfrage

Außerdem musst du eine Übungsberechtigung erklären, da jede Route mit einer Trainingseinheit (eine Sitzung = ein Training).

Diese Berechtigung musst du deklarieren, um Trainingsrouten schreiben zu können:

<application>
  <uses-permission
android:name="android.permission.health.WRITE_EXERCISE_ROUTE" />
  <uses-permission
android:name="android.permission.health.WRITE_EXERCISE" />
...
</application>

Um Trainingsrouten zu lesen, musst du die folgenden Berechtigungen anfordern:

<application>
  <uses-permission
android:name="android.permission.health.READ_EXERCISE_ROUTES" />
  <uses-permission
android:name="android.permission.health.READ_EXERCISE" />
...
</application>

Verwenden Sie zum Anfordern von Berechtigungen den PermissionController.createRequestPermissionResultContract()-Methode, wenn Sie verbinde deine App zuerst mit Health Connect. Verschiedene Berechtigungen, die Sie die Sie anfordern möchten:

  • Zustandsdaten lesen, einschließlich Routendaten: HealthPermission.getReadPermission(ExerciseSessionRecord::class)
  • Zustandsdaten schreiben, einschließlich Routendaten: HealthPermission.getWritePermission(ExerciseSessionRecord::class)
  • Trainingsroutendaten schreiben: HealthPermission.PERMISSION_WRITE_EXERCISE_ROUTE

Routendaten lesen und schreiben

Apps fügen eine Route ein, indem sie eine Sitzung mit einer Route als Feld schreiben.

Wenn der Nutzer keine Schreibberechtigungen hat und keine Route festgelegt ist, nicht aktualisiert wird.

Wenn Ihre App eine Schreibberechtigung für Routen hat und versucht, eine Sitzung durch wird die vorhandene Route gelöscht, wenn ein Sitzungsobjekt ohne Route übergeben wird.

Wenn Ihre App von einer Drittanbieter-App bereitgestellte Routendaten lesen muss, wird der Nutzer aufgefordert, den Lesevorgang zu erlauben.

Route aus einer Sitzung anfordern

So kannst du eine Sitzung in Health Connect lesen und daraus eine Route anfordern Sitzung:

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

Route aus einer Sitzung schreiben

Der folgende Code zeigt, wie eine Sitzung aufgezeichnet wird, die ein Trainingsroute:

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