Ten przewodnik jest zgodny z wersją Health Connect 1.1.0-alpha12.
Większość aplikacji zintegrowanych z Health Connect ma własny magazyn danych, który służy jako źródło wiarygodnych informacji. Health Connect oferuje sposoby synchronizacji aplikacji.
W zależności od architektury aplikacji proces synchronizacji może obejmować niektóre lub wszystkie z tych działań:
- Przekazywanie nowych lub zaktualizowanych danych z pamięci danych aplikacji do Health Connect.
- Pobierz zmiany danych z Health Connect do magazynu danych aplikacji.
- Usuwanie danych z Health Connect, gdy zostaną one usunięte z pamięci danych aplikacji.
W każdym przypadku upewnij się, że proces synchronizacji zapewnia spójność danych w Health Connect i w pamięci danych aplikacji.
Przekazywanie danych do Health Connect
Pierwsza część procesu synchronizacji polega na przekazywaniu danych z pamięci danych aplikacji do pamięci danych Health Connect.
Przygotowywanie danych
Zwykle rekordy w pamięci danych aplikacji zawierają te informacje:
- unikalny klucz, np.
UUID
; - wersję lub sygnaturę czasową;
Podczas synchronizowania danych z Health Connect identyfikuj i przesyłaj tylko te dane, które zostały wstawione, zaktualizowane lub usunięte od czasu ostatniej synchronizacji.
Zapisywanie danych w Health Connect
Aby przekazywać dane do Health Connect, wykonaj te czynności:
- Uzyskaj listę nowych, zaktualizowanych lub usuniętych wpisów z pamięci danych aplikacji.
- Dla każdego wpisu utwórz obiekt
Record
odpowiedni do danego typu danych. Możesz na przykład utworzyć obiektWeightRecord
dla danych związanych z wagą. Określ obiekt
Metadata
dla każdego elementuRecord
. Obejmuje toclientRecordId
, czyli identyfikator z pamięci danych aplikacji, którego możesz używać do jednoznacznego identyfikowania rekordu. Możesz w tym celu użyć istniejącego unikalnego klucza. Jeśli Twoje dane są wersjonowane, podaj teżclientRecordVersion
, który jest zgodny z wersjonowaniem używanym w Twoich danych. Jeśli nie jest wersjonowany, możesz użyć wartościLong
bieżącej sygnatury czasowej.val recordVersion = 0L // Specify as needed // The clientRecordId is an ID that you choose for your record. This // is often the same ID you use in your app's datastore. val clientRecordId = "<your-record-id>" val record = WeightRecord( metadata = Metadata.activelyRecorded( clientRecordId = clientRecordId, clientRecordVersion = recordVersion, device = Device(type = Device.TYPE_SCALE) ), weight = Mass.kilograms(62.0), time = Instant.now(), zoneOffset = ZoneOffset.UTC, ) healthConnectClient.insertRecords(listOf()(record))
Wstawiaj lub aktualizuj dane w Health Connect za pomocą
insertRecords
. Upsertowanie danych oznacza, że wszelkie istniejące dane w Health Connect zostaną nadpisane, o ile wartościclientRecordId
znajdują się w magazynie danych Health Connect, a wartośćclientRecordVersion
jest wyższa niż istniejąca wartość. W przeciwnym razie dane wstawione lub zaktualizowane zostaną zapisane jako nowe dane.healthConnectClient.insertRecords(arrayListOf(record))
Aby dowiedzieć się więcej o praktycznych aspektach przesyłania danych, zapoznaj się ze sprawdzonymi metodami zapisywania danych.
Przechowywanie identyfikatorów Health Connect
Jeśli Twoja aplikacja odczytuje też dane z Health Connect, po wstawieniu lub zaktualizowaniu rekordów zapisz identyfikator id
Health Connect. Jest to wymagane do przetwarzania usunięć podczas pobierania zmian danych z Health Connect.id
Funkcja insertRecords
zwraca element InsertRecordsResponse
, który zawiera listę wartości id
.
Użyj odpowiedzi, aby uzyskać identyfikatory rekordów i je zapisać.
val response = healthConnectClient.insertRecords(arrayListOf(record))
for (recordId in response.recordIdsList) {
// Store recordId to your app's datastore
}
Pobieranie danych z Health Connect
Drugą częścią procesu synchronizacji jest pobieranie zmian danych z Health Connect do magazynu danych aplikacji. Zmiany danych mogą obejmować aktualizacje i usunięcia.
Pobieranie tokena zmian
Aby pobrać listę zmian z Health Connect, aplikacja musi śledzić tokeny Changes. Możesz ich używać podczas wysyłania żądań Changes, aby zwracać zarówno listę zmian danych, jak i nowy token Changes, który będzie używany przy następnym żądaniu.
Aby uzyskać token Changes, wywołaj funkcję getChangesToken
i podaj wymagane typy danych.
val changesToken = healthConnectClient.getChangesToken(
ChangesTokenRequest(recordTypes = setOf(WeightRecord::class))
)
Sprawdzanie zmian danych
Po uzyskaniu tokena Changes użyj go, aby pobrać wszystkie Changes. Zalecamy utworzenie pętli, która przejdzie przez wszystkie zmiany i sprawdzi, czy są dostępne zmiany danych. Aby to zrobić:
- Wywołaj funkcję
getChanges
, używając tokena, aby uzyskać listę zmian. - Sprawdź, czy typ zmiany to
UpsertionChange
czyDeletionChange
, i wykonaj niezbędne operacje.- W przypadku
UpsertionChange
uwzględniaj tylko zmiany, które nie pochodzą z aplikacji do dzwonienia, aby uniknąć ponownego importowania danych.
- W przypadku
- Przypisz kolejny token Changes jako nowy token.
- Powtarzaj kroki 1–3, aż nie będzie już żadnych zmian.
- Zapisz kolejny token i zarezerwuj go na potrzeby przyszłego importu.
suspend fun processChanges(token: String): String {
var nextChangesToken = token
do {
val response = healthConnectClient.getChanges(nextChangesToken)
response.changes.forEach { change ->
when (change) {
is UpsertionChange ->
if (change.record.metadata.dataOrigin.packageName != context.packageName) {
processUpsertionChange(change)
}
is DeletionChange -> processDeletionChange(change)
}
}
nextChangesToken = response.nextChangesToken
} while (response.hasMore)
// Return and store the changes token for use next time.
return nextChangesToken
}
Aby dowiedzieć się więcej o praktycznych aspektach pobierania danych, zapoznaj się ze sprawdzonymi metodami synchronizowania danych.
Przetwarzanie zmian w danych
odzwierciedlać zmiany w pamięci danych aplikacji; W przypadku UpsertionChange
użyj id
i lastModifiedTime
z metadata
, aby wstawić lub zaktualizować rekord.
W przypadku DeletionChange
użyj id
, aby usunąć rekord.
Wymaga to zapisania rekordu id
zgodnie z instrukcjami podanymi w sekcji Przechowywanie identyfikatorów Health Connect.
Usuwanie danych z Health Connect
Gdy użytkownik usunie swoje dane z Twojej aplikacji, upewnij się, że zostaną one również usunięte z Health Connect. Aby to zrobić, użyj deleteRecords
. Funkcja ta przyjmuje typ rekordu i listę wartości id
i clientRecordId
, co ułatwia usuwanie wielu danych naraz. Dostępna jest też alternatywna funkcja deleteRecords
, która przyjmuje timeRangeFilter
.
Sprawdzone metody synchronizowania danych
Na proces synchronizacji wpływają te czynniki:
Wygaśnięcie tokena
Nieużywany token Changes wygasa w ciągu 30 dni, więc musisz używać strategii synchronizacji, która zapobiega utracie informacji w takim przypadku. Twoja strategia może obejmować te podejścia:
- Wyszukaj w pamięci danych aplikacji ostatnio użyty rekord, który zawiera też
id
z Health Connect. - Żądaj z Health Connect rekordów, które zaczynają się od określonego znacznika czasu, a następnie wstawiaj je lub aktualizuj w pamięci danych aplikacji.
- Poproś o token zmian, aby zarezerwować go na następny raz, gdy będzie potrzebny.
Zalecane strategie zarządzania zmianami
Jeśli Twoja aplikacja otrzymuje nieprawidłowe lub wygasłe tokeny Changes, zalecamy stosowanie tych strategii zarządzania w zależności od ich zastosowania w logice aplikacji:
- Odczytywanie i usuwanie duplikatów wszystkich danych Jest to najbardziej optymalna strategia.
- przechowywać sygnaturę czasową ostatniego odczytu danych z Health Connect;
- Po wygaśnięciu tokena ponownie odczytaj wszystkie dane od ostatniej sygnatury czasowej lub z ostatnich 30 dni. Następnie usuń zduplikowane dane, porównując je z wcześniej odczytanymi danymi za pomocą identyfikatorów.
- Najlepiej zaimplementować identyfikatory klientów, ponieważ są one wymagane w przypadku aktualizacji danych.
- Odczytuj tylko dane od ostatniej sygnatury czasowej odczytu. Powoduje to pewne rozbieżności w danych w okresie wygaśnięcia tokena zmian, ale okres ten jest krótszy i może trwać od kilku godzin do kilku dni.
- przechowywać sygnaturę czasową ostatniego odczytu danych z Health Connect;
- Po wygaśnięciu tokena odczytaj wszystkie dane od tej sygnatury czasowej.
- Usuń, a potem odczytaj dane z ostatnich 30 dni. Jest to bardziej zgodne z tym, co dzieje się podczas pierwszej integracji.
- Usuń wszystkie dane odczytane przez aplikację z Health Connect w ciągu ostatnich 30 dni.
- Po usunięciu ponownie odczytaj wszystkie te dane.
- Odczytaj dane z ostatnich 30 dni bez usuwania duplikatów. Jest to najmniej odpowiednia strategia, która powoduje wyświetlanie użytkownikom zduplikowanych danych.
- Usuń wszystkie dane odczytane przez aplikację z Health Connect w ciągu ostatnich 30 dni.
- Zezwalaj na zduplikowane wpisy.
Tokeny zmian typu danych
Jeśli aplikacja korzysta z więcej niż jednego typu danych niezależnie od siebie, użyj oddzielnych tokenów Changes dla każdego typu danych. Listy wielu typów danych używaj w interfejsie API synchronizacji zmian tylko wtedy, gdy te typy danych są używane razem lub wcale.
Odczyty na pierwszym planie
Aplikacje mogą odczytywać dane z Health Connect tylko wtedy, gdy są na pierwszym planie. Podczas synchronizowania danych z Health Connect dostęp do tej usługi może zostać w każdej chwili przerwany. Na przykład aplikacja musi obsługiwać przerwy w synchronizacji w trakcie odczytywania dużej ilości danych z Health Connect i kontynuować działanie przy następnym otwarciu.
Odczytywanie w tle
Możesz poprosić o uruchomienie aplikacji w tle i odczytywanie danych z Health Connect. Jeśli poprosisz o uprawnienie
Background Read
, użytkownik może przyznać aplikacji dostęp do odczytywania danych w tle.
Importowanie kodów czasowych
Ponieważ aplikacja nie może otrzymywać powiadomień o nowych danych, sprawdzaj, czy są dostępne nowe dane, w 2 momentach:
- Za każdym razem, gdy aplikacja staje się aktywna na pierwszym planie. W takim przypadku użyj zdarzeń cyklu życia.
- okresowo, gdy aplikacja działa na pierwszym planie; Powiadamiaj użytkowników o dostępności nowych danych, aby mogli zaktualizować ekran i odzwierciedlić zmiany.