Начало работы с платформой "Здоровье и спорт"

Это руководство совместимо с версией 1.1.0-alpha12 платформы "Здоровье и спорт".

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

Шаг 1. Подготовьте приложение "Здоровье и спорт"

Приложение "Здоровье и спорт" обрабатывает все запросы, которые ваше приложение отправляет через SDK Health Connect. Эти запросы включают хранение данных и управление доступом к ним на чтение и запись.

Доступ к приложению "Здоровье и спорт" зависит от версии Android, установленной на телефоне. В следующих разделах описано, как работать с несколькими последними версиями Android.

Android 14

В Android 14 (уровень API 34) и более поздних версиях платформа "Здоровье и спорт" является частью фреймворка Android. Эта версия Health Connect представляет собой модуль фреймворка. Настраивать ничего не нужно.

Android 13 и более ранние версии

На устройствах с Android 13 (уровень API 33) и более ранних версий приложение "Здоровье и спорт" не является частью Android Framework. Для этого вам нужно установить приложение "Здоровье и спорт" из Google Play.

Если вы интегрировали приложение с платформой "Здоровье и спорт" на устройстве с Android 13 или более ранней версией и хотите перенести интеграцию на Android 14, ознакомьтесь с разделом Переход с Android 13 на 14.

Как открыть приложение "Здоровье и спорт"

Приложение "Здоровье и спорт" больше не показывается на главном экране по умолчанию. Вы можете открыть приложение "Здоровье и спорт" в настройках. Путь к нему зависит от версии Android:

  • На устройствах с Android 14 и более поздних версий: откройте Настройки > Безопасность и конфиденциальность > Настройки конфиденциальности > Здоровье и спорт или найдите Здоровье и спорт в настройках.
  • На устройстве с Android 13 и более ранних версий откройте Настройки > Приложения > Здоровье и спорт или добавьте приложение "Здоровье и спорт" в меню Быстрые настройки.

Шаг 2. Добавьте в приложение SDK Здоровья и спорта

Пакет SDK Health Connect использует API Health Connect для отправки запросов на выполнение операций с хранилищем данных в приложении "Здоровье и спорт".

Добавьте зависимость Health Connect SDK в файл build.gradle на уровне модуля:

dependencies {
  ...
  implementation "androidx.health.connect:connect-client:1.2.0-alpha06"
  ...
}

Последнюю версию можно найти на странице Выпуски приложения "Здоровье и спорт".

Как использовать функции канала обновления Canary

Чтобы использовать функции канала Canary, измените версию compileSdk в файле build.gradle на уровне модуля:

android {
  compileSdkPreview = "CANARY"
}

Шаг 3. Настройте приложение

В следующих разделах рассказывается, как настроить приложение для интеграции с Health Connect.

Доступность функций Google Pay по странам

Когда в платформу "Здоровье и спорт" добавляются новые функции, пользователи не всегда обновляют ее. Feature Availability API позволяет проверить, доступна ли функция платформы "Здоровье и спорт" на устройстве пользователя, и решить, что делать дальше.

Основная функция для проверки доступности функции – getFeatureStatus(). Возвращает целочисленные константы FEATURE_STATUS_AVAILABLE или FEATURE_STATUS_UNAVAILABLE:

fun enqueueBackgroundReadWorker(context: Context, healthConnectClient: HealthConnectClient) {
    if (healthConnectClient
            .features
            .getFeatureStatus(
                HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_IN_BACKGROUND
            ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE
    ) {

        val periodicWorkRequest = PeriodicWorkRequestBuilder<ScheduleWorker>(1, TimeUnit.HOURS)
            .build()

        WorkManager.getInstance(context).enqueueUniquePeriodicWork(
            "read_health_connect",
            ExistingPeriodicWorkPolicy.KEEP,
            periodicWorkRequest
        )
    }
}

Как объявлять разрешения

Доступ к данным о здоровье и физической активности требует осторожности. Платформа "Здоровье и спорт" реализует уровень безопасности для операций чтения и записи, поддерживая доверие пользователей.

В файле AndroidManifest.xml приложения укажите разрешения на чтение и запись, необходимые для типов данных, которые вы указали в Play Console.

Платформа "Здоровье и спорт" использует стандартный формат декларации разрешений Android. Назначайте разрешения с помощью тегов <uses-permission>. Вложите их в теги <manifest>.

<manifest>
  <uses-permission android:name="android.permission.health.READ_HEART_RATE"/>
  <uses-permission android:name="android.permission.health.WRITE_HEART_RATE"/>
  <uses-permission android:name="android.permission.health.READ_STEPS"/>
  <uses-permission android:name="android.permission.health.WRITE_STEPS"/>

  <application>
  ...
  </application>
</manifest>

Полный список разрешений и соответствующих им типов данных приведен в списке типов данных.

Как показать диалоговое окно с политикой конфиденциальности приложения

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

Задекларируйте это действие для обработки намерения ACTION_SHOW_PERMISSIONS_RATIONALE, которое отправляется в приложение, когда пользователь нажимает на ссылку Политика конфиденциальности на экране разрешений сервиса "Здоровье и спорт".

...
<application>
  ...
  <!-- For supported versions through Android 13, create an activity to show the rationale
       of Health Connect permissions once users click the privacy policy link. -->
  <activity
      android:name=".PermissionsRationaleActivity"
      android:exported="true">
    <intent-filter>
      <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
    </intent-filter>
  </activity>

  <!-- For versions starting Android 14, create an activity alias to show the rationale
       of Health Connect permissions once users click the privacy policy link. -->
  <activity-alias
      android:name="ViewPermissionUsageActivity"
      android:exported="true"
      android:targetActivity=".PermissionsRationaleActivity"
      android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
    <intent-filter>
      <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
      <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
    </intent-filter>
  </activity-alias>
  ...
</application>
...

Как получить клиентское приложение Здоровье и спорт

HealthConnectClient – это точка входа в API платформы "Здоровье и спорт". Она позволяет приложению использовать хранилище данных в приложении "Здоровье и спорт". Она автоматически управляет подключением к базовому уровню хранения и обрабатывает все IPC и сериализацию исходящих запросов и входящих ответов.

Чтобы получить экземпляр клиента, сначала укажите название пакета платформы "Здоровье и спорт" в манифесте Android.

<application> ... </application>
...
<!-- Check if Health Connect is installed -->
<queries>
    <package android:name="com.google.android.apps.healthdata" />
</queries>

Затем в разделе "Действия" проверьте, установлено ли приложение "Здоровье и спорт" getSdkStatus. Если да, получите экземпляр HealthConnectClient.

val availabilityStatus = HealthConnectClient.getSdkStatus(context)
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
    Box(modifier = modifier.padding(16.dp), contentAlignment = Alignment.Center) {
        Text(
            text = "Health Connect is not available on this device. Please ensure it is installed and updated.",
            style = MaterialTheme.typography.bodyLarge,
            textAlign = TextAlign.Center
        )
    }
    return
}

