Interfejs Google Health API to kompleksowe rozwiązanie stworzone od podstaw, które zapewnia deweloperom solidny dostęp do szerokiej gamy danych dotyczących zdrowia użytkowników i różnych typów danych, na które użytkownicy wyrazili zgodę. Interfejs Google Health API korzysta z nowej konsoli do rejestrowania aplikacji, Google OAuth 2.0, nowych typów danych, nowego schematu punktów końcowych i nowego formatu odpowiedzi.
Ten przewodnik ma pomóc deweloperom w migracji dotychczasowych aplikacji korzystających z interfejsu Fitbit Web API do nowego interfejsu Google Health API. Zawiera rekomendacje, które pomogą Ci przeprowadzić bezproblemową migrację i zatrzymać użytkowników.
Dlaczego warto przeprowadzić migrację?
To nie jest tylko aktualizacja, ale strategiczny krok, który zapewni bezpieczeństwo Twoich aplikacji i przygotuje je na przyszłe postępy w dziedzinie technologii zdrowotnych. Oto niektóre zalety korzystania z interfejsu Google Health API:
- Dostęp do kompleksowych danych: uzyskaj dostęp do szerokiego zakresu danych dotyczących zdrowia użytkowników, na których udostępnianie wyrazili zgodę, oraz do różnych typów danych.
- Ulepszone zabezpieczenia: zgodność ze sprawdzonymi metodami Google w zakresie bezpieczeństwa, prywatności i tożsamości.
- Spójność: eliminuje starsze niespójności w formatach danych, strefach czasowych, jednostkach miary i obsłudze błędów, co zapewnia deweloperom bardziej intuicyjną obsługę.
- Skalowalność i odporność na przyszłe zmiany: usługa została zaprojektowana tak, aby można ją było skalować w celu spełnienia przyszłych wymagań, i obsługuje nowoczesne protokoły, takie jak gRPC.
Przejście z interfejsu Fitbit Web API na interfejs Google Health API wymaga nie tylko zmian technicznych. Ze względu na przejście na nową bibliotekę protokołu OAuth nie można przenieść istniejących tokenów dostępu i tokenów odświeżania, co wymaga od użytkowników ponownego wyrażenia zgody na zaktualizowaną integrację.
Obsługa obu metod logowania
Ponieważ interfejsy Fitbit Web API i Google Health API używają różnych systemów do obsługi logowania użytkowników, gdy interfejsy Fitbit Web API są nadal aktywne, Twoja aplikacja będzie musiała tymczasowo obsługiwać obie metody uwierzytelniania w przypadku wszystkich użytkowników.
Zamiast prosić o dane bezpośrednio z aplikacji, zaimplementuj warstwę, która decyduje, czy w przypadku konkretnego użytkownika ma komunikować się z interfejsem Fitbit Web API czy Google Health API. Dzięki temu reszta aplikacji nie będzie musiała zajmować się szczegółami.
Zaktualizuj bazę danych użytkowników, aby zawierała flagę (np. oauth_type) identyfikującą system logowania, którego używają.
- W przypadku nowych użytkowników: automatycznie skonfiguruj dla nich nowy interfejs Google Health API (
oauth_type: google). - Dotychczasowi użytkownicy: pozostaw ich na interfejsie Fitbit Web API, dopóki nie zaktualizują zgody (
oauth_type: fitbit).
| Scenariusz użytkownika | oauth_type stan |
Aktywny strumień interfejsu API | Wymagane działanie |
|---|---|---|---|
| Wprowadzenie nowego użytkownika | google |
Tylko interfejs Google Health API | Uruchom Google OAuth w przeglądarce systemowej i zmapuj identyfikatory za pomocą users.getIdentity. |
| Dotychczasowy użytkownik Fitbita (jeszcze nie przeszedł na konto Google) | fitbit |
Tylko Fitbit Web API | Kontynuuj synchronizację z Fitbit Web API. Wyświetlaj w aplikacji prośbę o uaktualnienie, którą można zamknąć. |
| Dotychczasowy użytkownik Fitbita kończący migrację | fitbit → google |
Przejście na interfejs Google Health API | Sprawdź przyznane zakresy, wywołaj users.getIdentity (legacyUserId → healthUserId), przełącz oauth_type na google i natychmiast unieważnij starsze tokeny Fitbita. |
Aby nie zakłócać pracy użytkowników, zalecamy, aby nie zmuszać wszystkich do wylogowania się i ponownego zalogowania. Zamiast tego:
- Gdy użytkownik, który pozostaje połączony z interfejsami Fitbit Web API, korzysta z Twojej aplikacji, wyświetl mu przyjazne powiadomienie zachęcające do zaktualizowania połączenia.
- Gdy użytkownik zaakceptuje działanie aktualizacji, natychmiast uruchom proces logowania w Google Health.
- Po pomyślnym zalogowaniu się przez Google zapisz nowe dane logowania Google w profilu użytkownika, zmień flagę
oauth_typezfitbitnagooglei natychmiast wyłącz starszą synchronizację, automatycznie unieważniając starsze tokeny Fitbita, aby zapobiec powielaniu danych i podwójnemu łączeniu.
Zapewnianie ciągłości danych
Podczas przenoszenia integracji ze starszej wersji interfejsu Fitbit Web API do interfejsu Google Health API aplikacje deweloperskie muszą uwzględniać zmianę struktur identyfikacji użytkowników.
Starsza wersja interfejsu Fitbit Web API identyfikuje konta za pomocą 6-znakowego ciągu alfanumerycznego (np. A1B2C3), natomiast interfejs Google Health API korzysta z healthUserId w formacie ciągu składającego się z maksymalnie 63 cyfr i znaków.
Aby wypełnić tę lukę bez utraty kontekstu użytkownika, deweloperzy mogą wysłać zapytanie do punktu końcowego getIdentity, aby uzyskać identyfikatory użytkowników Fitbita i Health.
Ten punkt końcowy zwraca ładunek zawierający zarówno legacyUserId, jak i nowy healthUserId, co umożliwia aplikacjom dynamiczne tworzenie mapowania między istniejącymi rekordami a nowym systemem kont.
Zarządzanie niepołączonymi kontami Google
Aby Twoja aplikacja mogła synchronizować dane za pomocą interfejsu Google Health API, użytkownik musi zalogować się w aplikacji mobilnej Google Health i połączyć Google Health ze swoim kontem Google. Zobacz Łączenie Google Health przed wyrażeniem zgody na OAuth. Protokół Google OAuth 2.0 uwierzytelnia każde prawidłowe konto Google podczas wyrażania zgody, dlatego nie może blokować kont, które nie mają jeszcze aktywnego profilu Google Health.
Jeśli użytkownik wyrazi zgodę na protokół OAuth Google przed utworzeniem profilu Google Health lub przed przeniesieniem starszego konta Fitbit na konto Google, wywołanie users.getIdentity lub punktu końcowego danych zwróci błąd HTTP 400 Bad Request ze stanem FAILED_PRECONDITION i przyczyną ACCOUNT_NOT_LINKED:
{
"error": {
"code": 400,
"message": "The account is not linked to Google Health.",
"status": "FAILED_PRECONDITION",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "ACCOUNT_NOT_LINKED",
"domain": "health.googleapis.com",
"metadata": {
"redirect_uri": "https://fitbit.google.com/auth/signup"
}
}
]
}
}
Aby sprawdzić dostęp do konta i rozwiązać ten problem:
- Wymień kod autoryzacji OAuth na tokeny i natychmiast wywołaj metodę
users.getIdentity(GET https://health.googleapis.com/v4/users/me/identity), zanim oznaczysz konto jako połączone w interfejsie aplikacji. - Jeśli
users.getIdentitylub wywołanie synchronizacji danych w tle zwraca kod HTTP400z przyczynąACCOUNT_NOT_LINKED, nie oznaczaj konta jako połączonego. Jeśli użytkownik przechodzi ze starszej wersji interfejsu Fitbit Web API, zachowaj jego dotychczasowe połączenie z Fitbitem i nie unieważniaj jego starszych tokenów Fitbita. Wyświetlaj komunikat z wezwaniem do działania, który jest skierowany zarówno do nowych użytkowników, którzy nigdy nie utworzyli konta Google Health ani Fitbit, jak i do dotychczasowych użytkowników Fitbita, którzy nie przeszli jeszcze na konto Google:
„Twoje konto Google nie jest jeszcze połączone z Google Health. Otwórz aplikację mobilną Google Health i zaloguj się na konto Google, aby utworzyć profil, lub przenieś dotychczasowe konto Fitbit na konto Google, a następnie wróć tutaj, aby się połączyć”.
Udostępnij przycisk wezwania do działania, który otwiera
redirect_uriz metadanych błędu (https://fitbit.google.com/auth/signup), lub przekieruj użytkowników starszych kont Fitbit do artykułu pomocy na temat migracji konta Fitbit.
Uzupełnianie danych historycznych
Jeśli użytkownik nie uwierzytelni się w nowych punktach końcowych interfejsu Google Health API przed wyłączeniem starszych punktów końcowych, jego dane będą nadal dostępne, o ile będzie on nadal synchronizować swoje urządzenie z aplikacją Google Health. Możesz jednak mieć lukę w danych tego użytkownika.
Aby uzupełnić dane, gdy użytkownik ponownie uwierzytelni się w nowych punktach końcowych, możesz użyć interfejsu Google Health API do uzupełnienia danych historycznych. Wskazówki znajdziesz w artykule Wykonywanie zapytań na danych historycznych.
Przykładowa implementacja migracji i łączenia
Poniższa implementacja referencyjna pokazuje, jak obsługiwać wywołanie zwrotne OAuth, sprawdzać częściową lub zerową zgodę, rozwiązywać tożsamość użytkownika za pomocą users.getIdentity (w tym obsługi HTTP 400 ACCOUNT_NOT_LINKED), zapobiegać podwójnemu łączeniu przez unieważnianie starszych tokenów Fitbita i kierować żądania danych za pomocą oauth_type:
import requests
GOOGLE_HEALTH_IDENTITY_URL = "https://health.googleapis.com/v4/users/me/identity"
FITBIT_REVOKE_URL = "https://api.fitbit.com/oauth2/revoke"
DEFAULT_SIGNUP_URL = "https://fitbit.google.com/auth/signup"
def complete_google_health_linking(user_record: dict, oauth_token_response: dict, fitbit_client_creds: str) -> dict:
"""Completes Google Health account linking and migrates legacy Fitbit users."""
# 1. Check granted scopes (handle zero consent and partial consent)
granted_scopes = set(oauth_token_response.get("scope", "").split())
health_scopes = {s for s in granted_scopes if s.startswith("https://www.googleapis.com/auth/googlehealth")}
if not health_scopes:
return {
"status": "MISSING_PERMISSIONS",
"ui_action": "ROUTE_TO_MISSING_PERMISSIONS_SCREEN",
"message": "At least one permission is required to connect to Google Health.",
}
access_token = oauth_token_response["access_token"]
# 2. Call users.getIdentity and handle HTTP 400
# (status: "FAILED_PRECONDITION", ErrorInfo.reason: "ACCOUNT_NOT_LINKED").
identity_resp = requests.get(
GOOGLE_HEALTH_IDENTITY_URL,
headers={"Authorization": f"Bearer {access_token}", "Accept": "application/json"},
timeout=10,
)
if identity_resp.status_code == 400:
error_payload = identity_resp.json().get("error", {})
if error_payload.get("status") == "FAILED_PRECONDITION":
for detail in error_payload.get("details", []):
if detail.get("reason") == "ACCOUNT_NOT_LINKED":
redirect_uri = detail.get("metadata", {}).get("redirect_uri", DEFAULT_SIGNUP_URL)
return {
"status": "ACCOUNT_NOT_LINKED",
"ui_action": "PROMPT_LINK_GOOGLE_HEALTH_ACCOUNT",
"redirect_uri": redirect_uri,
"message": (
"Your Google Account isn't linked to Google Health yet. "
"Open the Google Health mobile app and sign in with your Google Account "
"to create a profile, or move your existing Fitbit account to your "
"Google Account, then return here to connect."
),
}
identity_resp.raise_for_status()
identity = identity_resp.json()
# 3. Verify legacyUserId and map legacyUserId -> healthUserId.
previous_oauth_type = user_record.get("oauth_type")
legacy_fitbit_refresh_token = user_record.get("fitbit_refresh_token")
existing_legacy_id = user_record.get("legacy_user_id")
returned_legacy_id = identity.get("legacyUserId")
legacy_id_verified = bool(returned_legacy_id) and (
not existing_legacy_id or returned_legacy_id == existing_legacy_id
)
if previous_oauth_type == "fitbit" and not legacy_id_verified:
return {
"status": "LEGACY_ID_MISMATCH",
"ui_action": "PROMPT_VERIFY_FITBIT_MIGRATION_ACCOUNT",
"message": (
"The Google Account you signed in with does not match your linked "
"Fitbit account. Sign in with the Google Account linked to your "
"Fitbit profile."
),
}
# 4. Cut over oauth_type and revoke legacy Fitbit token once verified.
user_record.update({
"health_user_id": identity.get("healthUserId") or user_record.get("health_user_id"),
"legacy_user_id": returned_legacy_id or existing_legacy_id,
"google_access_token": access_token,
"google_refresh_token": oauth_token_response.get("refresh_token"),
"granted_scopes": list(health_scopes),
"oauth_type": "google",
"fitbit_access_token": None,
"fitbit_refresh_token": None,
})
if previous_oauth_type == "fitbit" and legacy_fitbit_refresh_token:
requests.post(
FITBIT_REVOKE_URL,
headers={
"Authorization": f"Basic {fitbit_client_creds}",
"Content-Type": "application/x-www-form-urlencoded",
},
data={"token": legacy_fitbit_refresh_token},
timeout=10,
)
return {
"status": "CONNECTED",
"health_user_id": user_record["health_user_id"],
"granted_scopes": user_record["granted_scopes"],
}
Komunikacja i harmonogram
Aby pomóc użytkownikom przejść z dotychczasowego protokołu OAuth Fitbita na nowy protokół OAuth Google, postępuj zgodnie z tymi sprawdzonymi metodami.
Komunikacja skupiona na wartości
Nie zaczynaj od „Zaktualizowaliśmy nasz interfejs API”, ale od korzyści płynących z integracji danych z Google Health z aplikacją. Pamiętaj jednak, aby poinformować użytkowników, że jeśli chcą synchronizować dane, muszą ponownie przejść uwierzytelnianie:
- Wyraźnie wyjaśnij, jakie funkcje są dostępne w Twojej aplikacji dzięki integracji, i dostosuj przekaz do korzyści, jakie użytkownik może odnieść z tych funkcji.
- Skup się na funkcjach i podaj przykłady zastosowania zamiast szczegółów technicznych dotyczących implementacji.
- Nie mów: „Nie będziesz mieć możliwości połączenia się z interfejsem Fitbit API”.
- Do say: "To continue seeing detailed workouts with heart rate data, re-consent to the Google Health APIs."
Kiedy powiadamiać użytkowników
We wszystkich komunikatach dla użytkowników przestrzegaj wytycznych dotyczących marki Google Health i używaj banerów, kart lub alertów, które można zamknąć.
- Nie wyświetlaj ekranu zgody, gdy użytkownik jest w trakcie treningu lub ręcznie coś rejestruje.
- Wymagaj ponownego wyrażenia zgody dopiero po kilku tygodniach ostrzeżeń, co zbiegnie się z oficjalnymi terminami wycofania interfejsu Fitbit Web API.
- Jeśli użytkownik nie wyrazi ponownie zgody po ostatecznym terminie, zapewnij mu możliwość łatwego przywrócenia dostępu. Wyświetl komunikat pomocy na banerze, karcie lub w etykietce, aby wyjaśnić, dlaczego brakuje danych i jak rozwiązać ten problem.
Planowanie limitów częstotliwości przyznawania tokenów OAuth
Gdy dotychczasowi użytkownicy Fitbita ponownie wyrażą zgodę na korzystanie z interfejsu Google Health API, każde upoważnienie użytkownika będzie wliczane do limitu przyznawania tokenów OAuth w projekcie Google Cloud. Ten limit określa, ilu użytkowników może autoryzować Twoją aplikację na minutę i w ciągu 24-godzinnego okna.
Jeśli spodziewasz się, że w ciągu 24 godzin podczas migracji przekroczysz 10 000 rejestracji lub ponownych uwierzytelnień użytkowników, wykonaj te czynności, aby uniknąć przekroczenia limitów liczby żądań OAuth:
- Monitoruj wykorzystanie przyznanych tokenów w projekcie w chmurze Google.
- Rozłóż w czasie powiadomienia o migracji w aplikacji, aby nie przekroczyć dziennego limitu przyznanych środków.
- Zanim poprosisz duże grupy użytkowników o ponowne uwierzytelnienie, poproś o zwiększenie limitu przyznawania tokenów OAuth. Instrukcje sprawdzania wykorzystania i wysyłania prośby o zwiększenie limitu znajdziesz w artykule Ograniczenia liczby żądań w aplikacji OAuth.