Dieser Leitfaden ist mit Health Connect-Version 1.1.0-alpha12 kompatibel.
In diesem Leitfaden erfahren Sie, wie Sie Health Connect in Ihrer App verwenden können.
Schritt 1: Health Connect App vorbereiten
Die Health Connect App ist für die Verarbeitung aller Anfragen verantwortlich, die Ihre Anwendung über das Health Connect SDK sendet. Dazu gehören das Speichern von Daten und die Verwaltung des Lese- und Schreibzugriffs.
Der Zugriff auf Health Connect hängt von der auf dem Smartphone installierten Android-Version ab. In den folgenden Abschnitten wird beschrieben, wie Sie mit mehreren aktuellen Android-Versionen umgehen.
Android 14
Ab Android 14 (API‑Level 34) ist Health Connect Teil des Android-Frameworks. Diese Version von Health Connect ist ein Framework-Modul. Es ist keine Einrichtung erforderlich.
Android 13 und niedriger
Unter Android 13 (API‑Level 33) und niedrigeren Versionen ist Health Connect nicht Teil des Android-Frameworks. Dazu müssen Sie die Health Connect App aus dem Google Play Store installieren.
Wenn Sie Ihre App unter Android 13 oder niedriger in Health Connect integriert haben und unter Android 14 migrieren möchten, lesen Sie den Abschnitt Von Android 13 auf Android 14 migrieren.
Health Connect App öffnen
Health Connect wird standardmäßig nicht mehr auf dem Startbildschirm angezeigt. Sie können Health Connect über die Einstellungen öffnen. Der Pfad variiert jedoch je nach Android-Version:
- Unter Android 14 und höher:Gehe zu Einstellungen > Sicherheit und Datenschutz > Datenschutzeinstellungen > Health Connect oder suche in den Einstellungen nach Health Connect.
- Android 13 und niedriger:Gehen Sie zu Einstellungen > Apps > Health Connect oder fügen Sie Health Connect den Schnelleinstellungen hinzu.
Schritt 2: Health Connect SDK in Ihre App einfügen
Das Health Connect SDK ist dafür verantwortlich, die Health Connect API zu verwenden, um Anfragen zum Ausführen von Vorgängen für den Datenspeicher in der Health Connect App zu senden.
Fügen Sie die Health Connect SDK-Abhängigkeit in die Datei build.gradle
auf Modulebene ein:
dependencies {
...
implementation "androidx.health.connect:connect-client:1.2.0-alpha02"
...
}
Die aktuelle Version finden Sie unter Health Connect-Releases.
Schritt 3: App konfigurieren
In den folgenden Abschnitten wird beschrieben, wie Sie Ihre App für die Integration in Health Connect konfigurieren.
Verfügbarkeit von Funktionen überprüfen
Wenn Health Connect neue Funktionen erhält, aktualisieren Nutzer ihre Version von Health Connect möglicherweise nicht immer. Mit der Feature Availability API können Sie prüfen, ob eine Funktion in Health Connect auf dem Gerät des Nutzers verfügbar ist, und entscheiden, welche Aktion Sie ausführen möchten.
Die Hauptfunktion zum Prüfen der Verfügbarkeit von Funktionen ist getFeatureStatus()
. Dadurch werden die Ganzzahlkonstanten FEATURE_STATUS_AVAILABLE
oder FEATURE_STATUS_UNAVAILABLE
zurückgegeben:
if (healthConnectClient
.features
.getFeatureStatus(
HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_IN_BACKGROUND
) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE) {
// Feature is available
...
} else {
// Feature is not available
...
}
Berechtigungen deklarieren
Der Zugriff auf Gesundheits- und Fitnessdaten ist sensibel. Health Connect implementiert eine Sicherheitsebene für Lese- und Schreibvorgänge, um das Vertrauen der Nutzer zu wahren.
Deklarieren Sie in Ihrer App Lese- und Schreibberechtigungen in der AndroidManifest.xml
-Datei basierend auf den erforderlichen Datentypen. Diese sollten mit den Datentypen übereinstimmen, für die Sie in der Play Console den Zugriff deklariert haben.
Health Connect verwendet das Standardformat für die Android-Berechtigungserklärung.
Weisen Sie Berechtigungen mit den <uses-permission>
-Tags zu. Schließen Sie sie in die <manifest>
-Tags ein.
<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>
Eine vollständige Liste der Berechtigungen und der entsprechenden Datentypen finden Sie unter Liste der Datentypen.
Dialogfeld zur Datenschutzerklärung Ihrer App anzeigen
Ihr Android-Manifest muss eine Aktivität enthalten, in der die Datenschutzerklärung Ihrer App angezeigt wird. Darin wird die Begründung für die angeforderten Berechtigungen erläutert und beschrieben, wie die Daten des Nutzers verwendet und verarbeitet werden.
Deklarieren Sie diese Aktivität, um den ACTION_SHOW_PERMISSIONS_RATIONALE
-Intent zu verarbeiten, der an die App gesendet wird, wenn der Nutzer auf dem Health Connect-Berechtigungsbildschirm auf den Link Datenschutzerklärung klickt.
...
<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-Client herunterladen
HealthConnectClient
ist ein Einstiegspunkt für die Health Connect API.
Damit kann die App den Datenspeicher in der Health Connect App verwenden. Die Verbindung zur zugrunde liegenden Speicherebene wird automatisch verwaltet und alle IPC- und Serialisierungsvorgänge für ausgehende Anfragen und eingehende Antworten werden übernommen.
Wenn Sie eine Clientinstanz abrufen möchten, müssen Sie zuerst den Health Connect-Paketnamen in Ihrem Android-Manifest deklarieren.
<application> ... </application>
...
<!-- Check if Health Connect is installed -->
<queries>
<package android:name="com.google.android.apps.healthdata" />
</queries>
Prüfen Sie dann in Ihren Aktivitäten, ob Health Connect mit getSdkStatus
installiert wurde. Wenn ja, rufen Sie eine HealthConnectClient
-Instanz ab.
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
Schritt 4: Berechtigungen vom Nutzer anfordern
Nachdem Sie eine Client-Instanz erstellt haben, muss Ihre App Berechtigungen vom Nutzer anfordern. Nutzer müssen jederzeit die Möglichkeit haben, Berechtigungen zu erteilen oder zu verweigern.
Erstellen Sie dazu eine Reihe von Berechtigungen für die erforderlichen Datentypen. Die Berechtigungen im Set müssen zuerst in Ihrem Android-Manifest deklariert werden.
// 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)
)
Mit getGrantedPermissions
können Sie prüfen, ob Ihrer App bereits die erforderlichen Berechtigungen erteilt wurden. Falls nicht, verwenden Sie createRequestPermissionResultContract
, um diese Berechtigungen anzufordern. Der Bildschirm mit den Health Connect-Berechtigungen wird angezeigt.
// 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)
}
}
Da Nutzer Berechtigungen jederzeit erteilen oder widerrufen können, muss Ihre App regelmäßig prüfen, welche Berechtigungen erteilt wurden, und Szenarien berücksichtigen, in denen Berechtigungen verloren gehen.
Nutzer einarbeiten
Viele Apps haben einen benutzerdefinierten Onboarding-Ablauf, z. B. zur Erklärung von Funktionen oder zur Einholung der Nutzereinwilligung. Damit Health Connect Ihren Onboarding-Ablauf starten kann, fügen Sie Ihrem Manifest Folgendes hinzu:
<!-- 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>
Nutzer können die Verbindung zu Ihrer App direkt über die Health Connect App und nicht über Ihre App herstellen. Wenn für Ihre App zusätzliche Interaktionen erforderlich sind, nachdem die Berechtigung zum Lesen oder Schreiben von Daten erteilt wurde, stellen Sie eine Onboarding-Aktivität bereit.
Die Onboarding-Aktivität kann mehrmals gestartet werden, z. B. wenn der Nutzer später die Berechtigungen für Ihre App widerruft und sie dann wieder verbindet.
Schritt 5: Vorgänge ausführen
Nachdem alles eingerichtet ist, können Sie Lese- und Schreibvorgänge in Ihrer App ausführen.
Daten schreiben
Strukturieren Sie Ihre Daten in einem Datensatz. Hier findest du eine Liste der in Health Connect verfügbaren Datentypen.
val stepsRecord = StepsRecord(
count = 120,
startTime = START_TIME,
endTime = END_TIME,
startZoneOffset = START_ZONE_OFFSET,
endZoneOffset = END_ZONE_OFFSET,
)
Schreiben Sie dann Ihren Datensatz mit 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
}
}
Daten lesen
Mit readRecords
können Sie Ihre Daten einzeln lesen.
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
}
}
Sie können Ihre Daten auch aggregiert mit aggregate
lesen.
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
}
}
Videoanleitungen
In diesen Videos werden die Health Connect-Funktionen und Best Practices für eine reibungslose Integration erläutert:
- Berechtigungen in Health Connect verwalten
- Lesen und Schreiben in Health Connect
- Tipps für eine gute Health Connect-Integration
Ressourcen
Die folgenden Ressourcen können Ihnen bei der Entwicklung helfen.
- Health Connect SDK (in Jetpack verfügbar): Fügen Sie dieses SDK in Ihre Anwendung ein, um die Health Connect API zu verwenden.
- API-Referenz:In der Jetpack-Referenz finden Sie Informationen zur Health Connect API.
- Verwendung von Datentypen deklarieren:Deklarieren Sie in der Play Console den Zugriff auf die Health Connect-Datentypen, die Ihre App liest und in die sie schreibt.
- Optionales GitHub-Codebeispiel und Codelab:Das GitHub-Codebeispiel-Repository und das Codelab können Ihnen den Einstieg erleichtern.
Nächste Schritte
Unter Häufige Workflows erfahren Sie, wie Sie Vorgänge in Health Connect ausführen, z. B.: