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.

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. Zu diesen Anfragen 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 der Umgang mit einigen aktuellen Android-Versionen beschrieben.

Android 14

Ab Android 14 (API-Level 34) ist Health Connect Teil des Android-Frameworks. Diese Version von Health Connect ist ein Framework-Modul. Eine Einrichtung ist also nicht 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 in Health Connect eingebunden haben und unter Android 14 migrieren möchten, lesen Sie Von Android 13 zu Android 14 migrieren.

Öffne die Health Connect App

Health Connect wird nicht mehr standardmäßig auf dem Startbildschirm angezeigt. Rufe zum Öffnen von Health Connect Einstellungen > Apps > Health Connect auf oder füge Health Connect zum Menü Schnelleinstellungen hinzu.

Außerdem muss der Nutzer bei Health Connect die Displaysperre mit einer PIN, einem Muster oder einem Passwort aktivieren, damit die in Health Connect gespeicherten Gesundheitsdaten vor böswilligen Parteien geschützt sind, während das Gerät gesperrt ist. Rufen Sie zum Einrichten einer Displaysperre Einstellungen > Sicherheit > Displaysperre auf.

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

Das Health Connect SDK ist für die Verwendung der Health Connect API zum Senden von Anfragen beim Ausführen von Vorgängen an den Datenspeicher in der Health Connect App verantwortlich.

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.1.0-alpha02"
  ...
}

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

Schritt 3: App konfigurieren

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

Deklarieren von Berechtigungen

Der Zugriff auf Gesundheits- und Fitnessdaten ist sensibel. Health Connect implementiert eine Sicherheitsebene für Lese- und Schreibvorgänge und hält das Vertrauen der Nutzer aufrecht.

Deklarieren Sie Lese- und Schreibberechtigungen für die Datei AndroidManifest.xml anhand der erforderlichen Datentypen. Achten Sie darauf, dass Sie die Berechtigungen verwenden, für die Sie Zugriff angefordert haben, nachdem Sie das Formular ausgefüllt haben.

Health Connect verwendet das Standardformat für die Erklärung von Android-Berechtigungen. 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 zugehörigen Datentypen finden Sie unter Liste der Datentypen.

Dialogfeld mit der Datenschutzerklärung deiner App anzeigen

Ihr Android-Manifest muss eine Activity enthalten, in der die Datenschutzerklärung Ihrer App angezeigt wird. Diese Erklärung dient dazu, die angeforderten Berechtigungen durch Ihre App zu begründen. Darin wird beschrieben, wie die Daten des Nutzers verwendet und verarbeitet werden.

Deklariere diese Aktivität zur Verarbeitung des ACTION_SHOW_PERMISSIONS_RATIONALE-Intents, wenn sie an die App gesendet wird, wenn der Nutzer auf dem Berechtigungsbildschirm von Health Connect 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 zur Health Connect API. Sie ermöglicht der Anwendung, den Datenspeicher in der Health Connect-Anwendung zu verwenden. Sie verwaltet automatisch ihre Verbindung zur zugrunde liegenden Speicherebene und verarbeitet die gesamte IPC und Serialisierung von ausgehenden Anfragen und eingehenden Antworten.

Um eine Clientinstanz zu erhalten, 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 unter „Aktivität“ mit getSdkStatus, ob Health Connect installiert ist. Falls 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 Clientinstanz erstellt haben, muss Ihre Anwendung vom Nutzer Berechtigungen anfordern. Nutzer müssen jederzeit berechtigt sein, Berechtigungen zu erteilen oder zu verweigern.

Dazu erstellen Sie eine Reihe von Berechtigungen für die erforderlichen Datentypen. Achten Sie darauf, dass die Berechtigungen in diesem Satz zuerst in Ihrem Android-Manifest deklariert sind.

// 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 gewährt wurden. Andernfalls verwenden Sie createRequestPermissionResultContract, um diese Berechtigungen anzufordern. Der Health Connect-Berechtigungsbildschirm 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)
  }
}

Sie sollten nicht davon ausgehen, dass Berechtigungen konstant sind, da Nutzer sie jederzeit gewähren oder widerrufen können. Ihre App muss regelmäßig nach gewährten Berechtigungen suchen und Szenarien verarbeiten, in denen Berechtigungen verloren gehen.

Schritt 5: Vorgänge ausführen

Jetzt, da alles eingerichtet ist, können Sie Lese- und Schreibvorgänge in Ihrer Anwendung 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 den Eintrag mit insertRecords.

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

Mit aggregate können Sie Ihre Daten auch in aggregierter Form 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 Funktionen von Health Connect sowie Best Practices für eine reibungslose Integration näher erläutert:

Ressourcen

Die folgenden Ressourcen helfen Ihnen später bei der Entwicklung.

Health Connect SDK (auf Jetpack verfügbar): Binde dieses SDK in deine Anwendung ein, um die Health Connect API zu verwenden.
API-Referenz: Sehen Sie sich die Jetpack-Referenz für die Health Connect API an.
Formular zur Erklärung von API-Anfragen für Entwickler:Verwenden Sie dieses Formular, um Zugriff zum Lesen und Schreiben von Datentypen zu beantragen. Weitere Informationen finden Sie unter Zugriff auf Health Connect-Datentypen anfordern.
Optionales GitHub-Codebeispiel und Codelab: Das GitHub-Codebeispiel-Repository und die Codelab-Übung erleichtern den Einstieg.

Nächste Schritte

Unter Allgemeine Workflows erfahren Sie, wie Sie in Health Connect Vorgänge wie die folgenden durchführen: