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

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

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

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

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

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

Android 14

Начиная с Android 14 (уровень API 34), платформа "Здоровье и спорт" является частью фреймворка Android. Эта версия платформы "Здоровье и спорт" является модулем фреймворка. В этом случае настройка не требуется.

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

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

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

Откройте приложение "Здоровье и спорт".

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

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

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

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

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

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

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

Для connect-client версии 1.1.0 и более поздних требуется compileSdk = 36 и плагин Android Gradle (AGP) версии 8.9.1 или более поздней. Обновите compileSdk в файле build.gradle на уровне модуля:

android {
  compileSdk = 36
}

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

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

android {
  compileSdkPreview = "CANARY"
}

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

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

Доступность функций 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 должна быть указана Activity, которая показывает политику конфиденциальности приложения. В ней должно быть обоснование запрашиваемых разрешений и описание того, как используются и обрабатываются пользовательские данные.

Объявите это действие, чтобы обрабатывать намерение 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>

Затем в Activity проверьте, установлено ли приложение "Здоровье и спорт", используя 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
}

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

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

Ресурсы

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

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

В разделе Стандартные рабочие процессы рассказывается, как выполнять в приложении Здоровье и спорт следующие операции: