Odczyt nieprzetworzonych danych

Poniższy przykład pokazuje, jak odczytywać nieprzetworzone dane w ramach typowego przepływu pracy.

Odczytywanie danych

Health Connect umożliwia aplikacjom odczytywanie danych z magazynu danych, gdy są one na pierwszym planie i w tle:

• Odczytywanie na pierwszym planie: dane z Health Connect możesz zwykle odczytywać, gdy aplikacja jest na pierwszym planie. W takich przypadkach możesz użyć usługi (działającej) na pierwszym planie, aby wykonać tę operację, jeśli użytkownik lub system umieści aplikację w tle podczas operacji odczytu.

• Odczytywanie w tle: prosząc użytkownika o dodatkowe uprawnienia, możesz odczytywać dane po tym, jak użytkownik lub system umieści Twoją aplikację w tle. Zobacz pełny przykład odczytu w tle.

Typ danych Kroki w Health Connect rejestruje liczbę kroków, które użytkownik wykonał między odczytami. Liczba kroków to wspólny pomiar na platformach związanych ze zdrowiem, kondycją i dobrym samopoczuciem. Health Connect umożliwia odczytywanie i zapisywanie danych o liczbie kroków.

Aby odczytać rekordy, utwórz ReadRecordsRequest i podaj go podczas wywoływania funkcji readRecords.

Przykład poniżej pokazuje, jak odczytać dane o liczbie kroków użytkownika w określonym czasie. Rozszerzony przykład z użyciem SensorManager znajdziesz w przewodniku po danych dotyczących liczby kroków.

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

Możesz też odczytywać dane w formie zbiorczej za pomocą aggregate.

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 danych o krokach na urządzeniu mobilnym

W Androidzie 14 (API na poziomie 34) i w rozszerzeniu SDK w wersji 20 lub nowszej Health Connect zapewnia zliczanie kroków na urządzeniu. Jeśli jakiejkolwiek aplikacji przyznano uprawnienie READ_STEPS, Health Connect zaczyna rejestrować kroki z urządzenia z Androidem, a użytkownicy widzą dane o krokach automatycznie dodawane do wpisów Kroki w Health Connect.

Aby sprawdzić, czy na urządzeniu jest dostępna funkcja zliczania kroków, upewnij się, że urządzenie ma Androida 14 (poziom API 34) i co najmniej wersję 20 rozszerzenia pakietu SDK:

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 zagregowane liczby kroków za pomocą interfejsu aggregate i nie filtruje ich według parametru DataOrigin, kroki zarejestrowane na urządzeniu są automatycznie uwzględniane w sumie i nie są wymagane żadne zmiany w przypadku aktualizacji z czerwca 2026 r.

Zmiana atrybucji w przypadku kroków na urządzeniu

Od aktualizacji z czerwca 2026 r. kroki śledzone natywnie przez Health Connect będą 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 dotyczące kroków zarejestrowane przed czerwcem 2026 r. zachowają nazwę pakietu android.

Identyfikatory SPN są powiązane z konkretnym urządzeniem i zakresem poszczególnych aplikacji, aby chronić prywatność użytkowników:

• Stabilny: SPN bieżącego urządzenia jest stabilny w przypadku Twojej aplikacji.
• Zakres aplikacji: różne aplikacje na tym samym urządzeniu widzą różne numery SPN dla danych o krokach na urządzeniu.

Zapytanie o kroki na urządzeniu

Numery SPN są ograniczone do konkretnego urządzenia, więc nie wolno ich zakodować na stałe. Zamiast tego użyj interfejsu getCurrentDeviceDataSource() API, aby pobrać SPN dla bieżącego urządzenia.

Licznik kroków na urządzeniu wymaga wersji rozszerzenia pakietu SDK 20 lub nowszej, a interfejs getCurrentDeviceDataSource() API jest dostępny na Androidzie 14 (API na poziomie 34) z wersją rozszerzenia pakietu SDK 11 lub nowszą.

Interfejs API getCurrentDeviceDataSource() nie jest jeszcze dostępny w bibliotece Jetpack Health Connect. W tych przykładach użyto 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 aplikacja musi odczytywać dane o krokach na urządzeniu lub wyświetla dane o krokach podzielone według aplikacji lub urządzenia źródłowego, musisz wysyłać zapytania o rekordy, w których DataOrigin jest równe android lub pasuje do SPN urządzenia. Jeśli Twoja aplikacja wyświetla atrybucję danych o krokach, użyj metadata.device, aby określić urządzenie źródłowe poszczególnych rekordów. W przypadku kroków na urządzeniu zidentyfikowanych przez SPN w zagregowanych danych możesz używać metadanych urządzenia, takich jak model lub manufacturer z DeviceDataSource, do atrybucji lub używać ogólnej etykiety, np. „Twój telefon”, w przypadku kroków na urządzeniu.

Przykład poniżej pokazuje, jak odczytać zagregowane dane o liczbie kroków na urządzeniu, filtrując zarówno android, jak i bieżący SPN 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.
    }
}

Liczenie kroków na urządzeniu

• Korzystanie z czujników: Health Connect korzysta z czujnikaTYPE_STEP_COUNTER firmy SensorManager. Ten czujnik jest zoptymalizowany pod kątem niskiego zużycia energii, dzięki czemu idealnie nadaje się do ciągłego śledzenia kroków w tle.
• Szczegółowość danych: aby oszczędzać baterię, dane o krokach są zwykle przesyłane w pakietach 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 konkretnego urządzenia. Zobacz Zmiana atrybucji w przypadku 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 ma przyznane uprawnienie READ_STEPS w Health Connect.

Przykład odczytywania w tle

Aby odczytywać dane w tle, zadeklaruj w pliku manifestu to uprawnienie:

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

Przykład poniżej pokazuje, jak odczytać dane o liczbie kroków w tle dla użytkownika w określonym czasie za pomocą funkcji WorkManager:

class ScheduleWorker(appContext: Context, workerParams: WorkerParameters) :
    CoroutineWorker(appContext, workerParams) {

    override suspend fun doWork(): Result {
        val healthConnectClient = HealthConnectClient.getOrCreate(applicationContext)
        // Perform background read logic here
        return Result.success()
    }
}
HealthConnectWorker.kt

@OptIn(ExperimentalFeatureAvailabilityApi::class)
fun enqueueBackgroundReadWorker(context: Context, healthConnectClient: HealthConnectClient) {
    if (healthConnectClient
            .features
            .getFeatureStatus(
                HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_IN_BACKGROUND
            ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE
    ) {

        val periodicWorkRequest = PeriodicWorkRequestBuilder<ScheduleWorker>(1, TimeUnit.HOURS)
            .build()

        WorkManager.getInstance(context).enqueueUniquePeriodicWork(
            "read_health_connect",
            ExistingPeriodicWorkPolicy.KEEP,
            periodicWorkRequest
        )
    }
}
HealthConnectWorker.kt

Parametr ReadRecordsRequest ma domyślną wartość pageSize 1000. Jeśli liczba rekordów w jednym readResponse przekracza pageSize żądania, musisz przejść przez wszystkie strony odpowiedzi, aby pobrać wszystkie rekordy za pomocą pageToken. Uważaj jednak, aby nie przekroczyć limitu żądań.

Przykład odczytu pageToken

Do odczytywania rekordów zalecamy używanie pageToken, aby pobierać wszystkie dostępne dane z wybranego okresu.

Poniższy przykład pokazuje, jak odczytać wszystkie rekordy, dopóki nie zostaną wykorzystane wszystkie tokeny strony:

val type = HeartRateRecord::class
val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofDays(7))

try {
    var pageToken: String? = null
    do {
        val readResponse =
            healthConnectClient.readRecords(
                ReadRecordsRequest(
                    recordType = type,
                    timeRangeFilter = TimeRangeFilter.between(
                        startTime,
                        endTime
                    ),
                    pageToken = pageToken
                )
            )
        val records = readResponse.records
        // Do something with records
        pageToken = readResponse.pageToken
    } while (pageToken != null)
} catch (quotaError: IllegalStateException) {
    // Backoff
}
HealthConnectManager.kt

Odczytywanie wcześniej zapisanych danych

Jeśli aplikacja zapisywała wcześniej rekordy w Health Connect, może odczytywać dane historyczne. Dotyczy to sytuacji, w których aplikacja musi ponownie zsynchronizować się z Health Connect po ponownym zainstalowaniu przez użytkownika.

Obowiązują pewne ograniczenia dotyczące odczytu:

• Android 14 lub nowszy

  • Brak historycznego limitu odczytywania przez aplikację własnych danych.
  • 30-dniowy limit odczytywania przez aplikację innych danych.

• Android 13 lub starszy

  • 30-dniowy limit odczytywania danych przez aplikację.

Ograniczenia można usunąć, prosząc o uprawnienia do odczytu.

Aby odczytać dane historyczne, musisz wskazać nazwę pakietu jako obiekt DataOrigin w parametrze dataOriginFilter elementu ReadRecordsRequest.

Poniższy przykład pokazuje, jak wskazać nazwę pakietu podczas odczytywania rekordów tętna:

try {
    val response =  healthConnectClient.readRecords(
        ReadRecordsRequest(
            recordType = HeartRateRecord::class,
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
            dataOriginFilter = setOf(DataOrigin("com.my.package.name"))
        )
    )
    for (record in response.records) {
        // Process each record
    }
} catch (e: Exception) {
    // Run error handling here
}
HealthConnectManager.kt

Odczytywanie danych starszych niż 30 dni

Domyślnie wszystkie aplikacje mogą odczytywać dane z Health Connect z okresu do 30 dni przed przyznaniem im uprawnień.

Jeśli musisz rozszerzyć uprawnienia do odczytu poza domyślne ograniczenia, poproś o to, wysyłając PERMISSION_READ_HEALTH_DATA_HISTORY. W przeciwnym razie próba odczytania rekordów starszych niż 30 dni spowoduje błąd.

Historia uprawnień usuniętej aplikacji

Jeśli użytkownik usunie Twoją aplikację, wszystkie uprawnienia, w tym uprawnienia do historii, zostaną cofnięte. Jeśli użytkownik ponownie zainstaluje aplikację i ponownie przyzna jej uprawnienia, będą obowiązywać te same domyślne ograniczenia, a aplikacja będzie mogła odczytywać dane z Health Connect z okresu do 30 dni przed tą nową datą.

Załóżmy na przykład, że użytkownik usunie Twoją aplikację 10 maja 2023 r., a następnie zainstaluje ją ponownie 15 maja 2023 r. i przyzna jej uprawnienia do odczytu. Najwcześniejsza data, od której Twoja aplikacja może domyślnie odczytywać dane, to 15 kwietnia 2023 r.

Obsługa wyjątków

W przypadku napotkania problemu Health Connect zgłasza standardowe wyjątki dotyczące operacji CRUD. Aplikacja powinna przechwytywać i obsługiwać każdy z tych wyjątków w odpowiedni sposób.

Każda metoda w HealthConnectClient zawiera listę wyjątków, które mogą zostać zgłoszone. Ogólnie rzecz biorąc, aplikacja powinna obsługiwać te wyjątki: