Erste Schritte mit Health Connect

Diese Anleitung ist mit Health Connect-Version 1.1.0-alpha12 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. 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 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 in Health Connect integriert haben und zu Android 14 migrieren möchten, lesen Sie den Abschnitt Von Android 13 zu Android 14 migrieren.

Health Connect App öffnen

Health Connect wird standardmäßig nicht mehr auf dem Startbildschirm angezeigt. Um Health Connect zu öffnen, gehe zu Einstellungen > Apps > Health Connect oder füge Health Connect den Schnelleinstellungen hinzu.

Außerdem muss der Nutzer für Health Connect eine Displaysperre mit einer PIN, einem Entsperrungsmuster oder einem Passwort aktiviert haben, damit die in Health Connect gespeicherten Gesundheitsdaten geschützt sind, wenn das Gerät gesperrt ist. Wenn Sie eine Displaysperre einrichten möchten, gehen Sie zu Einstellungen > Sicherheit > Displaysperre.

Schritt 2: Health Connect SDK in Ihre App einfügen

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

Die aktuelle Version finden Sie unter Health Connect-Releases.

Schritt 3: App konfigurieren

In den folgenden Abschnitten wird beschrieben, wie Sie Ihre App für die Integration 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 wahren.

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

Health Connect verwendet das Standardformat für die Android-Berechtigungserklärung. Weisen Sie Berechtigungen mit den <uses-permission>-Tags zu. Schließen Sie sie in die <manifest>-Tags ein.

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

HealthConnectClient ist ein Einstiegspunkt für die Health Connect API. So 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 übernommen.

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 mit getSdkStatus installiert wurde. 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 Client-Instanz erstellt haben, muss Ihre App Berechtigungen vom Nutzer anfordern. Nutzer müssen jederzeit die Möglichkeit haben, Berechtigungen zu erteilen oder zu verweigern.

Erstellen Sie dazu eine Reihe von Berechtigungen für die erforderlichen Datentypen. Die Berechtigungen im Set müssen 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. Falls nicht, verwenden Sie createRequestPermissionResultContract, um diese Berechtigungen anzufordern. Der Bildschirm mit den Health Connect-Berechtigungen 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)
  }
}

Da Nutzer Berechtigungen jederzeit erteilen oder widerrufen können, muss Ihre App regelmäßig prüfen, welche Berechtigungen erteilt wurden, und Szenarien berücksichtigen, in denen Berechtigungen verloren gehen.

Schritt 5: Vorgänge ausführen

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

Daten schreiben

Strukturieren Sie Ihre Daten in einem Datensatz. Hier finden Sie 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 Ihren Datensatz mit insertRecords.

suspend fun insertSteps(healthConnectClient: HealthConnectClient) {
    val endTime = Instant.now()
    val startTime = endTime.minus(Duration.ofMinutes(15))
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = startTime,
            endTime = endTime,
            startZoneOffset = ZoneOffset.UTC,
            endZoneOffset = ZoneOffset.UTC,
            metadata = Metadata.autoRecorded(
                device = Device(type = Device.TYPE_WATCH)
            ),
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling here
    }
}

Daten lesen

Mit readRecords können Sie Ihre Daten einzeln lesen.

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

Sie können Ihre Daten auch aggregiert mit aggregate 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 erhalten Best Practices für eine reibungslose Integration:

Ressourcen

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

Nächste Schritte

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