Ten przewodnik opisuje proces zapisywania i aktualizowania danych w Health Connect.
Skonfiguruj strukturę danych
Przed zapisaniem danych musimy najpierw skonfigurować rekordy. W przypadku ponad 50 typów danych każdy ma swoją własną strukturę. Więcej informacji o dostępnych typach danych znajdziesz w dokumentacji Jetpacka.
Rekordy podstawowe
Typ danych Kroki w Health Connect rejestruje liczbę kroków, które użytkownik wykonał między odczytami. Liczba kroków to często spotykana metoda pomiarów na platformach związanych ze zdrowiem, aktywnością i samopoczuciem.
Poniższy przykład pokazuje, jak skonfigurować dane o liczbie kroków:
val stepsRecord = StepsRecord(
count = 120,
startTime = START_TIME,
endTime = END_TIME,
startZoneOffset = START_ZONE_OFFSET,
endZoneOffset = END_ZONE_OFFSET
)
Rekordy z jednostkami miary
Aby zapewnić dokładność, Health Connect może przechowywać wartości wraz z jednostkami miary. Jednym z przykładów jest typ danych Żywienie, który jest bardzo obszerny. Zawierają wiele opcjonalnych pól odżywczych, od węglowodanów po witaminy. Każdy punkt danych odzwierciedla składniki odżywcze, które zostały potencjalnie spożyte jako część posiłku lub elementu żywnościowego.
W tym typie danych wszystkie składniki odżywcze są wyrażone w jednostkach Mass
, a energy
– w jednostce Energy
.
Poniższy przykład pokazuje, jak ustawić dane dotyczące wartości odżywczej użytkownika, który zjadł banana:
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 = START_TIME,
endTime = END_TIME,
startZoneOffset = START_ZONE_OFFSET,
endZoneOffset = END_ZONE_OFFSET
)
Rekordy z danymi serii
Health Connect może przechowywać listę danych serii. Jednym z przykładów jest typ danych Tętno, który rejestruje serię próbek tętna wykrytych między odczytami.
W tym typie danych parametr samples
jest reprezentowany przez listę Próbek tętna. Każda próbka zawiera wartości beatsPerMinute
i time
.
Poniższy przykład pokazuje, jak ustawić dane dotyczące serii tętna:
val heartRateRecord = HeartRateRecord(
startTime = START_TIME,
startZoneOffset = START_ZONE_OFFSET,
endTime = END_TIME,
endZoneOffset = END_ZONE_OFFSET,
// records 10 arbitrary data, to replace with actual data
samples = List(10) { index ->
HeartRateRecord.Sample(
time = START_TIME + Duration.ofSeconds(index.toLong()),
beatsPerMinute = 100 + index.toLong(),
)
}
)
Zapisywanie danych
Jednym z typowych przepływów pracy w Health Connect jest zapisywanie danych. Aby dodać rekordy, użyj funkcji insertRecords
.
Ten przykład pokazuje, jak zapisywać liczbę kroków wstawianych danych:
suspend fun insertSteps(healthConnectClient: HealthConnectClient) {
try {
val stepsRecord = StepsRecord(
count = 120,
startTime = START_TIME,
endTime = END_TIME,
startZoneOffset = START_ZONE_OFFSET,
endZoneOffset = END_ZONE_OFFSET
)
healthConnectClient.insertRecords(listOf(stepsRecord))
} catch (e: Exception) {
// Run error handling here
}
}
Zaktualizuj dane
Jeśli musisz zmienić co najmniej jeden rekord, zwłaszcza gdy musisz synchronizować magazyn danych aplikacji z danymi z Health Connect, możesz zaktualizować swoje 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 to konieczne przy aktualizowaniu danych. Po utworzeniu każda wartość Record
w Health Connect ma swoje pole metadata
. Do synchronizacji mają znaczenie:
Właściwości | Opis |
---|---|
id
|
Każdy Record w Health Connect ma unikalną wartość id .Health Connect wypełni tę wartość automatycznie podczas wstawiania nowego rekordu. |
lastModifiedTime
|
W każdej pozycji Record rejestruje się również czas ostatniej modyfikacji rekordu.Health Connect uzupełni tę wartość automatycznie. |
clientRecordId
|
Z każdym identyfikatorem Record może być powiązany unikalny identyfikator, który będzie służyć jako odwołanie w magazynie danych aplikacji.
Twoja aplikacja ma tę wartość. |
clientRecordVersion
|
Jeśli rekord ma clientRecordId , właściwość clientRecordVersion może być używana do zapewnienia synchronizacji danych z wersją w magazynie danych aplikacji.Twoja aplikacja ma tę wartość. |
Zaktualizuj przez identyfikator rekordu
Aby zaktualizować dane, przygotuj najpierw wymagane rekordy. W razie potrzeby wprowadź zmiany w rekordach. Następnie wywołaj updateRecords
, aby wprowadzić zmiany.
Z przykładu poniżej dowiesz się, jak zaktualizować dane. W tym celu każdy rekord ma wartość przesunięcia strefy dostosowywaną 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)
}
client.updateRecords(newStepsRecords)
} catch (e: Exception) {
// Run error handling here
}
}
Wstaw za pomocą identyfikatora rekordu klienta
Jeśli używasz opcjonalnych wartości identyfikatora rekordu klienta i wersji rekordu klienta, zalecamy użycie insertRecords
zamiast updateRecords
.
Funkcja insertRecords
może wyświetlać dane przez upsert.
Jeśli dane istnieją w Health Connect na podstawie podanego zestawu identyfikatorów rekordów klienta, zostaną zastąpione. W przeciwnym razie jest zapisywany jako nowe dane.
Ten scenariusz jest przydatny, gdy chcesz zsynchronizować dane z magazynu danych aplikacji z Health Connect.
Ten przykład pokazuje, jak wykonać upsert na danych pobranych z magazynu 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(
// Assign parameters for this record
metadata = Metadata(
clientRecordId = cid
)
)
appStepsRecords.add(sr)
// ...
return appStepsRecords
}
suspend fun upsertSteps(
healthConnectClient: HealthConnectClient,
newStepsRecords: ArrayList<StepsRecord>
) {
try {
healthConnectClient.insertRecords(newStepsRecords)
} catch (e: Exception) {
// Run error handling here
}
}
Potem możesz je wywoływać w wątku głównym.
upsertSteps(healthConnectClient, pullStepsFromDatastore())
Sprawdzanie wartości w wersji rekordu klienta
Jeśli proces wprowadzania danych przez upsert obejmuje wersję rekordu klienta, Health Connect przeprowadza testy porównawcze wartości clientRecordVersion
. Jeśli wersja z wstawionych danych jest wyższa niż wersja z istniejących danych, zachodzi upsert. W przeciwnym razie zmiana zostanie zignorowana, a wartość pozostaje taka sama.
Aby w danych uwzględnić obsługę wersji, musisz podać Metadata.clientRecordVersion
z wartością Long
opartą na Twojej logice obsługi wersji.
val sr = StepsRecord(
count = count,
startTime = startTime,
startZoneOffset = startZoneOffset,
endTime = endTime,
endZoneOffset = endZoneOffset,
metadata = Metadata(
clientRecordId = cid,
clientRecordVersion = version
)
)
Upsert nie zwiększają automatycznie wartości version
po każdej zmianie, co zapobiega nieoczekiwanym przypadkom zastępowania danych. Musisz więc ręcznie
podać mu większą wartość.
Sprawdzone metody zapisu danych
Aplikacje mogą zapisywać w Health Connect tylko dane pochodzące od siebie.
Jeśli dane w Twojej aplikacji zostały zaimportowane z innej aplikacji, obowiązkiem tej aplikacji jest zapisanie własnych danych w Health Connect.
Warto też wdrożyć logikę, która obsługuje wyjątki zapisu, na przykład dane spoza granic lub wewnętrzny błąd systemu. Strategie ponawiania i ponawiania prób możesz zastosować w mechanizmie planowania zadań. Jeśli wysyłanie wiadomości do Health Connect się nie powiedzie, upewnij się, że aplikacja może przejść poza ten punkt eksportu. Nie zapomnij zapisać i zgłosić błędów, aby ułatwić diagnostykę.
Przy śledzeniu danych możesz skorzystać z kilku sugestii w zależności od tego, jak aplikacja zapisuje dane.
Śledzenie pasywne
Dotyczy to aplikacji, które wykonują pasywne śledzenie aktywności fizycznej lub zdrowia, np. rejestrują kroki lub tętno w trybie ciągłym w tle.
Aplikacja musi okresowo zapisywać dane w Health Connect w ten sposób:
- Przy każdej synchronizacji zapisuj tylko nowe dane i zaktualizowane dane, które zostały zmodyfikowane od ostatniej synchronizacji.
- Podziel żądania na fragment do maksymalnie 1000 rekordów na żądanie zapisu.
- Za pomocą
WorkManager
zaplanuj okresowe zadania w tle, które będą obejmować co najmniej 15 minut. Ogranicz zadania tak, aby były uruchamiane tylko wtedy, gdy urządzenie jest bezczynne 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
Dotyczy to aplikacji, które śledzą zdarzenia na podstawie zdarzeń, np. ćwiczeń i snu, lub generują ręcznie dane użytkownika, np. odżywianie. Rekordy te są tworzone, gdy aplikacja działa na pierwszym planie lub w rzadkich sytuacjach, gdy aplikacja jest używana kilka razy dziennie.
Sprawdź, czy aplikacja nie działa w Health Connect przez cały czas trwania zdarzenia.
Dane należy zapisywać w Health Connect na 1 z 2 sposobów:
- Zsynchronizuj dane z Health Connect po zakończeniu zdarzenia. Na przykład: synchronizuj dane, gdy użytkownik zakończy śledzoną sesję ćwiczeniową.
- Zaplanuj jednorazowe zadanie za pomocą
WorkManager
, aby później zsynchronizować dane.
Sprawdzone metody dotyczące szczegółowości i częstotliwości zapisów
Zapisując dane w Health Connect, używaj odpowiedniej rozdzielczości. Wybór odpowiedniej rozdzielczości pomaga zmniejszyć obciążenie pamięci masowej, jednocześnie zachowując spójność i dokładność danych. Rozpoznawanie danych obejmuje 2 kwestie:
- Częstotliwość zapisów: jak często aplikacja przekazuje nowe dane do Health Connect. np. zapisywać nowe dane co 15 minut.
- Szczegółowość zapisanych danych: jak często przesyłane dane były próbkowane. Na przykład zapisuj próbki tętna co 5 s. Nie każdy typ danych wymaga takiej samej częstotliwości próbkowania. Modyfikowanie danych o liczbie kroków co sekundę ma niewielkie korzyści w porównaniu z mniejszym cyklem, np. co 60 sekund. Wyższe częstotliwości próbkowania mogą jednak zapewniać użytkownikom bardziej szczegółowe i szczegółowe dane dotyczące zdrowia i aktywności fizycznej. Częstotliwość próbkowania powinna zapewniać równowagę między szczegółami a skutecznością.
Zapisuj dane monitorowane w ciągu dnia
W przypadku danych zbieranych na bieżąco (np. kroków) aplikacja powinna zapisywać się w Health Connect co najmniej co 15 minut w ciągu dnia.
Typ danych |
Jednostka |
Oczekiwana |
Przykład |
Kroki |
kroki |
Co minutę |
23:14–23:15 – 5 kroków 23:16-23:17 – 22 kroki 23:17–23:18 – 8 kroków |
Kadencja kroków |
kroki/min |
Co minutę |
23:14–23:15 – 5 kr./min 23:16–23:17 – 22 kr./min 23:17–23:18 – 20:00 |
Pchnięcia wózka inwalidzkiego |
wypychanie |
Co minutę |
23:14–23:15 – 5 uderzeń 23:16–23:17 – 22 pchnięcia 23:17–23:18 – 8 pchnięć |
Aktywne kalorie |
Kalorie |
Co 15 minut |
23:15 - 23:30 - 2 kalorie 23:30 - 23:45 - 25 kcal 23:45 - 00:00 - 5 kalorii |
Wszystkie spalone kalorie |
Kalorie |
Co 15 minut |
23:15 - 23:30 - 16 kalorii 23:30 - 23:45 - 16 kalorii 23:45 - 00:00 - 16 kalorii |
Odległość |
km/min |
Co minutę |
23:14–23:15 – 0,008 km 23:16-23:16-0,021 km 23:17–23:18 – 0,012 km |
Przebyte przewyższenie |
min |
Co minutę |
20:36-20:37-3,048 20:39-20:40-3,048 23:23–23:24 – 9,144 |
Pokonane piętra |
piętra |
Co minutę |
23:14–23:15 – 5 pięter 23:16–23:16 – 22 piętra 23:17–23:18 – 8 pięter |
Tętno |
uderz./min |
Co minutę |
6:11–55 uderz./min |
Zmienność rytmu serca |
ms |
Co minutę |
6:11–23 ms |
Częstość oddychania |
oddechy/min |
Co minutę |
23:14-23:15 – 60 oddechów/min 23:16-23:16 – 62 oddechy/min 23:17-23:18 – 64 oddechy/min |
Nasycenie tlenem |
% |
Co godzinę |
6:11–95,208% |
Zapisywanie sesji
Dane powinny być zapisywane w Health Connect po zakończeniu treningu lub sesji snu.
Sprawdzoną metodą jest zapisanie każdej sesji snu lub sesji ćwiczeń za pomocą urządzenia do nagrywania i odpowiednich metadanych, np. RecordingMethod
.
Zgłoszenie powinno być zgodne przynajmniej ze wskazówkami podanymi w kolumnie „Oczekiwane” poniżej. Jeśli to możliwe, postępuj zgodnie z „najlepszymi” wskazówkami.
Dane śledzone podczas ćwiczenia
Typ danych |
Jednostka |
Oczekiwana |
Pozdrawiam |
Przykład |
Kroki |
kroki |
Co minutę |
Co sekundę |
23:14–23:15 – 5 kroków 23:16-23:17 – 22 kroki 23:17–23:18 – 8 kroków |
Kadencja kroków |
kroki/min |
Co minutę |
Co sekundę |
23:14–23:15 – 35 kr./min 23:16–23:17 – 37 kr./min 23:17–23:18 – 40 kr./min |
Pchnięcia wózka inwalidzkiego |
wypychanie |
Co minutę |
Co sekundę |
23:14–23:15 – 5 uderzeń 23:16–23:17 – 22 pchnięcia 23:17–23:18 – 8 pchnięć |
Ścieżka rowerowa |
obr./min |
Co minutę |
Co sekundę |
23:14–23:15 – 65 obr./min 23:16-23:17 - 70 obr./min 23:17-23:18-68 obr./min |
Zasilanie |
waty |
Co minutę |
Co sekundę |
23:14–23:15 – 250 watów 23:16–23:17 – 255 watów 23:17–23:18 – 245 watów |
Szybkość |
km/min |
Co minutę |
Co sekundę |
23:14–23:15 – 0,3 km/min 23:16-23:17 - 0,4 km/min 23:17-23:18 -0,4 km/min |
Odległość |
km/m |
Co minutę |
Co sekundę |
23:14–23:15 – 0,008 km 23:16-23:16-0,021 km 23:17–23:18 – 0,012 km |
Aktywne kalorie |
Kalorie |
Co minutę |
Co sekundę |
23:14-23:15 - 20 kalorii 23:16 - 23:17 - 20 kalorii 23:17 - 23:18 - 25 kcal |
Wszystkie spalone kalorie |
Kalorie |
Co minutę |
Co sekundę |
23:14-23:15 - 36 kalorii 23:16 - 23:17 - 36 kcal 23:17 - 23:18 - 41 kcal |
Przebyte przewyższenie |
min |
Co minutę |
Co sekundę |
20:36-20:37-3,048 20:39-20:40-3,048 23:23–23:24 – 9,144 |
Trasy ćwiczeń |
szer./dł./sł./sł. |
Co 3–5 sekund |
Co sekundę |
|
Tętno |
uderz./min |
Co minutę |
Co sekundę |
23:14–23:15–150 uderz./min 23:16–23:17–152 uderz./min 23:17–23:18–155 uderz./min |
Dane śledzone podczas snu
Typ danych |
Jednostka |
Oczekiwane próbki |
Przykład |
Ocena snu |
etapie |
Szczegółowe przedziały czasu dla poszczególnych faz snu |
23:46–23:50 – obudzenie 23:50–23:56 – sen płytki 23:56-00:16 – sen głęboki |
Tętno spoczynkowe |
uderz./min |
Jedna wartość dzienna (oczekiwana z rana) |
6:11–60 uderz./min |
Nasycenie tlenem |
% |
Jedna wartość dzienna (oczekiwana z rana) |
6:11–95,208% |