Ta strona została przetłumaczona przez Cloud Translation API.

Dodaj trasy ćwiczeń

Ten przewodnik jest zgodny z Health Connect w wersji 1.1.0-alpha12.

Trasy ćwiczeń umożliwiają użytkownikom śledzenie trasy GPS powiązanych aktywności i udostępnianie map treningów innym aplikacjom.

Dostępność funkcji

Aby sprawdzić, czy urządzenie użytkownika obsługuje trasy ćwiczeń w Health Connect, sprawdź dostępność FEATURE_PLANNED_EXERCISE na urządzeniu:

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

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

Więcej informacji znajdziesz w sekcji Sprawdzanie dostępności funkcji.

W tym przewodniku znajdziesz informacje o tym, jak prosić użytkownika o uprawnienia, a także jak aplikacje otrzymują uprawnienia do zapisywania danych o trasie w ramach sesji ćwiczeń.

Funkcje odczytu i zapisu tras ćwiczeń obejmują:

Aplikacje tworzą nowe uprawnienia do zapisu dotyczące tras ćwiczeń.
Wstawianie odbywa się przez zapisanie sesji ćwiczeń z trasą jako polem.
Odczyt:
1. W przypadku właściciela sesji dostęp do danych uzyskuje się za pomocą odczytu sesji.
2. z aplikacji innej firmy za pomocą okna, które umożliwia użytkownikowi jednorazowe odczytanie trasy;

Jeśli użytkownik nie ma uprawnień do zapisu, a trasa nie jest ustawiona, trasa nie zostanie zaktualizowana.

Jeśli aplikacja ma uprawnienia do zapisu trasy i próbuje zaktualizować sesję, przekazując obiekt sesji bez trasy, dotychczasowa trasa zostanie usunięta.

Wymagane uprawnienia

Dostęp do trasy ćwiczeń jest chroniony przez te uprawnienia:

android.permission.health.READ_EXERCISE_ROUTE
android.permission.health.WRITE_EXERCISE_ROUTE

Aby dodać do aplikacji funkcję trasy ćwiczeń, zacznij od poproszenia o uprawnienia do zapisu w przypadku typu danych ExerciseSession.

Aby móc zapisywać trasy ćwiczeń, musisz zadeklarować to uprawnienie:

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

Aby odczytać trasę ćwiczeń, musisz poprosić o te uprawnienia:

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

Musisz też zadeklarować uprawnienia do ćwiczeń, ponieważ każda trasa jest powiązana z sesją ćwiczeń (1 sesja = 1 trening).

Aby poprosić o uprawnienia, użyj metody PermissionController.createRequestPermissionResultContract(), gdy po raz pierwszy połączysz aplikację z Health Connect. Oto kilka uprawnień, o które możesz poprosić:

Odczytywanie danych dotyczących zdrowia, w tym danych o trasie:HealthPermission.getReadPermission(ExerciseSessionRecord::class)
Zapisywanie danych o zdrowiu, w tym danych o trasie:HealthPermission.getWritePermission(ExerciseSessionRecord::class)
Zapisywanie danych trasy ćwiczeń: HealthPermission.PERMISSION_WRITE_EXERCISE_ROUTE

Prośba użytkownika o uprawnienia

Po utworzeniu instancji klienta aplikacja musi poprosić użytkownika o przyznanie uprawnień. Użytkownicy muszą mieć możliwość przyznania lub odmowy przyznania uprawnień w dowolnym momencie.

Aby to zrobić, utwórz zestaw uprawnień dla wymaganych typów danych. Sprawdź, czy uprawnienia w zestawie są najpierw zadeklarowane w pliku manifestu Androida.

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

Użyj getGrantedPermissions, aby sprawdzić, czy Twoja aplikacja ma już przyznane wymagane uprawnienia. Jeśli nie, użyj createRequestPermissionResultContract, aby poprosić o te uprawnienia. Wyświetli się ekran uprawnień 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)
  }
}

Użytkownicy mogą w dowolnym momencie przyznawać i wycofywać uprawnienia, dlatego aplikacja musi okresowo sprawdzać, czy uprawnienia zostały przyznane, i obsługiwać sytuacje, w których uprawnienia zostaną utracone.

Informacje zawarte w rekordzie sesji ćwiczeń

Każdy rekord sesji ćwiczeń zawiera te informacje:

Rodzaj ćwiczenia, np. jazda na rowerze.
Trasa ćwiczeń, która zawiera informacje takie jak szerokość i długość geograficzna oraz wysokość.

Obsługiwane agregacje

W przypadku tego typu danych nie ma obsługiwanych agregacji.

Przykład użycia

Poniższe fragmenty kodu pokazują, jak odczytywać i zapisywać trasę ćwiczeń.

Odczytuj trasę ćwiczeń

Ten fragment kodu pokazuje, jak odczytać sesję w Health Connect i poprosić o trasę z tej sesji:

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

Zapisywanie trasy ćwiczeń

Poniższy kod pokazuje, jak zarejestrować sesję, która obejmuje trasę ćwiczeń:

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

Sesje ćwiczeń

Sesje ćwiczeń mogą obejmować wszystko, od biegania po badmintona.

Zapisywanie sesji ćwiczeń

Oto jak utworzyć żądanie wstawienia, które zawiera sesję:

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"
            ),
            // ... other records
        )
    )
}

Odczytywanie sesji ćwiczeń

Oto przykład odczytywania sesji ćwiczeń:

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

Zapisywanie danych podtypu

Sesje mogą też zawierać opcjonalne dane podtypu, które wzbogacają sesję o dodatkowe informacje.

Na przykład sesje ćwiczeń mogą obejmować zajęcia ExerciseSegment, ExerciseLap i 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
)

Usuwanie sesji ćwiczeń

Sesję ćwiczeń możesz usunąć na 2 sposoby:

według zakresu czasowego,
według identyfikatora UID,

Aby usunąć dane podtypu według zakresu czasu:

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

Możesz też usuwać dane podtypu według identyfikatora UID. Spowoduje to usunięcie tylko sesji ćwiczeń, a nie powiązanych z nią danych:

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