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, beginnt Health Connect mit der Erfassung von Schritten auf dem Android-Gerät. Nutzer sehen dann automatisch Schrittdaten, die den Schritt-Einträgen in Health Connect hinzugefügt wurden.

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 Schritte, die von Health Connect erfasst werden, 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 Quellenangabe 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.

Das folgende Beispiel zeigt, 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 wurde 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 Erfassen von Schritten hinzufügen möchten, müssen Sie zuerst Berechtigungen 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>

Zum Lesen von Schritten 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 jedes Mal prüfen, ob die Berechtigungen vorhanden sind, bevor sie verwendet werden. Außerdem muss sie Szenarien berücksichtigen, in denen Berechtigungen verloren gehen.

In einem Schritt-Datensatz 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

Für StepsRecord sind die folgenden aggregierten Werte verfügbar:

Für StepsCadenceRecord sind die folgenden aggregierten Werte verfügbar:

Beispiel

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