Добавьте маршруты тренировок

Данное руководство совместимо с Health Connect версии 1.1.0-alpha12 .

Маршруты тренировок позволяют пользователям отслеживать маршрут GPS для соответствующих занятий спортом и делиться картами своих тренировок с другими приложениями.

В этом руководстве содержится информация о том, как запрашивать разрешения у пользователя, а также описывается, как приложения получают разрешение на запись данных маршрута в рамках сеанса тренировки.

Функции чтения и записи для маршрутов упражнений включают:

  1. Приложения создают новое разрешение на запись для маршрутов тренировок.
  2. Вставка происходит путем записи сеанса упражнений с маршрутом в качестве поля.
  3. Чтение:
    1. Для владельца сеанса доступ к данным осуществляется с помощью чтения сеанса.
    2. Из стороннего приложения через диалоговое окно, позволяющее пользователю единоразово предоставить разрешение на чтение маршрута.

Если у пользователя нет прав на запись и маршрут не установлен, маршрут не обновится.

Если ваше приложение имеет разрешение на запись маршрута и пытается обновить сеанс, передавая объект сеанса без маршрута, существующий маршрут удаляется.

Требуемые разрешения

Доступ к маршрутам тренировок защищен следующими разрешениями:

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

Чтобы добавить в приложение возможность создания маршрутов тренировок, начните с запроса разрешений на запись для определенного типа данных.

Вам также необходимо заявить о разрешении на тренировку, поскольку каждый маршрут связан с сеансом тренировки (один сеанс = одна тренировка).

Вот разрешение, которое вам необходимо заявить, чтобы иметь возможность писать маршруты тренировок:

<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() при первом подключении приложения к Health Connect. Несколько разрешений, которые вы можете запросить:

  • Чтение данных о состоянии здоровья, включая данные маршрута: 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)
  }
}

Поскольку пользователи могут предоставлять или отзывать разрешения в любое время, вашему приложению необходимо периодически проверять наличие предоставленных разрешений и обрабатывать сценарии, в которых разрешение теряется.

Информация, включенная в запись сеанса тренировки

Каждая запись сеанса упражнений содержит следующую информацию:

  • Тип упражнения, например, езда на велосипеде.
  • Маршрут упражнения, содержащий такую ​​информацию, как широта, долгота и высота.

Поддерживаемые агрегации

Для этого типа данных не поддерживается агрегация.

Пример использования

Запросите маршрут или напишите маршрут из сеанса.

Запросить маршрут из сеанса

Вот как прочитать сеанс в Health Connect и запросить маршрут из этого сеанса:

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

Написать маршрут из сеанса

Следующий код демонстрирует, как записать сеанс, включающий маршрут упражнений:

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