Schritte zählen

Health Connect bietet den Datentyp Schritte zum Aufzeichnen von Schrittzahlen mit dem StepsRecord. Schritte sind ein wichtiger Messwert 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 Health Connect-Einträgen Schritte hinzugefügt wurden.

So prüfen Sie, ob die Schrittzählung auf dem Gerät verfügbar ist: Das Gerät muss Android 14 (API-Level 34) ausführen und mindestens SDK-Erweiterungsversion 20 haben:

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

Wenn Ihre App aggregierte Schrittzahlen mit aggregate liest und nicht nach DataOrigin filtert, werden die Schritte auf dem Gerät automatisch in die Gesamtzahl einbezogen. Für das Update im Juni 2026 sind keine Änderungen erforderlich.

Änderung der Attribution für Schritte auf dem Gerät

Ab dem Update vom Juni 2026 werden Schritte, die nativ von Health Connect erfasst werden, einem synthetischen Paketnamen (SPN) wie com.android.healthconnect.phone.jd5bdd37e1a8d3667a05d0abebfc4a89e zugewiesen.

Bisher wurden integrierte Schritte dem Paketnamen android zugeordnet. Bei Verlaufsdaten zu Schritten, die vor Juni 2026 aufgezeichnet wurden, wird der Paketname android beibehalten.

SPNs sind gerätespezifisch und werden pro Anwendung festgelegt, um den Datenschutz der Nutzer zu gewährleisten:

• Stabil:Der SPN für das aktuelle Gerät ist für Ihre Anwendung stabil.
• Anwendungsspezifisch:Verschiedene Anwendungen auf demselben Gerät sehen unterschiedliche SPNs für Schrittdaten auf dem Gerät.

Nach Schritten auf dem Gerät suchen

Da SPNs bereichsbezogen und gerätespezifisch sind, dürfen Sie SPN-Werte nicht fest codieren. Verwenden Sie stattdessen die getCurrentDeviceDataSource() API, um die SPN für das aktuelle Gerät abzurufen.

Für die Schrittzählung auf dem Gerät ist die SDK-Erweiterungsversion 20 oder höher erforderlich. Die getCurrentDeviceDataSource() API ist jedoch unter Android 14 (API-Level 34) mit der SDK-Erweiterungsversion 11 oder höher verfügbar.

Die getCurrentDeviceDataSource() API ist noch nicht in der Health Connect Jetpack-Bibliothek verfügbar. In den folgenden Beispielen wird stattdessen die Android-Framework-API verwendet:

import android.content.Context
import android.health.connect.HealthConnectManager

val healthConnectManager = context.getSystemService(HealthConnectManager::class.java)
val deviceDataSource = healthConnectManager?.getCurrentDeviceDataSource()
val currentDeviceSpn = deviceDataSource?.deviceDataOrigin?.packageName

Wenn Ihre App Schritte auf dem Gerät lesen muss oder Schrittdaten nach Quellanwendung oder Gerät aufgeschlüsselt anzeigt, müssen Sie Datensätze abfragen, bei denen DataOrigin android oder dem SPN des Geräts entspricht. Wenn in Ihrer App die Quellenangabe für Schrittdaten angezeigt wird, verwenden Sie metadata.device, um das Quellgerät für einzelne Datensätze zu identifizieren. Für On-Device-Schritte, die in aggregierten Daten durch einen SPN identifiziert werden, können Sie Gerätemetadaten wie model oder manufacturer aus DeviceDataSource für die Zuordnung verwenden oder ein generisches Label wie „Ihr Smartphone“ für On-Device-Schritte verwenden.

Das folgende Beispiel zeigt, wie aggregierte On-Device-Schrittzahl-Daten gelesen werden, indem sowohl nach android als auch nach dem aktuellen Geräte-SPN gefiltert wird:

import android.content.Context
import android.health.connect.HealthConnectManager
import android.os.Build
import android.os.ext.SdkExtensions
import androidx.health.connect.client.HealthConnectClient
import androidx.health.connect.client.records.StepsRecord
import androidx.health.connect.client.records.metadata.DataOrigin
import androidx.health.connect.client.request.AggregateRequest
import androidx.health.connect.client.time.TimeRangeFilter
import java.time.Instant

suspend fun readDeviceStepsByTimeRange(
    healthConnectClient: HealthConnectClient,
    context: Context,
    startTime: Instant,
    endTime: Instant
) {
    // 1. Check if SDK Extension 11+ is available for getCurrentDeviceDataSource()
    val isDataSourceApiAvailable = Build.VERSION.SDK_INT >= Build.VERSION_CODES.U &&
            SdkExtensions.getExtensionVersion(Build.VERSION_CODES.U) >= 11

    try {
        val healthConnectManager = context.getSystemService(HealthConnectManager::class.java)

        // 2. Safely fetch the package name only if API is available and data exists
        val currentDeviceSpn = if (isDataSourceApiAvailable) {
            healthConnectManager?.getCurrentDeviceDataSource()?.deviceDataOrigin?.packageName
        } else {
            null
        }

        val dataOriginFilters = mutableSetOf(DataOrigin("android"))

        // 3. Explicit null-safety check using .let
        currentDeviceSpn?.let {
            dataOriginFilters.add(DataOrigin(it))
        }

        val response = healthConnectClient.aggregate(
            AggregateRequest(
                metrics = setOf(StepsRecord.COUNT_TOTAL),
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
                dataOriginFilter = dataOriginFilters
            )
        )

        val stepCount = response[StepsRecord.COUNT_TOTAL]

    } catch (e: Exception) {
        // Now this catch block only handles actual runtime exceptions, 
        // rather than Errors from missing methods.
    }
}

Schrittzählung 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: Schritte, die vor Juni 2026 mit dieser Funktion aufgezeichnet wurden, werden in der DataOrigin dem Paketnamen android zugeordnet. Danach werden sie einem gerätespezifischen SPN zugeordnet. Weitere Informationen finden Sie unter Änderung der Zuordnung für Schritte auf dem Gerät.
• 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.

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

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

• COUNT_TOTAL

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

• RATE_AVG
• RATE_MAX
• RATE_MIN

Nutzungsbeispiel

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:

val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(startTime)
val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = zoneOffset,
    endZoneOffset = zoneOffset,
    metadata = Metadata(
        device = Device(type = Device.TYPE_WATCH),
        recordingMethod = Metadata.RECORDING_METHOD_AUTOMATICALLY_RECORDED
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))
HealthConnectManager.kt

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 Gesamtschrittzahl für einen Nutzer in einem bestimmten Zeitraum gelesen wird:

suspend fun readStepsAggregate(startTime: Instant, endTime: Instant): Long {
    val response = healthConnectClient.aggregate(
        AggregateRequest(
            metrics = setOf(StepsRecord.COUNT_TOTAL),
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
        )
    )
    return response[StepsRecord.COUNT_TOTAL] ?: 0L
}
HealthConnectManager.kt

Rohdaten lesen

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

val response = healthConnectClient.readRecords(
    ReadRecordsRequest(
        StepsRecord::class,
        timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
    )
)
response.records.forEach { record ->
    /* Process records */
}
HealthConnectManager.kt