Zapisywanie danych

Ten przewodnik jest zgodny z Health Connect w wersji 1.1.0-alpha12.

W tym przewodniku opisujemy proces zapisywania i aktualizowania danych w Health Connect.

Obsługa wartości zerowych

Niektóre typy danych, takie jak kroki, odległość czy kalorie, mogą mieć wartość 0. Wartości zerowe należy zapisywać tylko wtedy, gdy odzwierciedlają one prawdziwą nieaktywność, gdy użytkownik miał na sobie urządzenie. Nie wpisuj wartości zerowych, jeśli urządzenie nie było noszone, brakuje danych lub bateria się wyczerpała. W takich przypadkach pomiń rekord, aby uniknąć wprowadzania w błąd.

Konfigurowanie struktury danych

Zanim zapiszemy dane, musimy najpierw skonfigurować rekordy. W przypadku ponad 50 rodzajów danych każdy z nich ma własną strukturę. Więcej informacji o dostępnych typach danych znajdziesz w dokumentacji Jetpacka.

Podstawowe rekordy

Typ danych Kroki w Health Connect rejestruje liczbę kroków wykonanych przez użytkownika między odczytami. Liczba kroków to powszechny pomiar na platformach związanych ze zdrowiem, aktywnością fizyczną i dobrym samopoczuciem.

Poniższy przykład pokazuje, jak ustawić dane dotyczące liczby kroków:

val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofMinutes(15))

val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = ZoneOffset.UTC,
    endZoneOffset = ZoneOffset.UTC,
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    )
)

Rekordy z jednostkami miary

Health Connect może przechowywać wartości wraz z jednostkami miary, aby zapewnić dokładność. Przykładem jest typ danych Nutrition, który jest obszerny i wszechstronny. Zawiera wiele opcjonalnych pól dotyczących składników odżywczych, od węglowodanów ogółem po witaminy. Każdy punkt danych reprezentuje składniki odżywcze, które mogły zostać spożyte w ramach posiłku lub produktu spożywczego.

W tym typie danych wszystkie składniki odżywcze są reprezentowane w jednostkach Mass, a energy w jednostce Energy.

Poniższy przykład pokazuje, jak ustawić dane o odżywianiu dla użytkownika, który zjadł banana:

val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofMinutes(1))

val banana = NutritionRecord(
    name = "banana",
    energy = 105.0.kilocalories,
    dietaryFiber = 3.1.grams,
    potassium = 0.422.grams,
    totalCarbohydrate = 27.0.grams,
    totalFat = 0.4.grams,
    saturatedFat = 0.1.grams,
    sodium = 0.001.grams,
    sugar = 14.0.grams,
    vitaminB6 = 0.0005.grams,
    vitaminC = 0.0103.grams,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = ZoneOffset.UTC,
    endZoneOffset = ZoneOffset.UTC,
    metadata = Metadata.manualEntry(
        device = Device(type = Device.TYPE_PHONE)
    )
)

Rekordy z danymi serii

Health Connect może przechowywać listę danych szeregowych. Przykładem jest typ danych Tętno, który rejestruje serię próbek uderzeń serca wykrytych między odczytami.

W tym typie danych parametr samples jest reprezentowany przez listę próbek tętna. Każda próbka zawiera beatsPerMinute wartość i wartość time.

Poniższy przykład pokazuje, jak ustawić dane serii tętna:

val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofMinutes(5))

val heartRateRecord = HeartRateRecord(
    startTime = startTime,
    startZoneOffset = ZoneOffset.UTC,
    endTime = endTime,
    endZoneOffset = ZoneOffset.UTC,
    // records 10 arbitrary data, to replace with actual data
    samples = List(10) { index ->
        HeartRateRecord.Sample(
            time = startTime + Duration.ofSeconds(index.toLong()),
            beatsPerMinute = 100 + index.toLong(),
        )
    },
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    ))

Prośba użytkownika o uprawnienia

Po utworzeniu instancji klienta aplikacja musi poprosić użytkownika o przyznanie uprawnień. Użytkownicy muszą mieć możliwość przyznania lub odmowy przyznania uprawnień w dowolnym momencie.

Aby to zrobić, utwórz zestaw uprawnień dla wymaganych typów danych. Sprawdź, czy uprawnienia w zestawie są najpierw zadeklarowane w pliku manifestu Androida.

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

Użyj getGrantedPermissions, aby sprawdzić, czy Twoja aplikacja ma już przyznane wymagane uprawnienia. Jeśli nie, użyj createRequestPermissionResultContract, aby poprosić o te uprawnienia. Wyświetli się ekran 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)
  }
}

Użytkownicy mogą w dowolnym momencie przyznawać i anulować uprawnienia, dlatego aplikacja musi okresowo sprawdzać, czy uprawnienia zostały przyznane, i obsługiwać sytuacje, w których uprawnienia zostaną utracone.

Zapisywanie danych

Jednym z najczęstszych procesów w Health Connect jest zapisywanie danych. Aby dodać rekordy, użyj ikony insertRecords.

Ten przykład pokazuje, jak zapisywać dane dotyczące liczby kroków:

suspend fun insertSteps(healthConnectClient: HealthConnectClient) {
    val endTime = Instant.now()
    val startTime = endTime.minus(Duration.ofMinutes(5))
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = startTime,
            endTime = endTime,
            startZoneOffset = ZoneOffset.UTC,
            endZoneOffset = ZoneOffset.UTC,
            metadata = Metadata.autoRecorded(
                device = Device(type = Device.TYPE_WATCH)
            )
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling here
    }
}

Aktualizowanie danych

Jeśli musisz zmienić co najmniej 1 rekord, zwłaszcza gdy chcesz zsynchronizować bazę danych aplikacji z danymi z Health Connect, możesz zaktualizować dane. Istnieją 2 sposoby aktualizowania istniejących danych, które zależą od identyfikatora używanego do wyszukiwania rekordów.

Metadane

Warto najpierw przyjrzeć się klasie Metadata, ponieważ jest ona niezbędna podczas aktualizowania danych. Każdy Record w Health Connect ma pole metadata. Poniższe właściwości są istotne w przypadku synchronizacji:

Aktualizacja po przeczytaniu w określonym przedziale czasu

Aby zaktualizować dane, najpierw przygotuj potrzebne rekordy. Wprowadź w razie potrzeby zmiany w rekordach. Następnie wywołaj updateRecords, aby wprowadzić zmiany.

Poniższy przykład pokazuje, jak zaktualizować dane. W tym celu wartości przesunięcia strefy czasowej każdego rekordu są dostosowywane do czasu PST.

suspend fun updateSteps(
    healthConnectClient: HealthConnectClient,
    prevRecordStartTime: Instant,
    prevRecordEndTime: Instant
) {
    try {
        val request = healthConnectClient.readRecords(
            ReadRecordsRequest(
                recordType = StepsRecord::class, timeRangeFilter = TimeRangeFilter.between(
                    prevRecordStartTime, prevRecordEndTime
                )
            )
        )

        val newStepsRecords = arrayListOf<StepsRecord>()
        for (record in request.records) {
            // Adjusted both offset values to reflect changes
            val sr = StepsRecord(
                count = record.count,
                startTime = record.startTime,
                startZoneOffset = record.startTime.atZone(ZoneId.of("PST")).offset,
                endTime = record.endTime,
                endZoneOffset = record.endTime.atZone(ZoneId.of("PST")).offset,
                metadata = record.metadata
            )
            newStepsRecords.add(sr)
        }

        healthConnectClient.updateRecords(newStepsRecords)
    } catch (e: Exception) {
        // Run error handling here
    }
}

Wstawianie lub aktualizowanie za pomocą identyfikatora rekordu klienta

Jeśli używasz opcjonalnych wartości Identyfikator rekordu klienta i Wersja rekordu klienta, zalecamy używanie znaku insertRecords zamiast znaku updateRecords.

Funkcja insertRecords może wstawiać dane lub je aktualizować. Jeśli dane istnieją w Health Connect na podstawie podanego zestawu identyfikatorów rekordów klienta, zostaną zastąpione. W przeciwnym razie zostaną zapisane jako nowe dane. Ten scenariusz jest przydatny, gdy musisz synchronizować dane z pamięci danych aplikacji z Health Connect.

Poniższy przykład pokazuje, jak wykonać operację upsert na danych pobranych z pamięci danych aplikacji:

suspend fun pullStepsFromDatastore() : ArrayList<StepsRecord> {
    val appStepsRecords = arrayListOf<StepsRecord>()
    // Pull data from app datastore
    // ...
    // Make changes to data if necessary
    // ...
    // Store data in appStepsRecords
    // ...
    var sr = StepsRecord(
        metadata = Metadata.autoRecorded(
            clientRecordId = "Your client record ID",
            device = Device(type = Device.TYPE_WATCH)
        ),
        // Assign more parameters for this record
    )
    appStepsRecords.add(sr)
    // ...
    return appStepsRecords
}

suspend fun upsertSteps(
    healthConnectClient: HealthConnectClient,
    newStepsRecords: ArrayList<StepsRecord>
) {
    try {
        healthConnectClient.insertRecords(newStepsRecords)
    } catch (e: Exception) {
        // Run error handling here
    }
}

Następnie możesz wywoływać te funkcje w głównym wątku.

upsertSteps(healthConnectClient, pullStepsFromDatastore())

Sprawdzanie wartości w wersji rekordu klienta

Jeśli proces wstawiania danych obejmuje wersję rekordu klienta, Health Connect przeprowadza porównanie wartości w clientRecordVersion. Jeśli wersja w wstawionych danych jest wyższa niż wersja w danych, które już istnieją, nastąpi aktualizacja. W przeciwnym razie proces zignoruje zmianę, a wartość pozostanie bez zmian.

Aby uwzględnić w danych wersjonowanie, musisz podać wartość Metadata.clientRecordVersion z wartością Long na podstawie logiki wersjonowania.

val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofMinutes(15))

val stepsRecord = StepsRecord(
    count = 100L,
    startTime = startTime,
    startZoneOffset = ZoneOffset.UTC,
    endTime = endTime,
    endZoneOffset = ZoneOffset.UTC,
    metadata = Metadata.manualEntry(
        clientRecordId = "Your supplied record ID",
        clientRecordVersion = 0L, // Your supplied record version
        device = Device(type = Device.TYPE_WATCH)
    )
)

Operacje upsert nie zwiększają automatycznie wartości version, gdy występują zmiany, co zapobiega nieoczekiwanym przypadkom nadpisywania danych. W takim przypadku musisz ręcznie podać wyższą wartość.

Sprawdzone metody zapisywania danych

Aplikacje mogą zapisywać w Health Connect tylko dane pochodzące z własnych źródeł.

Jeśli dane w aplikacji zostały zaimportowane z innej aplikacji, to ta inna aplikacja jest odpowiedzialna za zapisywanie własnych danych w Health Connect.

Warto też wdrożyć logikę obsługującą wyjątki zapisu, takie jak dane wykraczające poza zakres lub błąd systemu wewnętrznego. Możesz zastosować strategie wycofywania i ponawiania w mechanizmie planowania zadań. Jeśli zapisywanie danych w Health Connect ostatecznie się nie powiedzie, upewnij się, że aplikacja może przejść do kolejnego etapu eksportu. Nie zapomnij rejestrować błędów i zgłaszać ich, aby ułatwić diagnozę.

Podczas śledzenia danych możesz postępować zgodnie z kilkoma sugestiami, w zależności od sposobu zapisywania danych przez aplikację.

Obsługa stref czasowych

Podczas zapisywania rekordów opartych na czasie unikaj domyślnego ustawiania przesunięć na zoneOffset.UTC, ponieważ może to prowadzić do niedokładnych sygnatur czasowych, gdy użytkownicy znajdują się w innych strefach. Zamiast tego oblicz przesunięcie na podstawie rzeczywistej lokalizacji urządzenia. Strefę czasową urządzenia możesz pobrać za pomocą ZoneId.systemDefault().

val endTime = Instant.now()
val startTime = endTime.minus(java.time.Duration.ofDays(1))
val stepsRecords = mutableListOf<StepsRecord>()
var sampleTime = startTime
val minutesBetweenSamples = 15L
while (sampleTime < endTime) {
    // Get the default ZoneId then convert it to an offset
    val zoneOffset = ZoneOffset.systemDefault().rules.getOffset(sampleTime)
    stepsRecords += StepsRecord(
        startTime = sampleTime.minus(java.time.Duration.ofMinutes(minutesBetweenSamples)),
        startZoneOffset = zoneOffset,
        endTime = sampleTime,
        endZoneOffset = zoneOffset,
        count = Random.nextLong(1, 100),
        metadata = Metadata.unknownRecordingMethod(),
    )
    sampleTime = sampleTime.plus(java.time.Duration.ofMinutes(minutesBetweenSamples))
}
healthConnectClient.insertRecords(
    stepsRecords
)

Więcej informacji znajdziesz w dokumentacji ZoneId.

Śledzenie pasywne

Dotyczy to aplikacji, które pasywnie śledzą aktywność fizyczną lub stan zdrowia, np. rejestrują kroki lub tętno w tle.

Aplikacja musi okresowo zapisywać dane w Health Connect w jeden z tych sposobów:

• Podczas każdej synchronizacji zapisuj tylko nowe i zaktualizowane dane, które zostały zmodyfikowane od czasu ostatniej synchronizacji.
• Dziel żądania na części, tak aby każde żądanie zapisu zawierało maksymalnie 1000 rekordów.
• Użyj WorkManager, aby zaplanować okresowe zadania w tle z okresem co najmniej 15 minut.
• Ogranicz wykonywanie zadań tylko do sytuacji, gdy urządzenie jest nieaktywne i nie ma niskiego poziomu baterii.

val constraints = Constraints.Builder()
    .requiresBatteryNotLow()
    .requiresDeviceIdle(true)
    .build()

