Diese Seite wurde von der Cloud Translation API übersetzt.

Erste Schritte mit Health Connect

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 App ü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 also 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 und niedriger mit Health Connect integriert haben und zu Android 14 migrieren möchten, lesen Sie den Hilfeartikel Von Android 13 auf Android 14 migrieren.

Öffnen Sie die Health Connect App.

Health Connect wird nicht mehr standardmäßig auf dem Startbildschirm angezeigt. Sie können Health Connect über Einstellungen > Apps > Health Connect öffnen oder Health Connect zu den Schnelleinstellungen hinzufügen.

Außerdem muss der Nutzer in Health Connect die Displaysperre mit einer PIN, einem Muster oder einem Passwort aktivieren, damit die in Health Connect gespeicherten Gesundheitsdaten während der Sperrung des Geräts vor böswilligen Akteuren geschützt sind. Wenn Sie eine Displaysperre einrichten möchten, gehen Sie zu Einstellungen > Sicherheit > Displaysperre.

Schritt 2: Der App das Health Connect SDK hinzufügen

Das Health Connect SDK ist dafür verantwortlich, über die Health Connect API Anfragen zu senden, um Vorgänge im Datenspeicher in der Health Connect App auszuführen.

Fügen Sie die Abhängigkeit vom Health Connect SDK in der Datei build.gradle auf Modulebene hinzu:

dependencies {
  ...
  implementation "androidx.health.connect:connect-client:1.1.0-alph10"
  ...
}

Die neueste Version finden Sie in den Health Connect-Releases.

Schritt 3: App konfigurieren

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

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 stärken.

Deklarieren Sie in Ihrer App in der Datei AndroidManifest.xml Lese- und Schreibberechtigungen für die erforderlichen Datentypen. Diese sollten mit den Datentypen übereinstimmen, für die Sie in der Play Console den Zugriff erklärt haben.

Health Connect verwendet das Standardformat für die Erklärung von Berechtigungen unter Android. Weisen Sie Berechtigungen mit den <uses-permission>-Tags zu. Ordnen Sie sie den <manifest>-Tags zu.

<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 zugehörigen 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 erläutert, warum die angeforderten Berechtigungen erforderlich sind und 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 Bildschirm mit den Health Connect-Berechtigungen 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 erhalten

HealthConnectClient ist ein Einstiegspunkt in die Health Connect API. So kann die App den Datenspeicher in der Health Connect App verwenden. Außerdem wird die Verbindung zur zugrunde liegenden Speicherebene automatisch verwaltet und alle IPC- und Serialization-Vorgänge für ausgehende Anfragen und eingehende Antworten werden abgedeckt.

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 installiert ist. Verwenden Sie dazu die Taste getSdkStatus. Wenn ja, rufe 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 Clientinstanz erstellt haben, muss Ihre App vom Nutzer Berechtigungen 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 Ihre App bereits die erforderlichen Berechtigungen hat. Andernfalls kannst du mit createRequestPermissionResultContract diese Berechtigungen anfordern. Daraufhin wird der Bildschirm mit den Health Connect-Berechtigungen 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)
  }
}

Gehen Sie nicht davon aus, dass Berechtigungen konstant sind, da Nutzer sie jederzeit gewähren oder widerrufen können. Ihre App muss regelmäßig prüfen, ob Berechtigungen erteilt wurden, und mit Szenarien umgehen, in denen die Berechtigung verloren geht.

Schritt 5: Vorgänge ausführen

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

Daten schreiben

Strukturieren Sie Ihre Daten in einem Datensatz. 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 den Datensatz mit insertRecords auf.

suspend fun insertSteps(healthConnectClient: HealthConnectClient) {
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = START_TIME,
            endTime = END_TIME,
            startZoneOffset = START_ZONE_OFFSET,
            endZoneOffset = END_ZONE_OFFSET,
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling here
    }
}

Daten lesen

Mit readRecords können Sie Ihre Daten einzeln lesen.

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

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

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 erfahren Sie mehr über die Health Connect-Funktionen und Best Practices für eine reibungslose Integration:

Ressourcen

Die folgenden Ressourcen helfen Ihnen bei der späteren Entwicklung:

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:Sehen Sie sich die Jetpack-Referenz für die Health Connect API an.
Verwendung von Datentypen erklären:Deklarieren Sie in der Play Console den Zugriff auf die Health Connect-Datentypen, aus denen Ihre App Daten liest und in die sie schreibt.
Optionales GitHub-Codebeispiel und Codelab:Im GitHub-Repository mit Codebeispielen und in der Codelab-Übung finden Sie Informationen für den Einstieg.

Nächste Schritte

Unter Gängige Workflows erfahren Sie, wie Sie in Health Connect beispielsweise folgende Aktionen ausführen: