Erste Schritte mit Health Connect

Diese Anleitung ist mit Health Connect-Version 1.1.0-alpha12 kompatibel.

In dieser Anleitung erfahren Sie, wie Sie Health Connect in Ihrer App verwenden können.

Schritt 1: Health Connect App vorbereiten

Die Health Connect App verarbeitet alle Anfragen, 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 erläutert, wie Sie mit verschiedenen 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. Daher ist keine Einrichtung erforderlich.

Android 13 und niedriger

Unter Android 13 (API-Level 33) und niedriger ist Health Connect nicht Teil des Android-Frameworks. Daher müssen Sie die Health Connect App aus dem Google Play Store installieren.

Wenn Sie Ihre App unter Android 13 und niedriger in Health Connect eingebunden haben und zu Android 14 migrieren möchten, lesen Sie den Hilfeartikel Von Android 13 zu 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:

  • Android 14 und höher:Rufen Sie die Einstellungen > Sicherheit und Datenschutz > Datenschutzeinstellungen > Health Connect auf oder suchen Sie in den Einstellungen nach Health Connect.
  • Android 13 und niedriger:Rufen Sie die Einstellungen > Apps > Health Connect auf oder fügen Sie Health Connect dem Menü Schnelleinstellungen hinzu.

Schritt 2: Health Connect SDK in Ihrer App hinzufügen

Das Health Connect SDK verwendet die Health Connect API, um Anfragen zu senden und Vorgänge für den Datenspeicher in der Health Connect App auszuführen.

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-alpha04"
  ...
}

Die aktuelle Version finden Sie unter Health Connect-Releases.

Funktionen des Canary-Releasekanals verwenden

Wenn Sie Funktionen im Canary -Releasekanal 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 Einbindung in Health Connect konfigurieren.

Verfügbarkeit von Funktionen überprüfen

Wenn Health Connect neue Funktionen hinzugefügt werden, aktualisieren Nutzer möglicherweise nicht immer ihre Version von Health Connect. 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 Maßnahmen ergriffen werden sollen.

Die Hauptfunktion zum Prüfen der Verfügbarkeit von Funktionen ist getFeatureStatus(). Diese Funktion gibt die Ganzzahlkonstanten FEATURE_STATUS_AVAILABLE oder FEATURE_STATUS_UNAVAILABLE zurück:

@OptIn(ExperimentalFeatureAvailabilityApi::class)
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 müssen mit den Datentypen übereinstimmen, für die Sie in der Play Console Zugriff deklariert haben.

Health Connect verwendet das Standardformat für die Android-Berechtigungserklärung. Weisen Sie Berechtigungen mit den <uses-permission> Tags zu. Verschachteln Sie sie in den <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 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 Activity, um die ACTION_SHOW_PERMISSIONS_RATIONALE-Intent zu verarbeiten, die an die App gesendet wird, wenn der Nutzer auf dem Berechtigungsbildschirm von Health Connect 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 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 Sie eine Clientinstanz abrufen möchten, deklarieren Sie zuerst den Health Connect-Paketnamen in Ihrem Android-Manifest.

<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, ob Health Connect installiert ist mit getSdkStatus. Wenn ja, 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 jederzeit Berechtigungen erteilen oder verweigern können.

Erstellen Sie dazu eine Reihe von Berechtigungen für die erforderlichen Datentypen. Achten Sie darauf, dass die Berechtigungen im Set 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. Wenn nicht, fordern Sie diese Berechtigungen mit createRequestPermissionResultContract an. Dadurch wird der Berechtigungsbildschirm von Health Connect 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 aufheben können, muss Ihre App jedes Mal prüfen, ob Berechtigungen vorhanden sind, bevor sie verwendet werden. Außerdem muss sie Szenarien verarbeiten, in denen Berechtigungen verloren gehen.

Nutzer einarbeiten

Viele Apps haben einen benutzerdefinierten Onboarding-Prozess, z. B. eine Einführung in die Funktionen oder eine Aufforderung zur Einwilligung des Nutzers. Wenn Health Connect Ihren Onboarding-Prozess starten soll, 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 eine zusätzliche Interaktion erforderlich ist, die über die Berechtigung zum Lesen oder Schreiben von Daten hinausgeht, 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 in Ihrer App Lese- und Schreibvorgänge ausführen.

Ihre Nutzer verwenden möglicherweise andere Apps, die Daten mit Health Connect synchronisieren, auf die Ihre App zugreifen kann. Wenn der Nutzer diese Apps noch nicht so eingerichtet hat, dass sie Daten in Health Connect schreiben, können Sie mit der Matchmaking API diese Apps nahtlos verbinden für Ihre Nutzer.

Daten schreiben

Strukturieren Sie Ihre Daten in einem Datensatz. Sehen Sie sich die Liste der Datentypen in Health Connect an.

val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)
val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = zoneOffset,
    endZoneOffset = zoneOffset,
    metadata = Metadata(
        device = Device(type = Device.TYPE_WATCH),
        recordingMethod = Metadata.RECORDING_METHOD_AUTOMATICALLY_RECORDED
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))

Schreiben Sie dann Ihren Datensatz mit insertRecords.

val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)
val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = zoneOffset,
    endZoneOffset = zoneOffset,
    metadata = Metadata(
        device = Device(type = Device.TYPE_WATCH),
        recordingMethod = Metadata.RECORDING_METHOD_AUTOMATICALLY_RECORDED
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))

Daten lesen

Sie können Ihre Daten einzeln mit readRecords 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 erfahren Sie mehr über die Funktionen von Health Connect und erhalten Best-Practice-Richtlinien für eine reibungslose Einbindung:

Ressourcen

Die folgenden Ressourcen können Ihnen bei der Entwicklung helfen.

  • Health Connect SDK (verfügbar in Jetpack): Fügen Sie dieses SDK in Ihre Anwendung ein, um die Health Connect API zu verwenden.
  • API-Referenz: Sehen Sie sich die Jetpack-Referenz für die Health Connect API an.
  • Verwendung von Datentypen deklarieren:Deklarieren Sie in der Play Console, den Zugriff auf die Health Connect-Datentypen, aus denen Ihre App Daten liest und in die sie Daten schreibt.
  • Optionales GitHub-Codebeispiel und Codelab: Im GitHub-Codebeispiel Repository und im Codelab finden Sie Informationen, die Ihnen den Einstieg erleichtern.

Nächste Schritte

Unter Häufige Arbeitsabläufe erfahren Sie, wie Sie Vorgänge in Health Connect ausführen, z. B.: