Schritte zählen

Health Connect bietet den Datentyp Schritte zum Aufzeichnen von Schrittzahlen mit dem StepsRecord. Schritte sind eine grundlegende Messung beim Gesundheits- und Fitnesstracking.

Schritte auf dem Smartphone lesen

Unter Android 14 (API-Level 34) und SDK-Erweiterung Version 20 oder höher bietet Health Connect eine Schrittzählung auf dem Gerät. Wenn einer App die Berechtigung READ_STEPS erteilt wurde, erfasst Health Connect Schritte vom Android-Gerät und Nutzer sehen automatisch hinzugefügte Schrittdaten in den Health Connect-Einträgen unter Schritte.

Wenn Sie prüfen möchten, ob die Schrittzählung auf dem Gerät verfügbar ist, müssen Sie prüfen, ob auf dem Gerät Android 14 (API-Level 34) ausgeführt wird und es mindestens die SDK-Erweiterungsversion 20 hat. Sie können den folgenden Code verwenden:

val isStepTrackingAvailable =
    Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE &&
        SdkExtensions.getExtensionVersion(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) >= 20

Für von Health Connect erfasste Schritte auf dem Smartphone ist DataOrigin auf den Paketnamen android festgelegt. Wenn Ihre App nur aggregierte Schrittzahlen mit aggregate liest und nicht nach DataOrigin filtert, werden die Schritte auf dem Gerät automatisch in die Gesamtzahl einbezogen.

Wenn Ihre App Schritte auf dem Gerät lesen muss oder Schrittdaten nach Quellanwendung oder Gerät aufgeschlüsselt anzeigt, können Sie Datensätze abfragen, bei denen DataOrigin gleich android ist. Wenn in Ihrer App die Attribution für Schrittdaten angezeigt wird, sollten Sie Daten aus dem Android-Paket dem aktuellen Gerät zuordnen. Dazu können Sie ein Label wie „Mein Smartphone“ verwenden, den Gerätenamen mit Settings.Global.getString(resolver, Settings.Global.DEVICE_NAME) abrufen oder das Feld Device in den Metadaten des Datensatzes prüfen.

Im folgenden Beispiel wird gezeigt, wie aggregierte Daten zur Anzahl der Schritte auf Mobilgeräten gelesen werden, indem nach dem Datenursprung android gefiltert wird:

suspend fun readStepsByTimeRange(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    try {
        val response = healthConnectClient.aggregate(
            AggregateRequest(
                metrics = setOf(StepsRecord.COUNT_TOTAL),
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
                dataOriginFilter = setOf(DataOrigin("android"))
            )
        )
        // 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
    }
}

Schrittzählung auf dem Gerät

Weitere Informationen zur Funktion zum Zählen von Schritten auf dem Gerät:

  • Sensornutzung: Health Connect verwendet den Sensor TYPE_STEP_COUNTER von SensorManager. Dieser Sensor ist für einen geringen Stromverbrauch optimiert und eignet sich daher ideal für die kontinuierliche Schrittzählung im Hintergrund.
  • Datengranularität: Um den Akku zu schonen, werden Schrittdaten in der Regel in Batches zusammengefasst und höchstens einmal pro Minute in die Health Connect-Datenbank geschrieben.
  • Attribution: Wie bereits erwähnt, werden alle von dieser On-Device-Funktion aufgezeichneten Schritte dem Paketnamen android im DataOrigin zugeordnet.
  • Aktivierung: Der Mechanismus zur Schrittzählung auf dem Gerät ist nur aktiv, wenn mindestens einer Anwendung auf dem Gerät die Berechtigung READ_STEPS in Health Connect erteilt wurde.

Verfügbarkeit von Health Connect prüfen

Bevor Ihre App versucht, Health Connect zu verwenden, sollte sie prüfen, ob Health Connect auf dem Gerät des Nutzers verfügbar ist. Health Connect ist möglicherweise nicht auf allen Geräten vorinstalliert oder deaktiviert. Sie können die Verfügbarkeit mit der Methode HealthConnectClient.getSdkStatus() prüfen.

Verfügbarkeit von Health Connect prüfen

fun checkHealthConnectAvailability(context: Context) {
    val providerPackageName = "com.google.android.apps.healthdata" // Or get from HealthConnectClient.DEFAULT_PROVIDER_PACKAGE_NAME
    val availabilityStatus = HealthConnectClient.getSdkStatus(context, providerPackageName)

    if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
      // Health Connect is not available. Guide the user to install/enable it.
      // For example, show a dialog.
      return // early return as there is no viable integration
    }
    if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE_PROVIDER_UPDATE_REQUIRED) {
      // Health Connect is available but requires an update.
      // 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
    }
    // Health Connect is available, obtain a HealthConnectClient instance
    val healthConnectClient = HealthConnectClient.getOrCreate(context)
    // Issue operations with healthConnectClient
}

Je nach dem von getSdkStatus() zurückgegebenen Status können Sie den Nutzer bei Bedarf anleiten, Health Connect aus dem Google Play Store zu installieren oder zu aktualisieren.

Erforderliche Berechtigungen

Der Zugriff auf Schritte wird durch die folgenden Berechtigungen geschützt:

  • android.permission.health.READ_STEPS
  • android.permission.health.WRITE_STEPS

Wenn Sie Ihrer App die Möglichkeit zum Aufzeichnen von Schritten hinzufügen möchten, müssen Sie zuerst Schreibberechtigungen für den Datentyp Steps anfordern.

Hier ist die Berechtigung, die Sie deklarieren müssen, um „Schritte“ schreiben zu können:

<application>
  <uses-permission
android:name="android.permission.health.WRITE_STEPS" />
...
</application>

Wenn Sie Schritte lesen möchten, müssen Sie die folgenden Berechtigungen anfordern:

<application>
  <uses-permission
android:name="android.permission.health.READ_STEPS" />
...
</application>

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

In einem Schrittaufzeichnungsdatensatz enthaltene Informationen

Jeder StepsRecord-Eintrag enthält die folgenden Informationen:

  • count: Die Anzahl der Schritte, die im Zeitintervall ausgeführt wurden, als Long.
  • startTime: Die Startzeit des Messzeitraums.
  • endTime: Die Endzeit des Messzeitraums.
  • startZoneOffset: Die Zonenabweichung für die Startzeit.
  • endZoneOffset: Die Zeitzonenabweichung für die Endzeit.

Unterstützte Aggregationen

Die folgenden aggregierten Werte sind für StepsRecord verfügbar:

Die folgenden aggregierten Werte sind für StepsCadenceRecord verfügbar:

Beispiel für die Verwendung

In den folgenden Abschnitten wird beschrieben, wie StepsRecord-Daten gelesen und geschrieben werden.

Schrittdaten schreiben

Ihre App kann Schrittzahldaten schreiben, indem sie StepsRecord-Instanzen einfügt. Das folgende Beispiel zeigt, wie 1.000 Schritte eines Nutzers aufgezeichnet werden:

suspend fun writeStepsData(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant,
    startZoneOffset: ZoneOffset,
    endZoneOffset: ZoneOffset
) {
    try {
        val stepsRecord = StepsRecord(
            startTime = startTime,
            startZoneOffset = startZoneOffset,
            endTime = endTime,
            endZoneOffset = endZoneOffset,
            count = 1000
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling
    }
}

Aggregierte Daten lesen

Die gängigste Methode zum Lesen von Schrittdaten ist die Aggregation der Gesamtzahl der Schritte über einen Zeitraum. Das folgende Beispiel zeigt, wie die Gesamtzahl der Schritte für einen Nutzer in einem bestimmten Zeitraum gelesen wird:

suspend fun readStepsAggregate(
    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
    }
}

Rohdaten lesen

Im folgenden Beispiel wird gezeigt, wie Sie StepsRecord-Rohdaten zwischen einer Start- und einer Endzeit lesen:

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