Schritte zählen

Health Connect bietet den Datentyp Schritte, um die Schrittzahl mit dem StepsRecord aufzuzeichnen. Schritte sind ein grundlegender Messwert beim Gesundheits- und Fitnesstracking.

Diese Anleitung ist mit Health Connect-Version 1.1.0-alpha12 oder höher kompatibel.

Schritte auf Mobilgeräten lesen

Mit Android 14 (API-Level 34) und SDK-Erweiterung ab Version 20 bietet Health Connect eine Schrittzählung auf dem Gerät. Wenn einer App die Berechtigung READ_STEPS gewährt wurde, beginnt Health Connect mit der Erfassung von Schritten auf dem Android-Gerät. Nutzer sehen dann, dass die Schrittdaten automatisch den Health Connect-Einträgen Schritte hinzugefügt werden.

Wenn du prüfen möchtest, ob die Schrittzählung auf dem Gerät verfügbar ist, muss auf dem Gerät Android 14 (API-Level 34) und mindestens die SDK-Erweiterungsversion 20 ausgeführt werden:

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 auf dem Gerät gezählten Schritte automatisch in die Gesamtzahl einbezogen. Für das Update im Juni 2026 sind dann keine Änderungen erforderlich.

Änderung der Zuordnung 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 zugeordnet.

Zuvor wurden integrierte Schritte dem Paketnamen android zugeordnet. Für vor Juni 2026 aufgezeichnete Verlaufsdaten zu Schritten wird der Paketname android beibehalten.

SPNs sind gerätespezifisch und werden pro App festgelegt, um den Datenschutz der Nutzer zu schützen:

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

Abfrage von Schritten auf dem Gerät

Da SPNs bereichs- und gerätespezifisch sind, dürfen Sie SPN-Werte nicht hartcodieren. Verwenden Sie stattdessen die getCurrentDeviceDataSource API, um den SPN für das aktuelle Gerät abzurufen.

Für die Schrittzählung auf dem Gerät ist die SDK-Erweiterung ab Version 20 erforderlich. Die getCurrentDeviceDataSource() API ist unter Android 14 (API-Level 34) mit der SDK-Erweiterung ab Version 22 verfügbar. Wenn Sie diese API verwenden möchten, setzen Sie compileSdkExtension in der Datei build.gradle.kts oder build.gradle auf Modulebene auf 22 oder höher:

Kotlin

android {
    compileSdk = 35
    compileSdkExtension = 22
}

Groovy

android {
    compileSdk 35
    compileSdkExtension 22
}

Die getCurrentDeviceDataSource() API ist in der Health Connect Jetpack-Bibliothek noch nicht verfügbar. In den folgenden Beispielen wird die Android Framework API verwendet, für die ein Executor- und ein OutcomeReceiver-Callback erforderlich sind:

import android.content.Context
import android.health.connect.DeviceDataSource
import android.health.connect.HealthConnectException
import android.health.connect.HealthConnectManager
import android.os.OutcomeReceiver

val healthConnectManager = context.getSystemService(HealthConnectManager::class.java)
healthConnectManager?.getCurrentDeviceDataSource(
    context.mainExecutor,
    object : OutcomeReceiver<DeviceDataSource, HealthConnectException> {
        override fun onResult(result: DeviceDataSource) {
            val currentDeviceSpn = result.deviceDataOrigin.packageName
        }

        override fun onError(error: HealthConnectException) {
            // Handle error
        }
    }
)

Wenn deine App auf dem Gerät gespeicherte Schritte lesen muss oder wenn sie Schrittdaten nach Quellanwendung oder Gerät aufgeschlüsselt anzeigt, musst du Datensätze abfragen, bei denen der DataOrigin android ist oder mit dem SPN des Geräts übereinstimmt. Wenn in deiner App die Zuordnung für Schrittdaten angezeigt wird, verwende metadata.device, um das Quellgerät für einzelne Datensätze zu identifizieren. Für On-Device-Schritte, die durch einen SPN in aggregierten Daten 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.

Im folgenden Beispiel wird gezeigt, wie aggregierte Schrittzahldaten auf dem Gerät gelesen werden, indem sowohl nach android als auch nach dem SPN des aktuellen Geräts gefiltert wird:

import android.content.Context
import android.health.connect.DeviceDataSource
import android.health.connect.HealthConnectException
import android.health.connect.HealthConnectManager
import android.os.Build
import android.os.OutcomeReceiver
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
import kotlin.coroutines.resume
import kotlin.coroutines.resumeWithException
import kotlinx.coroutines.suspendCancellableCoroutine

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

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

        // 2. Safely fetch the package name only if the API is available
        val currentDeviceSpn = if (isDataSourceApiAvailable && healthConnectManager != null) {
            suspendCancellableCoroutine { continuation ->
                healthConnectManager.getCurrentDeviceDataSource(
                    context.mainExecutor,
                    object : OutcomeReceiver<DeviceDataSource, HealthConnectException> {
                        override fun onResult(result: DeviceDataSource) {
                            continuation.resume(result.deviceDataOrigin.packageName)
                        }

                        override fun onError(error: HealthConnectException) {
                            continuation.resumeWithException(error)
                        }
                    }
                )
            }
        } 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 Schrittaufzeichnung im Hintergrund.
  • Datengranularität: Um den Akku zu schonen, werden Schrittdaten in der Regel im Batchmodus und nicht häufiger als einmal pro Minute in die Health Connect-Datenbank geschrieben.
  • Attribution: Schritte, die vor Juni 2026 mit dieser Funktion aufgezeichnet wurden, werden dem Paketnamen android in der DataOrigin zugeordnet. Nach diesem Datum werden sie einer gerätespezifischen SPN zugeordnet. Weitere Informationen finden Sie unter Attributionsänderung für Schritte auf dem Gerät.
  • Aktivierung: Der Schrittzählmechanismus auf dem Gerät ist nur aktiv, wenn mindestens einer Anwendung auf dem Gerät die Berechtigung READ_STEPS in Health Connect gewährt wurde.

Verfügbarkeit von Health Connect prüfen

Bevor du versuchst, Health Connect zu verwenden, sollte deine App 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"
    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 kannst du 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 Funktion 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>

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 Clientinstanz erstellt haben, muss Ihre App Berechtigungen vom Nutzer anfordern. Nutzer müssen Berechtigungen jederzeit erteilen oder verweigern können. Erstellen Sie dazu eine Reihe von Berechtigungen für die erforderlichen Datentypen. Achte darauf, dass die Berechtigungen in der Gruppe zuerst in deinem Android-Manifest deklariert werden. 

val permissions =
    setOf(
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class)
    )
 Mit getGrantedPermissions kannst du prüfen, ob deiner App bereits die erforderlichen Berechtigungen gewährt wurden. Falls nicht, verwenden Sie createRequestPermissionResultContract, um diese Berechtigungen anzufordern. Der Bildschirm mit den Health Connect-Berechtigungen wird angezeigt. 
val permissions = setOf(
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class)
    )

val requestPermissionsLauncher = rememberLauncherForActivityResult(
    contract = PermissionController.createRequestPermissionResultContract()
) { grantedPermissions ->
    if (grantedPermissions.containsAll(permissions)) {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions granted!") }
    } else {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions denied.") }
    }
}
 Da Nutzer Berechtigungen jederzeit erteilen oder widerrufen können, muss deine App vor jeder Verwendung prüfen, ob die Berechtigungen vorhanden sind, und Szenarien verarbeiten, in denen die Berechtigung verloren geht.

In einem Schrittdatensatz enthaltene Informationen

Jede StepsRecord enthält die folgenden Informationen:

  • count: Die Anzahl der Schritte im Zeitintervall als Long.
  • startTime: Der Beginn des Messintervalls.
  • endTime: Das Ende des Messintervalls.
  • startZoneOffset: Die Zeitzonenverschiebung für den Beginn.
  • endZoneOffset: Die Zonenverschiebung 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:

Nutzungsbeispiel

In den folgenden Abschnitten wird beschrieben, wie Sie StepsRecord-Daten lesen und schreiben.

Schrittdaten schreiben

Ihre App kann Schrittzahldaten schreiben, indem sie StepsRecord-Instanzen einfügt. Im folgenden Beispiel wird gezeigt, 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.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    )
)
healthConnectClient.insertRecords(listOf(stepsRecord))

Aggregierte Daten lesen

Die gängigste Methode zum Lesen von Schrittdaten ist die Aggregation der Gesamtschritte über einen bestimmten Zeitraum. Im folgenden Beispiel wird gezeigt, wie die Gesamtschrittzahl für einen Nutzer innerhalb eines bestimmten Zeitraums 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
}

Rohdaten lesen

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

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