val healthConnectClient = remember {
    if (availabilityStatus == HealthConnectClient.SDK_AVAILABLE) {
        HealthConnectClient.getOrCreate(context)
    } else {
        null
    }
}

Шаг 4. Запросите у пользователя разрешения

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

val permissions =
    setOf(
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class),
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class)
    )
 Используйте getGrantedPermissions, чтобы проверить, есть ли у вашего приложения необходимые разрешения. Если нет, используйте createRequestPermissionResultContract, чтобы запросить эти разрешения. Откроется экран с разрешениями для сервиса "Здоровье и спорт". 
val permissions = setOf(
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class)
    )

val requestPermissionsLauncher = rememberLauncherForActivityResult(
    contract = PermissionController.createRequestPermissionResultContract()
) { grantedPermissions ->
    if (grantedPermissions.containsAll(permissions)) {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions granted!") }
    } else {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions denied.") }
    }
}
 Поскольку пользователи могут в любой момент предоставить или отозвать разрешения, ваше приложение должно проверять их каждый раз перед использованием и обрабатывать ситуации, когда разрешение теряется.

Начало работы для пользователей

Во многих приложениях есть собственный процесс регистрации, например с обучением использованию функций или запросом согласия пользователя. Чтобы разрешить сервису "Здоровье и спорт" запускать процесс регистрации, добавьте в манифест следующие строки:

<!-- Required to support pre-Android 14 devices with APK Health Connect -->
<activity
  android:name=".OnboardingActivity"
  android:exported="true"
  android:permission="com.google.android.apps.healthdata.permission.START_ONBOARDING">
  <intent-filter>
    <action android:name="androidx.health.ACTION_SHOW_ONBOARDING"/>
  </intent-filter>
</activity>
<!-- Required to support Android 14+ devices with platform Health Connect -->
<activity-alias
  android:name="UAndAboveOnboardingActivity"
  android:exported="true"
  android:targetActivity=".OnboardingActivity"
  android:permission="android.permission.health.START_ONBOARDING">
  <intent-filter>
    <action android:name="android.health.connect.action.SHOW_ONBOARDING" />
  </intent-filter>
</activity-alias>

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

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

Шаг 5. Выполните операции

Теперь, когда все настроено, выполните операции чтения и записи в приложении.

Ваши пользователи могут использовать другие приложения, которые синхронизируют данные с сервисом "Здоровье и спорт", чтобы ваше приложение могло получить к ним доступ. Если пользователь ещё не настроил запись данных в сервисе "Здоровье и спорт" в этих приложениях, вы можете использовать Matchmaking API, чтобы легко подключить их.

Запись данных

Структурируйте данные в виде записи. Ознакомьтесь со списком типов данных, доступных в приложении "Здоровье и спорт".

val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)
val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = zoneOffset,
    endZoneOffset = zoneOffset,
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))

Затем запишите трек с помощью insertRecords.

val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)
val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = zoneOffset,
    endZoneOffset = zoneOffset,
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))

Чтение данных

Вы можете прочитать свои данные по отдельности, используя readRecords.

val response = healthConnectClient.readRecords(
    ReadRecordsRequest(
        HeartRateRecord::class,
        timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
    )
)
response.records.forEach { record ->
    /* Process records */
}

Вы также можете просматривать агрегированные данные с помощью aggregate.

suspend fun readStepsAggregate(startTime: Instant, endTime: Instant): Long {
    val response = healthConnectClient.aggregate(
        AggregateRequest(
            metrics = setOf(StepsRecord.COUNT_TOTAL),
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
        )
    )
    return response[StepsRecord.COUNT_TOTAL] ?: 0L
}

Видеоруководства

Посмотрите эти видео, чтобы узнать больше о функциях Здоровья и спорта и рекомендациях по интеграции:

Ресурсы

Ознакомьтесь с приведенными ниже ресурсами, которые помогут вам в разработке.

Дальнейшие действия

В разделе Распространенные рабочие процессы вы найдете инструкции по выполнению различных операций в приложении "Здоровье и спорт", например: