Erste Schritte mit Health Connect

Diese Anleitung ist mit Health Connect-Version 1.1.0-alpha12 oder höher 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. Diese Anfragen umfassen das Speichern von Daten und das Verwalten 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 musst du die Health Connect App aus dem Google Play Store installieren.

Wenn Sie Ihre App unter Android 13 und niedriger in Health Connect integriert haben und zu Android 14 migrieren möchten, lesen Sie den Hilfeartikel Von Android 13 zu Android 14 migrieren.

Öffne die Health Connect App.

Health Connect wird standardmäßig nicht mehr auf dem Startbildschirm angezeigt. Du kannst 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:Gehe zu Einstellungen > Apps > Health Connect oder füge Health Connect zu den Schnelleinstellungen hinzu.

Schritt 2: Health Connect SDK in Ihre App einbinden

Das Health Connect SDK ist dafür verantwortlich, die Health Connect API zu verwenden, um Anfragen zum Ausführen von Vorgängen im Datenspeicher 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-alpha06"
  ...
}

Die aktuelle Version finden Sie unter Health Connect-Releases.

Für Version 1.1.0 und höher von connect-client sind compileSdk = 36 und das Android-Gradle-Plug-in (AGP) ab Version 8.9.1 erforderlich. Aktualisieren Sie die compileSdk in der Datei build.gradle auf Modulebene:

android {
  compileSdk = 36
}

Funktionen der Canary-Release-Version verwenden

Wenn Sie Funktionen in der Canary-Release-Version verwenden möchten, ändern Sie die Version von compileSdk in der Datei build.gradle auf Modulebene:

android {
  compileSdkPreview = "CANARY"
}

Schritt 3: App konfigurieren

In den folgenden Abschnitten wird erläutert, wie Sie Ihre App für die Integration in Health Connect konfigurieren.

Verfügbarkeit von Funktionen überprüfen

Wenn Health Connect neue Funktionen hinzugefügt werden, 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 ausgeführt werden soll.

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:

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
        )
    }
}

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 Datei AndroidManifest.xml 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 Android-Berechtigungserklärungen. Weisen Sie Berechtigungen mit den <uses-permission>-Tags zu. Verschachteln Sie sie innerhalb der <manifest>-Tags.

<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 findest du in der Liste der Datentypen.

Dialogfeld „Datenschutzerklärung“ Ihrer App anzeigen

Ihr Android-Manifest muss eine Aktivität enthalten, in der die Datenschutzerklärung Ihrer App angezeigt wird. Darin wird begründet, warum die angeforderten Berechtigungen erforderlich sind, und es wird beschrieben, wie die Daten des Nutzers verwendet und verarbeitet werden.

Deklariere diese Aktivität, um den Intent ACTION_SHOW_PERMISSIONS_RATIONALE zu verarbeiten, der an die App gesendet wird, wenn der Nutzer auf dem Health Connect-Berechtigungsbildschirm auf den Link zur 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 abrufen

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

Wenn du eine Clientinstanz abrufen möchtest, musst du zuerst den Health Connect-Paketnamen in deinem 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 Ihrer Aktivität mit getSdkStatus, ob Health Connect installiert ist. Ist das der Fall, rufen Sie eine HealthConnectClient-Instanz ab.

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

Schritt 4: Berechtigungen vom Nutzer anfordern

Nachdem Sie eine Clientinstanz erstellt haben, muss Ihre App Berechtigungen vom Nutzer anfordern. Nutzer müssen Berechtigungen jederzeit erteilen oder verweigern können. Erstellen Sie dazu eine Reihe von Berechtigungen für die erforderlichen Datentypen. Achte darauf, dass die Berechtigungen in der Gruppe zuerst in deinem Android-Manifest deklariert werden. 

val permissions =
    setOf(
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class),
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class)
    )
 Mit getGrantedPermissions kannst du prüfen, ob deiner App bereits die erforderlichen Berechtigungen gewährt wurden. Falls nicht, verwenden Sie createRequestPermissionResultContract, um diese Berechtigungen anzufordern. Der Bildschirm mit den Health Connect-Berechtigungen wird angezeigt. 
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.") }
    }
}
 Da Nutzer Berechtigungen jederzeit erteilen oder widerrufen können, muss deine App vor jeder Verwendung prüfen, ob die Berechtigungen vorhanden sind, und Szenarien verarbeiten, in denen die Berechtigung verloren geht.

Nutzer einrichten

Viele Apps haben einen benutzerdefinierten Onboarding-Prozess, z. B. eine Einführung in die Funktionen oder die Abfrage der Nutzereinwilligung. Damit Health Connect den Onboarding-Vorgang 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 initiieren, anstatt über Ihre App. Wenn Ihre App zusätzliche Interaktionen erfordert, die über die Berechtigung zum Lesen oder Schreiben von Daten hinausgehen, 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 deine App widerruft und sie dann wieder verbindet.

Schritt 5: Vorgänge ausführen

Nachdem alles eingerichtet ist, können Sie in Ihrer App Lese- und Schreibvorgänge ausführen.

Ihre Nutzer verwenden möglicherweise andere Apps, die Daten mit Health Connect synchronisieren, damit Ihre App darauf zugreifen kann. Wenn der Nutzer diese Apps noch nicht so eingerichtet hat, dass sie in Health Connect schreiben, kannst du die Matchmaking API verwenden, um diese Apps nahtlos für deine Nutzer zu verbinden.

Daten schreiben

Strukturieren Sie Ihre Daten in einem Datensatz. Eine Liste der in Health Connect verfügbaren Datentypen findest du hier.

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

Schreiben Sie dann den Eintrag mit 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))

Daten lesen

Sie können Ihre Daten mit readRecords einzeln lesen.

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

Sie können Ihre Daten auch aggregiert mit aggregate lesen.

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
}

Videoanleitungen

In diesen Videos werden die Health Connect-Funktionen sowie Best Practices für eine reibungslose Integration erläutert:

Ressourcen

Sehen Sie sich die folgenden Ressourcen an, die Ihnen später bei der Entwicklung helfen.

  • Health Connect SDK (verfügbar auf Jetpack): Binde dieses SDK in deine Anwendung ein, um die Health Connect API zu verwenden.
  • API-Referenz:In der Jetpack-Referenz findest du Informationen zur Health Connect API.
  • Verwendung von Datentypen deklarieren:Deklariere in der Play Console den Zugriff auf die Health Connect-Datentypen, die deine App liest und schreibt.
  • Optionales GitHub-Codebeispiel und Codelab: Sehen Sie sich das GitHub-Codebeispiel-Repository und die Codelab-Übung an, um den Einstieg zu erleichtern.

Nächste Schritte

Unter Häufige Workflows finden Sie Informationen dazu, wie Sie in Health Connect Vorgänge ausführen, z. B.: