Schritte zählen

Health Connect bietet den Datentyp Schritte zum Aufzeichnen der Schrittanzahl mit StepsRecord. Schritte sind eine grundlegende Messung bei der Gesundheits- und Fitnessmessung.

Schritte auf Mobilgeräten lesen

Mit Android 14 (API-Level 34) und SDK-Erweiterung Version 20 oder höher bietet Health Connect die 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, dass den Schritte -Einträgen in Health Connect automatisch Schrittdaten hinzugefügt werden.

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-Erweiterung Version 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 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 im Juni 2026 werden Schritte, die nativ von Health Connect erfasst werden, einem synthetischen Paketnamen (SPN) zugeschrieben, z. B. com.android.healthconnect.phone.jd5bdd37e1a8d3667a05d0abebfc4a89e.

Bisher wurden integrierte Schritte dem Paketnamen android zugeschrieben. Für vor Juni 2026 aufgezeichnete Schrittdaten wird der Paketname android beibehalten.

SPNs sind gerätespezifisch und werden pro Anwendung festgelegt, um die Privatsphäre der Nutzer zu schützen:

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

Abfrage für Schritte auf dem Gerät

Da SPNs gerätespezifisch sind und nur für eine bestimmte Anwendung gelten, dürfen Sie SPN-Werte nicht fest codieren. 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 SDK-Erweiterung Version 20 oder höher erforderlich. Die getCurrentDeviceDataSource() API ist jedoch auf Android 14 (API-Level 34) mit SDK-Erweiterung Version 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 aufschlüsselt, müssen Sie nach Einträgen suchen, bei denen DataOrigin android ist oder mit dem SPN des Geräts übereinstimmt. Wenn Ihre App die Attribution für Schrittdaten anzeigt, verwenden Sie metadata.device um das Quellgerät für einzelne Einträge zu identifizieren. Für Schritte auf dem Gerät, die in aggregierten Daten durch einen SPN identifiziert werden, können Sie Gerätemetadaten wie model oder manufacturer aus DeviceDataSource für die Attribution verwenden oder ein allgemeines Label wie „Ihr Smartphone“ für Schritte auf dem Gerät verwenden.

Das folgende Beispiel zeigt, wie aggregierte Schrittdaten 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.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 TYPE_STEP_COUNTER Sensor aus 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 die Akkulaufzeit zu verlängern, werden Schrittdaten in der Regel in Batches verarbeitet 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 DataOrigin dem Paketnamen android zugeschrieben. Nach diesem Datum werden sie einem gerätespezifischen SPN zugeschrieben. Weitere Informationen finden Sie unter Attributionsänderung 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 READ_STEPSBerechtigung 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.

So prüfen Sie die Verfügbarkeit von Health Connect

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 auffordern, Health Connect bei Bedarf im 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 hinzufügen möchten, Schritte zu erfassen, fordern Sie zuerst Berechtigungen für den Datentyp Steps an.

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 Clientinstanz 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. Achten Sie darauf, dass die Berechtigungen im Set zuerst in Ihrem Android-Manifest deklariert werden. 

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, fordern Sie diese Berechtigungen mit createRequestPermissionResultContract an. Daraufhin wird der Health Connect-Berechtigungsbildschirm 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 Ihre App jedes Mal vor der Verwendung von Berechtigungen prüfen, ob sie erteilt wurden, und Szenarien berücksichtigen, in denen Berechtigungen verloren gehen.

Informationen in einem Eintrag vom Typ „Schritte“

Jeder StepsRecord enthält die folgenden Informationen:

  • count: Die Anzahl der Schritte im Zeitintervall als Long.
  • startTime: Die Startzeit des Messintervalls.
  • endTime: Die Endzeit des Messintervalls.
  • startZoneOffset: Der Zonen-Offset für die Startzeit.
  • endZoneOffset: Der Zonen-Offset 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 gezeigt, wie Sie StepsRecord-Daten lesen und schreiben.

Schrittdaten schreiben

Ihre App kann Schrittdaten 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))

Aggregierte Daten lesen

Die gängigste Methode zum Lesen von Schrittdaten ist die Aggregation der Gesamtschritte ü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(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

Das folgende Beispiel zeigt, wie Rohdaten vom Typ StepsRecord Daten zwischen einer Start- und einer Endzeit gelesen werden:

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