Данное руководство совместимо с версией Health Connect 1.1.0-alpha12 .
В этом руководстве показано, как начать использовать Health Connect в своем приложении.
Шаг 1: Подготовка приложения Health Connect
Приложение Health Connect отвечает за обработку всех запросов, которые ваше приложение отправляет через SDK Health Connect. Эти запросы включают в себя сохранение данных и управление доступом к ним для чтения и записи.
Доступ к Health Connect зависит от версии Android, установленной на телефоне. В следующих разделах описано, как работать с несколькими последними версиями Android.
Android 14
Начиная с Android 14 (уровень API 34), Health Connect является частью Android Framework. Эта версия Health Connect представляет собой модуль фреймворка . Поэтому настройка не требуется.
Android 13 и ниже
В Android 13 (API Level 33) и более ранних версиях приложение Health Connect не является частью Android Framework. Поэтому вам необходимо установить приложение Health Connect из Google Play Store.
Если ваше приложение интегрировано с 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: Добавьте SDK Health Connect в ваше приложение.
SDK Health Connect отвечает за использование API Health Connect для отправки запросов при выполнении операций с хранилищем данных в приложении Health Connect.
Добавьте зависимость Health Connect SDK в файл build.gradle на уровне модуля:
dependencies {
...
implementation "androidx.health.connect:connect-client:1.2.0-alpha02"
...
}
Актуальную версию можно найти в разделе "Релизы Health Connect" .
Шаг 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 внедряет дополнительный уровень защиты для операций чтения и записи, поддерживая доверие пользователей.
В вашем приложении укажите права на чтение и запись в файле 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. HealthConnect автоматически управляет подключением к базовому уровню хранения и обрабатывает все межпроцессные взаимодействия и сериализацию исходящих запросов и входящих ответов.
Чтобы получить экземпляр клиента, сначала укажите имя пакета 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 .
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, а также приводятся рекомендации по обеспечению бесперебойной интеграции:
- Управление правами доступа в Health Connect
- Чтение и письмо в Health Connect
- Советы по успешной интеграции с Health Connect
Ресурсы
Ознакомьтесь со следующими ресурсами, которые помогут в дальнейшей разработке.
- SDK Health Connect (доступен в Jetpack): Включите этот SDK в свое приложение, чтобы использовать API Health Connect.
- Справочник по API: ознакомьтесь со справочником Jetpack по API Health Connect.
- Объявление об использовании типов данных: В консоли Play укажите доступ к типам данных Health Connect, из которых ваше приложение читает и в которые записывает данные.
- Дополнительный пример кода и практическое задание на GitHub: для начала работы ознакомьтесь с репозиторием с примерами кода на GitHub и практическим заданием.
Следующие шаги
Ознакомьтесь с типовыми рабочими процессами , чтобы узнать, как выполнять такие операции в Health Connect, как: