W 2026 r. zaczniemy wycofywać interfejsy Google Fit API. Więcej informacji o migracji z Google Fit znajdziesz w przewodniku po migracji.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Śledzenie kroków

Health Connect udostępnia typ danych steps do rejestrowania liczby kroków za pomocą StepsRecord. Kroki są podstawowym pomiarem w śledzeniu stanu zdrowia i aktywności fizycznej.

Odczytywanie liczby kroków na urządzeniu mobilnym

W Androidzie 14 (poziom API 34) i rozszerzeniu pakietu SDK w wersji 20 lub nowszej Health Connect umożliwia zliczanie kroków na urządzeniu. Jeśli jakakolwiek aplikacja otrzyma uprawnienie READ_STEPS, Health Connect zacznie rejestrować kroki z urządzenia z Androidem, a użytkownicy będą automatycznie widzieć dane o krokach dodane do wpisów Kroki w Health Connect.

Aby sprawdzić, czy zliczanie kroków na urządzeniu jest dostępne, upewnij się, że na urządzeniu jest zainstalowany Android 14 (poziom API 34) i rozszerzenie pakietu SDK w wersji co najmniej 20:

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

Jeśli Twoja aplikacja odczytuje zagregowaną liczbę kroków za pomocą aggregate i nie filtruje według DataOrigin, liczba kroków na urządzeniu jest automatycznie uwzględniana w sumie i nie trzeba wprowadzać żadnych zmian w związku z aktualizacją z czerwca 2026 r.

Zmiana atrybucji w przypadku liczby kroków na urządzeniu

Od aktualizacji z czerwca 2026 r. kroki śledzone natywnie przez Health Connect są przypisywane do syntetycznej nazwy pakietu (SPN), np. com.android.healthconnect.phone.jd5bdd37e1a8d3667a05d0abebfc4a89e.

Wcześniej wbudowane kroki były przypisywane do nazwy pakietu android. Dane historyczne o krokach zarejestrowane przed czerwcem 2026 r. zachowują nazwę pakietu android.

SPN są specyficzne dla urządzenia i ograniczone do poszczególnych aplikacji, aby chronić prywatność użytkowników:

Stabilne: SPN na bieżącym urządzeniu jest stabilne w przypadku Twojej aplikacji.
Ograniczone do aplikacji: różne aplikacje na tym samym urządzeniu widzą różne SPN w przypadku danych o krokach na urządzeniu.

Wysyłanie zapytań o liczbę kroków na urządzeniu

Ponieważ SPN są ograniczone i specyficzne dla urządzenia, nie wolno ich zakodować na stałe. Zamiast tego użyj interfejsu API getCurrentDeviceDataSource(), aby pobrać SPN na bieżącym urządzeniu.

Zliczanie kroków na urządzeniu wymaga rozszerzenia pakietu SDK w wersji 20 lub nowszej, ale interfejs API getCurrentDeviceDataSource() jest dostępny w Androidzie 14 (poziom API 34) z rozszerzeniem pakietu SDK w wersji 11 lub nowszej.

Interfejs API getCurrentDeviceDataSource() nie jest jeszcze dostępny w bibliotece Jetpack Health Connect. W poniższych przykładach używamy interfejsu API platformy Android:

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

Jeśli Twoja aplikacja musi odczytywać liczbę kroków na urządzeniu lub wyświetla dane o krokach podzielone według aplikacji źródłowej lub urządzenia, musisz wysyłać zapytania o rekordy, w których DataOrigin ma wartość android lub pasuje do SPN urządzenia. Jeśli Twoja aplikacja pokazuje atrybucję danych o krokach, użyj metadata.device aby zidentyfikować urządzenie źródłowe poszczególnych rekordów. W przypadku liczby kroków na urządzeniu zidentyfikowanej przez SPN w zagregowanych danych możesz użyć metadanych urządzenia, takich jak model lub manufacturer z DeviceDataSource , do atrybucji, albo użyć ogólnej etykiety, np. „Twój telefon”, w przypadku liczby kroków na urządzeniu.

Poniższy przykład pokazuje, jak odczytać zagregowane dane o liczbie kroków na urządzeniu, filtrując zarówno według android, jak i SPN bieżącego urządzenia:

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

Zliczanie kroków na urządzeniu

Użycie czujnika: Health Connect korzysta z czujnika TYPE_STEP_COUNTER z SensorManager. Ten czujnik jest zoptymalizowany pod kątem niskiego zużycia energii, dzięki czemu idealnie nadaje się do ciągłego śledzenia liczby kroków w tle.
Szczegółowość danych: aby oszczędzać baterię, dane o krokach są zwykle grupowane i zapisywane w bazie danych Health Connect nie częściej niż raz na minutę.
Atrybucja: kroki zarejestrowane przez tę funkcję przed czerwcem 2026 r. są przypisywane do nazwy pakietu android w DataOrigin. Po tej dacie są one przypisywane do SPN specyficznej dla urządzenia. Więcej informacji znajdziesz w sekcji Zmiana atrybucji w przypadku liczby kroków na urządzeniu.
Aktywacja: mechanizm zliczania kroków na urządzeniu jest aktywny tylko wtedy, gdy co najmniej 1 aplikacja na urządzeniu otrzyma uprawnienie READ_STEPS w Health Connect.

Sprawdzanie dostępności Health Connect

Zanim spróbujesz użyć Health Connect, Twoja aplikacja powinna sprawdzić, czy Health Connect jest dostępny na urządzeniu użytkownika. Health Connect może nie być wstępnie zainstalowany na wszystkich urządzeniach lub może być wyłączony. Dostępność możesz sprawdzić za pomocą metody HealthConnectClient.getSdkStatus().

Jak sprawdzić dostępność 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
}

W zależności od stanu zwróconego przez getSdkStatus() możesz w razie potrzeby poprosić użytkownika o zainstalowanie lub zaktualizowanie Health Connect ze Sklepu Google Play.

Wymagane uprawnienia

Dostęp do liczby kroków jest chroniony przez te uprawnienia:

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

Aby dodać do aplikacji możliwość zliczania kroków, zacznij od poproszenia o uprawnienia do typu danych Steps.

Oto uprawnienie, które musisz zadeklarować, aby móc zapisywać liczbę kroków:

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

Aby odczytać liczbę kroków, musisz poprosić o te uprawnienia:

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

Prośba o uprawnienia od użytkownika

Po utworzeniu instancji klienta aplikacja musi poprosić użytkownika o uprawnienia. Użytkownicy muszą mieć możliwość przyznawania i odmawiania uprawnień w dowolnym momencie.

Aby to zrobić, utwórz zbiór uprawnień dla wymaganych typów danych. Najpierw upewnij się, że uprawnienia w zbiorze są zadeklarowane w manifeście Androida.

// Create a set of permissions for required data types
val PERMISSIONS =
    setOf(
  HealthPermission.getReadPermission(StepsRecord::class),
  HealthPermission.getWritePermission(StepsRecord::class)
)

Użyj getGrantedPermissions , aby sprawdzić, czy Twoja aplikacja ma już wymagane uprawnienia. Jeśli nie, użyj createRequestPermissionResultContract , aby poprosić o te uprawnienia. Spowoduje to wyświetlenie ekranu uprawnień Health Connect.

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

Ponieważ użytkownicy mogą przyznawać i cofać uprawnienia w dowolnym momencie, Twoja aplikacja musi sprawdzać uprawnienia za każdym razem przed ich użyciem i obsługiwać sytuacje, w których uprawnienia zostaną utracone.

Informacje zawarte w rekordzie Steps

Każdy StepsRecord zawiera te informacje:

count: liczba kroków wykonanych w danym przedziale czasu, jako Long.
startTime: czas rozpoczęcia przedziału pomiarowego.
endTime: czas zakończenia przedziału pomiarowego.
startZoneOffset: przesunięcie strefy czasowej dla czasu rozpoczęcia.
endZoneOffset: przesunięcie strefy czasowej dla czasu zakończenia.

Obsługiwane agregacje

W przypadku StepsRecord dostępne są te wartości zagregowane:

COUNT_TOTAL

W przypadku StepsCadenceRecord dostępne są te wartości zagregowane:

Przykład użycia

W kolejnych sekcjach dowiesz się, jak odczytywać i zapisywać dane StepsRecord.

Zapisywanie danych o krokach

Twoja aplikacja może zapisywać dane o liczbie kroków, wstawiając StepsRecord instancje. Poniższy przykład pokazuje, jak zarejestrować 1000 kroków wykonanych przez użytkownika:

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

Odczytywanie danych zbiorczych

Najczęstszym sposobem odczytywania danych o krokach jest agregowanie łącznej liczby kroków w danym okresie. Poniższy przykład pokazuje, jak odczytać łączną liczbę kroków użytkownika w określonym zakresie czasu:

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

Odczytywanie nieprzetworzonych danych

Poniższy przykład pokazuje, jak odczytać nieprzetworzone dane StepsRecord między czasem rozpoczęcia a czasem zakończenia:

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