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. 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 beschrieben, 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 niedrigeren Versionen 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 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-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 beschrieben, 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 ihre Version von Health Connect möglicherweise nicht immer. Mit der Feature Availability API können Sie prüfen, ob eine Funktion in Health Connect auf dem Gerät Ihres Nutzers verfügbar ist, und entscheiden, welche Maßnahmen Sie ergreifen möchten.

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

if (healthConnectClient
     .features
     .getFeatureStatus(
       HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_IN_BACKGROUND
     ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE) {

  // Feature is available
  ...
} else {
  // Feature is not available
  ...
}

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 den Zugriff deklariert haben.

Health Connect verwendet das Standardformat für die Deklaration 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 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 Paketnamen von Health Connect 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, 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 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 widerrufen können, muss Ihre App jedes Mal vor der Verwendung von Berechtigungen prüfen, ob sie vorhanden sind, und Szenarien verarbeiten, in denen Berechtigungen verloren gehen.

Nutzer einarbeiten

Viele Apps haben einen benutzerdefinierten Onboarding-Prozess, z. B. zur Erläuterung von Funktionen oder zur Einholung der Nutzereinwilligung. 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 Daten in Health Connect geschrieben werden, können Sie mit der Matchmaking API diese Apps nahtlos für Ihre Nutzer verbinden.

Daten schreiben

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

val stepsRecord = StepsRecord(
    count = 120,
    startTime = START_TIME,
    endTime = END_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endZoneOffset = END_ZONE_OFFSET,
)

Schreiben Sie dann Ihren Eintrag 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

Sie können Ihre Daten einzeln mit readRecords 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 Funktionen von Health Connect sowie über Best Practices für eine reibungslose Einbindung:

Ressourcen

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

  • Health Connect SDK (verfügbar in Jetpack): Binden 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.: