Diese Seite wurde von der Cloud Translation API übersetzt.

Erste Schritte mit Health Connect

In diesem Leitfaden erfährst du, wie du Health Connect in deiner App verwenden kannst.

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 musst du die Health Connect-App aus dem Google Play Store installieren.

Wenn du deine App unter Android 13 und niedriger in Health Connect eingebunden hast und zu Android 14 migrieren möchtest, lies dir den Artikel Von Android 13 zu 14 migrieren durch.

Ö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 für Health Connect die Displaysperre mit einer PIN, einem Muster oder einem Passwort aktiviert haben, damit die in Health Connect gespeicherten Gesundheitsdaten vor böswilligen Parteien geschützt werden, während das Gerät gesperrt ist. Rufen Sie Einstellungen > Sicherheit > Displaysperre auf, um eine Displaysperre einzurichten.

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 Health Connect SDK-Abhängigkeit in die Datei build.gradle auf Modulebene ein:

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

Die aktuelle 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.

Erklären Sie in der Play Console den Zugriff auf die Health Connect-Datentypen, aus denen Ihre App liest und in die sie schreibt.

Deklariere in deiner App Lese- und Schreibberechtigungen in der Datei AndroidManifest.xml basierend auf den erforderlichen Datentypen, die denjenigen entsprechen, für die du in der Play Console den Zugriff erklärt hast.

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 die Begründung für die angeforderten Berechtigungen Ihrer App erläutert und beschrieben, wie die Daten der Nutzer verwendet und verarbeitet werden.

Deklarieren Sie diese Aktivität für den Intent ACTION_SHOW_PERMISSIONS_RATIONALE, an den sie 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 erhalten

HealthConnectClient ist ein Einstiegspunkt in die Health Connect API. Damit kann die Anwendung den Datenspeicher in der Health Connect-Anwendung verwenden. Sie verwaltet automatisch die Verbindung zur zugrunde liegenden Speicherebene und verarbeitet alle IPC und Serialisierung von ausgehenden Anfragen und eingehenden Antworten.

Um eine Clientinstanz abzurufen, musst du zuerst den Namen des Health Connect-Pakets 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 Ihren Aktivitäten, ob Health Connect installiert ist. Verwenden Sie dazu die Taste getSdkStatus. 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 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.
    }
}

Mit aggregate können Sie Ihre Daten auch aggregiert 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 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: Sehen Sie sich zum Einstieg das GitHub-Codebeispiel-Repository und die Codelab-Übung an.

Nächste Schritte

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