val writeDataWork = PeriodicWorkRequestBuilder<WriteDataToHealthConnectWorker>(
        15,
        TimeUnit.MINUTES,
        5,
        TimeUnit.MINUTES
    )
    .setConstraints(constraints)
    .build()

Aktywne śledzenie

Obejmuje to aplikacje, które śledzą zdarzenia, takie jak ćwiczenia i sen, lub dane wprowadzane ręcznie przez użytkownika, np. informacje o odżywianiu. Te rekordy są tworzone, gdy aplikacja jest na pierwszym planie lub w rzadkich przypadkach, gdy jest używana kilka razy dziennie.

Upewnij się, że aplikacja nie utrzymuje Health Connect w stanie aktywnym przez cały czas trwania zdarzenia.

Dane muszą być zapisywane w Health Connect na jeden z tych 2 sposobów:

• Synchronizuj dane z Health Connect po zakończeniu wydarzenia. Na przykład synchronizuj dane, gdy użytkownik zakończy śledzoną sesję ćwiczeń.
• Zaplanuj jednorazowe zadanie za pomocą WorkManager, aby później zsynchronizować dane.

Sprawdzone metody dotyczące szczegółowości i częstotliwości zapisów

Podczas zapisywania danych w Health Connect używaj odpowiedniej rozdzielczości. Używanie odpowiedniej rozdzielczości pomaga zmniejszyć obciążenie pamięci masowej przy jednoczesnym zachowaniu spójnych i dokładnych danych. Rozdzielczość danych obejmuje 2 aspekty:

1. Częstotliwość zapisów: jak często aplikacja przesyła nowe dane do Health Connect. Możesz na przykład zapisywać nowe dane co 15 minut.
2. Szczegółowość zapisywanych danych: jak często próbkowane były dane przesyłane do usługi. Na przykład zapisuj próbki tętna co 5 sekund. Nie każdy typ danych wymaga tej samej częstotliwości próbkowania. Aktualizowanie danych o liczbie kroków co sekundę nie przynosi większych korzyści niż aktualizowanie ich rzadziej, np. co 60 sekund. Wyższe częstotliwości próbkowania mogą jednak zapewnić użytkownikom bardziej szczegółowy i dokładny wgląd w dane dotyczące zdrowia i aktywności fizycznej. Częstotliwości próbkowania powinny zachowywać równowagę między szczegółowością a wydajnością.

Zapisywanie danych monitorowanych przez cały dzień

W przypadku danych zbieranych na bieżąco, np. liczby kroków, aplikacja powinna zapisywać dane w Health Connect co najmniej co 15 minut w ciągu dnia.

Zapisywanie sesji

Dane powinny być zapisywane w Health Connect na koniec treningu lub sesji snu.

Aplikacja powinna co najmniej spełniać wymagania podane w kolumnie oczekiwane w tej tabeli. W miarę możliwości postępuj zgodnie z najlepszymi wskazówkami.

Sesje ćwiczeń i snu

Ten przykład pokazuje, jak zapisywać dane podczas ćwiczenia:

Poniższy przykład pokazuje, jak zapisywać dane podczas sesji snu lub po niej:

Wydarzenia obejmujące wiele dyscyplin sportowych

W tym podejściu wykorzystywane są istniejące typy i struktury danych, a także weryfikowana jest zgodność z obecnymi implementacjami Health Connect i czytnikami danych. Jest to powszechne podejście stosowane przez platformy fitness.

Poniższy przykład pokazuje, jak zapisywać dane dotyczące triathlonu:

val swimStartTime = Instant.parse("2024-08-22T08:00:00Z")
val swimEndTime = Instant.parse("2024-08-22T08:30:00Z")
val bikeStartTime = Instant.parse("2024-08-22T08:40:00Z")
val bikeEndTime = Instant.parse("2024-08-22T09:40:00Z")
val runStartTime = Instant.parse("2024-08-22T09:50:00Z")
val runEndTime = Instant.parse("2024-08-22T10:20:00Z")

val swimSession = ExerciseSessionRecord(
    startTime = swimStartTime,
    endTime = swimEndTime,
    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_SWIMMING_OPEN_WATER,
    metadata = Metadata.autoRecorded(
      device = Device(type = Device.TYPE_WATCH)
    )
)

val bikeSession = ExerciseSessionRecord(
    startTime = bikeStartTime,
    endTime = bikeEndTime,
    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_BIKING,
    metadata = Metadata.autoRecorded(
      device = Device(type = Device.TYPE_WATCH)
    )
)

val runSession = ExerciseSessionRecord(
    startTime = runStartTime,
    endTime = runEndTime,
    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_RUNNING,
    metadata = Metadata.autoRecorded(
      device = Device(type = Device.TYPE_WATCH)
    )
)

healthConnectClient.insertRecords(listOf(swimSession, bikeSession, runSession))