Trainingsrouten hinzufügen

Dieser Leitfaden ist mit der Health Connect-Version 1.1.0-alpha12 kompatibel.

Mit Trainingsrouten können Nutzer eine GPS-Route für zugehörige Trainingsaktivitäten aufzeichnen und Karten ihrer Trainings mit anderen Apps teilen.

Verfügbarkeit der Funktion

Prüfe, ob das Gerät eines Nutzers Trainingsrouten in Health Connect unterstützt. Dazu musst du die Verfügbarkeit von FEATURE_PLANNED_EXERCISE auf dem Client prüfen:

if (healthConnectClient
     .features
     .getFeatureStatus(
       HealthConnectFeatures.FEATURE_PLANNED_EXERCISE
     ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE) {

  // Feature is available
} else {
  // Feature isn't available
}

Weitere Informationen finden Sie unter Verfügbarkeit von Funktionen prüfen.

In diesem Leitfaden erfahren Sie, wie Sie Berechtigungen vom Nutzer anfordern und wie Apps die Berechtigung zum Schreiben von Routendaten im Rahmen einer Trainingseinheit erhalten.

Die Lese- und Schreibfunktionen für Trainingsrouten umfassen Folgendes:

  1. Apps erstellen eine neue Schreibberechtigung für Trainingsrouten.
  2. Die Einfügung erfolgt durch das Schreiben einer Trainingseinheit mit einer Route als Feld.
  3. Lesen:
    1. Für den Inhaber der Sitzung wird auf Daten über eine Sitzungsleseoperation zugegriffen.
    2. Über eine Drittanbieter-App über ein Dialogfeld, über das der Nutzer eine einmalige Lesezugriffsberechtigung für eine Route gewähren kann.

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

Wenn Ihre App eine Berechtigung zum Schreiben von Routen hat und versucht, eine Sitzung zu aktualisieren, indem sie ein Sitzungsobjekt ohne Route übergibt, wird die vorhandene Route gelöscht.

Erforderliche Berechtigungen

Der Zugriff auf Trainingsrouten wird durch die folgenden Berechtigungen geschützt:

  • android.permission.health.READ_EXERCISE_ROUTES
  • android.permission.health.WRITE_EXERCISE_ROUTE

Wenn Sie Ihrer App die Funktion „Trainingsroute“ hinzufügen möchten, müssen Sie zuerst Schreibberechtigungen für einen bestimmten Datentyp anfordern.

Sie müssen auch eine Berechtigung für Übungen deklarieren, da jeder Route eine Trainingseinheit zugeordnet ist (eine Sitzung = ein Training).

Sie müssen die folgende Berechtigung erklären, um Trainingsrouten erstellen zu können:

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

Wenn Sie Trainingsrouten lesen möchten, müssen Sie 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>

Wenn Sie Berechtigungen anfordern möchten, verwenden Sie die Methode PermissionController.createRequestPermissionResultContract(), wenn Sie Ihre App zum ersten Mal mit Health Connect verbinden. Beispiele für Berechtigungen, die Sie anfordern können:

  • Gesundheitsdaten, einschließlich Routendaten, lesen: HealthPermission.getReadPermission(ExerciseSessionRecord::class)
  • Gesundheitsdaten, einschließlich Routendaten, schreiben: HealthPermission.getWritePermission(ExerciseSessionRecord::class)
  • Daten zur Trainingsroute schreiben: HealthPermission.PERMISSION_WRITE_EXERCISE_ROUTE

Berechtigungen vom Nutzer anfordern

Nachdem Sie eine Clientinstanz erstellt haben, muss Ihre App vom Nutzer Berechtigungen anfordern. Nutzer müssen jederzeit Berechtigungen erteilen oder verweigern können.

Erstellen Sie dazu eine Reihe von Berechtigungen für die erforderlichen Datentypen. Achten Sie darauf, dass die Berechtigungen in der Gruppe zuerst in Ihrem Android-Manifest deklariert werden.

// Create a set of permissions for required data types
val PERMISSIONS =
    setOf(
  HealthPermission.getReadPermission(ExerciseSessionRecord::class),
  HealthPermission.getWritePermission(ExerciseSessionRecord::class)
)

Mit getGrantedPermissions können Sie prüfen, ob Ihrer App bereits die erforderlichen Berechtigungen erteilt wurden. Andernfalls kannst du sie mit createRequestPermissionResultContract anfordern. Daraufhin wird der Bildschirm mit den Health Connect-Berechtigungen angezeigt.

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

Da Nutzer Berechtigungen jederzeit gewähren oder widerrufen können, muss Ihre App regelmäßig nach erteilten Berechtigungen suchen und mit Szenarien umgehen, in denen die Berechtigung verloren geht.

In einem Trainingseintrags enthaltene Informationen

Jeder Eintrag für eine Trainingseinheit enthält die folgenden Informationen:

  • Die Art des Trainings, z. B. Radfahren.
  • Die Trainingsroute, die Informationen wie Breitengrad, Längengrad und Höhe enthält.

Unterstützte Aggregationen

Für diesen Datentyp werden keine Aggregationen unterstützt.

Anwendungsbeispiel

Route anfordern oder Route aus einer Sitzung schreiben

Route von einer Sitzung anfordern

So lesen Sie eine Sitzung in Health Connect und fordern eine Route von dieser Sitzung an:

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

Route aus einer Sitzung schreiben

Im folgenden Code wird gezeigt, wie eine Trainingseinheit mit einem Trainingsweg aufgezeichnet wird:

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