Начните работу с Health Connect

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

В этом руководстве показано, как начать использовать Health Connect в вашем приложении.

Шаг 1: Подготовьте приложение Health Connect

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

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

Андроид 14

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

Android 13 и ниже

В Android 13 (API уровня 33) и более ранних версиях Health Connect не входит в состав Android Framework. В этом случае вам необходимо установить приложение Health Connect из Google Play.

Если вы интегрировали свое приложение с Health Connect на Android 13 и ниже и хотите перейти на Android 14, см. раздел Миграция с Android 13 на 14 .

Откройте приложение Health Connect.

Health Connect больше не отображается на главном экране по умолчанию. Вы можете открыть Health Connect через «Настройки» , хотя путь к нему может различаться в зависимости от версии Android:

• На Android 14 и выше: перейдите в «Настройки» > «Безопасность и конфиденциальность» > «Управление конфиденциальностью» > Health Connect или найдите Health Connect в настройках.
• На Android 13 и ниже: перейдите в «Настройки» > «Приложения» > «Health Connect » или добавьте Health Connect в меню быстрых настроек .

Шаг 2: Добавьте Health Connect SDK в свое приложение

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

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

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

Последнюю версию смотрите в выпусках Health Connect .

Примечание: Health Connect SDK поддерживает Android 8 (API уровня 26) и выше, в то время как приложение Health Connect совместимо только с Android 9 (API уровня 28) и выше. Это означает, что сторонние приложения могут поддерживать пользователей Android 8, но использовать Health Connect могут только пользователи Android 9 и выше.

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

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

Проверить доступность функции

При добавлении новых функций в Health Connect пользователи не всегда могут обновить свою версию Health Connect. API доступности функций — это способ проверить, доступна ли функция Health Connect на устройстве пользователя, и решить, какие действия следует предпринять.

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

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

  // Feature is available
  ...
} else {
  // Feature is not available
  ...
}

Примечание: Если функция недоступна, попросите пользователя обновить Health Connect. Функции, связанные с системным модулем, остаются недоступными на Android 13 и ниже, даже при использовании APK.

Объявить разрешения

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

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

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

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

Получите клиента Health Connect

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

Чтобы получить экземпляр клиента, сначала объявите имя пакета Health Connect в манифесте Android.

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

Затем в Activity проверьте, установлен ли Health Connect, с помощью getSdkStatus . Если установлен, получите экземпляр HealthConnectClient .

val availabilityStatus = HealthConnectClient.getSdkStatus(context, providerPackageName)
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
  return // early return as there is no viable integration
}
if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE_PROVIDER_UPDATE_REQUIRED) {
  // Optionally redirect to package installer to find a provider, for example:
  val uriString = "market://details?id=$providerPackageName&url=healthconnect%3A%2F%2Fonboarding"
  context.startActivity(
    Intent(Intent.ACTION_VIEW).apply {
      setPackage("com.android.vending")
      data = Uri.parse(uriString)
      putExtra("overlay", true)
      putExtra("callerId", context.packageName)
    }
  )
  return
}
val healthConnectClient = HealthConnectClient.getOrCreate(context)
// Issue operations with healthConnectClient

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

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

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

// Create a set of permissions for required data types
val PERMISSIONS =
    setOf(
  HealthPermission.getReadPermission(HeartRateRecord::class),
  HealthPermission.getWritePermission(HeartRateRecord::class),
  HealthPermission.getReadPermission(StepsRecord::class),
  HealthPermission.getWritePermission(StepsRecord::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 мог запустить процедуру адаптации, добавьте в манифест следующее:

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

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

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

Шаг 5: Выполнение операций

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

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

Структурируйте данные в виде записи. Ознакомьтесь со списком типов данных, доступных в Health Connect.

val stepsRecord = StepsRecord(
    count = 120,
    startTime = START_TIME,
    endTime = END_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endZoneOffset = END_ZONE_OFFSET,
)

Затем запишите свою запись, используя insertRecords .

suspend fun insertSteps(healthConnectClient: HealthConnectClient) {
    val endTime = Instant.now()
    val startTime = endTime.minus(Duration.ofMinutes(15))
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = startTime,
            endTime = endTime,
            startZoneOffset = ZoneOffset.UTC,
            endZoneOffset = ZoneOffset.UTC,
            metadata = Metadata.autoRecorded(
                device = Device(type = Device.TYPE_WATCH)
            ),
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling here
    }
}

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

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

Примечание: для кумулятивных типов, таких как StepsRecord , используйте aggregate() вместо readRecords() , чтобы избежать двойного учёта из нескольких источников и повысить точность. Подробнее см. в разделе Чтение агрегированных данных .

suspend fun readHeartRateByTimeRange(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.readRecords(
            ReadRecordsRequest(
                HeartRateRecord::class,
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
        for (record in response.records) {
            // Process each record
        }
    } catch (e: Exception) {
        // Run error handling here
    }
}

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

suspend fun aggregateSteps(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.aggregate(
            AggregateRequest(
                metrics = setOf(StepsRecord.COUNT_TOTAL),
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
        // The result may be null if no data is available in the time range
        val stepCount = response[StepsRecord.COUNT_TOTAL]
    } catch (e: Exception) {
        // Run error handling here
    }
}

Важно: Health Connect может читать данные за период до 30 дней до момента предоставления разрешения. Если вы хотите, чтобы ваше приложение читало записи за период более 30 дней, используйте разрешение PERMISSION_READ_HEALTH_DATA_HISTORY . Подробнее см. в разделе « Ограничения на чтение» .

Видеоуроки

Посмотрите эти видеоролики, в которых более подробно рассказывается о функциях Health Connect, а также приводятся рекомендации по передовому опыту для достижения бесперебойной интеграции:

• Управление разрешениями в Health Connect
• Чтение и письмо в Health Connect
• Советы по эффективной интеграции Health Connect

Ресурсы

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

• Health Connect SDK (доступно в Jetpack): включите этот SDK в свое приложение, чтобы использовать API Health Connect.
• Справочник API: ознакомьтесь со справочником Jetpack по API Health Connect.
• Объявите использование типов данных: в Play Console объявите доступ к типам данных Health Connect, которые ваше приложение считывает и в которые записывает.
• Дополнительный пример кода GitHub и практическое задание: ознакомьтесь с репозиторием примеров кода GitHub и практическим заданием, которые помогут вам приступить к работе.

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

Следующие шаги

Ознакомьтесь с разделом Общие рабочие процессы , чтобы узнать, как выполнять такие операции в Health Connect, как:

• Запись данных
• Чтение необработанных данных
• Прочитать агрегированные данные