Przewodnik po migracji

Interfejs Google Health API to nowy interfejs API stworzony od podstaw, który umożliwia deweloperom wysyłanie zapytań o dane użytkowników Fitbita. To nie tylko aktualizacja, ale strategiczne działanie, które ma zapewnić bezpieczeństwo i niezawodność Twoich aplikacji oraz przygotować je na przyszłe postępy w technologii medycznej. Interfejs API obsługuje nową konsolę do rejestrowania aplikacji, protokół Google OAuth 2.0, nowe typy danych, nowy schemat punktu końcowego i nowy format odpowiedzi.

Przewodnik ma pomóc deweloperom w migracji aplikacji korzystających z interfejsu Fitbit Web API do nowego interfejsu Google Health API.

Dlaczego warto przeprowadzić migrację?

Korzyści z korzystania z interfejsu API Google Health:

  • Zwiększone bezpieczeństwo: zgodność ze sprawdzonymi metodami Google w zakresie bezpieczeństwa, zgodność ze standardami Google dotyczącymi 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, aby zapewnić bardziej intuicyjne środowisko programistyczne.
  • Skalowalność i zabezpieczenie na przyszłość: zaprojektowany z myślą o skalowalności, aby sprostać przyszłym wymaganiom, i obsługuje nowoczesne protokoły, takie jak gRPC.

Rejestracja aplikacji

Wszystkie aplikacje korzystające z interfejsu Google Health API muszą być zarejestrowane w konsoli Google Cloud, która jest centralnym miejscem do zarządzania wszystkimi aplikacjami Google.

Instrukcje rejestracji aplikacji znajdziesz w sekcji Wprowadzenie. Oto różnice, które zauważysz podczas rejestrowania aplikacji.

Fitbit Web API Google Health API
Linki publiczne https://dev.fitbit.com/apps https://console.cloud.google.com
Dodawanie nowej aplikacji Kliknij Zarejestruj nową aplikację.
  1. Tworzenie projektu Google Cloud
  2. Włącz Google Health API
Podstawowe informacje Pola do wypełnienia:
  • Nazwa aplikacji
  • Opis
  • Adres URL witryny aplikacji
  • Organizacja
  • Adres URL witryny organizacji
  • Adres URL warunków korzystania z usługi
  • Adres URL polityki prywatności
 Pola do wypełnienia:
  • Nazwa aplikacji
  • Adres e-mail pomocy
  • Odbiorcy (wewnętrzni lub zewnętrzni)
  • Kontaktowy adres e-mail
  • Ikona logo
  • Adres URL witryny aplikacji
  • URL Polityki prywatności
  • Adres URL warunków korzystania z usługi
  • Autoryzowana domena
Typy aplikacji Deweloper musi wybrać:
  • Serwer
  • Klient
  • Prywatnie
  • Aplikacja internetowa
  • Android
  • Rozszerzenie do Chrome
  • iOS
  • Telewizory
  • Aplikacja komputerowa
  • Platforma uniwersalna systemu Windows
Identyfikator klienta Rejestracja po zapisaniu ustawień aplikacji zarejestrowane osobno,
Typ dostępu Uprawnienia do odczytu i zapisu są kontrolowane na poziomie aplikacji Uprawnienia do odczytu i zapisu są kontrolowane na poziomie zakresu.
Dodatkowe adresy URL
  • Adres URL przekierowania: witryna, do której użytkownicy są przekierowywani po autoryzacji zakresów.
  • Autoryzowane źródła JavaScriptu: źródło HTTP, które hostuje aplikację internetową.
  • Adres URL przekierowania: witryna, do której użytkownicy są przekierowywani po autoryzacji zakresów.

Implementacja OAuth

Aplikacje korzystające z interfejsu Google Health API obsługują tylko biblioteki klienta Google OAuth2. Biblioteki klienta są dostępne w przypadku popularnych platform, co ułatwia wdrażanie OAuth 2.0. Różnice między bibliotekami Google OAuth2 a bibliotekami OAuth2 typu open source są następujące:

Fitbit Web API Google Health API
Obsługa biblioteki OAuth2 Oprogramowanie typu open source Biblioteki klienta Google OAuth2
Funkcjonalność Niespójne na różnych platformach Spójność na różnych platformach
URL autoryzacji https://www.fitbit.com/oauth2/authorize https://accounts.google.com/o/oauth2/v2/auth
URL tokena https://api.fitbit.com/oauth2/token https://oauth2.googleapis.com/token
Okres ważności tokena dostępu 8 godzin 1 godzina
Rozmiar tokena dostępu 1024 bajty 2048 bajtów
Token odświeżania Tokeny odświeżania są generowane podczas korzystania z przepływu przyznawania kodu autoryzacji. Dla użytkownika można wygenerować tylko 1 token odświeżania. Tokeny nigdy nie wygasają i można ich użyć tylko raz. Aby wygenerować token odświeżania, ciąg autoryzacji musi zawierać parametr zapytania „access_type=offline”. Dla jednego użytkownika można utworzyć wiele tokenów odświeżania. Tokeny odświeżania mogą być ograniczone czasowo. Wygasną, jeśli nie będą używane przez 6 miesięcy, użytkownik przyzna dostęp na określony czas lub aplikacja będzie w trybie „Testowanie”. Więcej informacji znajdziesz w sekcji Wygaśnięcie tokena odświeżania.
Odpowiedź tokena Odpowiedź JSON zawiera:
  • token dostępu,
  • wygaśnięcie tokena dostępu,
  • zakresy
  • typ tokena,
  • token odświeżania
  • Identyfikator użytkownika
 Odpowiedź JSON zawiera:
  • token dostępu,
  • wygaśnięcie tokena dostępu,
  • zakresy
  • typ tokena,
  • token odświeżania

Aby uzyskać identyfikator użytkownika, użyj punktu końcowego users.getIdentity.

Użytkownicy Fitbita muszą ponownie wyrazić zgodę na nową integrację, ponieważ Twoja aplikacja korzysta z innej biblioteki OAuth. Nie można przenieść tokenów dostępu i tokenów odświeżania do interfejsu API Google Health i ich używać.

Zakresy

Musisz zaktualizować żądanie autoryzacji, aby używać zakresów interfejsu Google Health API. Zakresy określają, czy aplikacja obsługuje operacje odczytu czy zapisu. Nie używaj zakresów, które nie są potrzebne w Twojej aplikacji. Jeśli projekt aplikacji się zmieni, zawsze możesz dodać więcej zakresów.

Zakresy interfejsu Google Health API to adresy URL HTTP rozpoczynające się od https://www.googleapis.com/auth/googlehealth.{scope}. Na przykład https://www.googleapis.com/auth/googlehealth.activity_and_fitness.

Mapowania zakresu

Zakresy interfejsu Fitbit Web API są powiązane z zakresami interfejsu Google Health API w ten sposób:

Tabela: mapowanie zakresów interfejsu Fitbit Web API na interfejs Google Health API
Zakresy Fitbit Web API Zakresy interfejsu API Google Health
aktywność .activity_and_fitness
.activity_and_fitness.readonly
cardio_fitness .activity_and_fitness
.activity_and_fitness.readonly
tętno .health_metrics_and_measurements
.health_metrics_and_measurements.readonly
lokalizacja .location.readonly
żywienie .nutrition
.nutrition.readonly
oxygen_saturation .health_metrics_and_measurements
.health_metrics_and_measurements.readonly
profil .profile
.profile.readonly
respiratory_rate .health_metrics_and_measurements
.health_metrics_and_measurements.readonly
ustawienia .settings
.settings.readonly
sen .sleep
.sleep.readonly
temperatura .health_metrics_and_measurements
.health_metrics_and_measurements.readonly
waga .health_metrics_and_measurements
.health_metrics_and_measurements.readonly

Typy danych

Oto lista typów danych interfejsu Google Health API i sposób ich mapowania na interfejs Fitbit Web API.

Tabela: mapowanie typów danych z interfejsu Fitbit Web API na interfejs Google Health API
Typ danych Fitbit Web API Typ danych interfejsu API Google Health
  Identyfikator punktu końcowego
Aktywne minuty w strefie Aktywne minuty w strefie
  active-zone-minutes
Zawiera zmiany poziomów aktywności użytkownika. Poziom aktywności
  activity-level
Wysokość Wysokość
  altitude
Tkanka tłuszczowa Tkanka tłuszczowa
  body-fat
caloriesOut w każdej strefie tętna Kalorie w strefie tętna
  calories-in-heart-rate-zone
Podsumowanie HRV Dzienna zmienność rytmu serca
  daily-heart-rate-variability
Podsumowanie SpO2 Dzienne nasycenie tlenem
  daily-oxygen-saturation
Tętno spoczynkowe Dzienne tętno spoczynkowe
  daily-resting-heart-rate
Temperatura skóry Codzienne wyliczenia temperatury snu
  daily-sleep-temperature-derivations
Odległość Dystans
  distance
Zarejestrowana aktywność Ćwiczenia
  exercise
Piętra Piętra
  floors
tętno Tętno
  heart-rate
HRV Intraday Zmienność rytmu serca
  heart-rate-variability
SpO2 w ciągu dnia Nasycenie tlenem
  oxygen-saturation
Wartość pułapu tlenowego podczas biegu użytkownika Pułap tlenowy podczas biegu
  run-vo2-max
Szereg czasowy aktywności – minuty braku aktywności Okres braku aktywności
  sedentary-period
Sen Sen
  sleep
Kroki Kroki
  steps
Aktywność caloriesOut Wszystkie kalorie
  total-calories
Wartość pułapu tlenowego Maksymalny pułap tlenowy
  vo2-max
Waga Waga
  weight

Punkty końcowe

Punkty końcowe REST mają spójną składnię dla wszystkich typów danych.

  • Punkt końcowy usługi: podstawowy adres URL HTTP zmienia się na https://health.googleapis.com.
  • Składnia punktu końcowego: interfejs Google Health API obsługuje ograniczoną liczbę punktów końcowych, których można używać w przypadku większości obsługiwanych typów danych. Zapewnia to spójną składnię dla wszystkich typów danych i ułatwia korzystanie z punktów końcowych.
  • Identyfikator użytkownika: w składni punktu końcowego należy podać identyfikator użytkownika lub „me”. W przypadku użycia tego parametru identyfikator użytkownika jest wywnioskowany z tokena dostępu.

Przykład: poniżej znajdziesz przykład wywołania punktu końcowego GET Profile za pomocą interfejsu Google Health API.

GET https://health.googleapis.com/v4/users/me/profile

Mapowania punktów końcowych

W tabeli dostępności typów danych znajdziesz listę dostępnych typów danych i metod API, które obsługują.

Fitbit Web API Endpoint Type Google Health API
GET (Log | Summary | Daily Summary), w którym żądasz danych z jednego dnia. Metoda dailyRollup z parametrem windowSize = 1 dzień
GET (Intraday), jeśli prosisz o szczegółowe dane Metoda list
GET (Time Series) by Date or Interval metoda rollUp lub dailyRollUp z zakresem dat;
GET (Lista logów) Metoda list
TWORZENIE I AKTUALIZOWANIE logów Metoda patch
Usuwanie logów Metoda batchDelete
GET Profile users.getProfile zwraca konkretne informacje o użytkowniku;
users.getSettings zwraca jednostki i strefy czasowe użytkownika.
AKTUALIZACJA profilu users.updateProfile modyfikuje konkretne informacje o użytkowniku.
users.updateSettings modyfikuje jednostki i strefy czasowe użytkownika.
Pobieranie identyfikatora użytkownika users.getIdentity zwraca starszy identyfikator użytkownika Fitbita i identyfikator użytkownika Google.

Migracja użytkowników

Przejście z interfejsu Fitbit Web API na interfejs Google Health API to coś więcej niż tylko aktualizacja techniczna. Ze względu na zmianę biblioteki OAuth użytkownicy muszą ponownie wyrazić zgodę na nową integrację. Nie można przenieść tokenów dostępu i tokenów odświeżania do interfejsu API Google Health i ich używać. Aby pomóc Ci utrzymać użytkowników podczas migracji, przygotowaliśmy kilka technicznych i strategicznych sugestii, które pomogą Ci przeprowadzić ją z sukcesem.

Strategia podwójnej biblioteki

Interfejs Fitbit Web API i interfejs Google Health API korzystają z różnych bibliotek OAuth2, więc musisz zarządzać okresem „pomostowym”, w którym w bazie kodu istnieją obie biblioteki.

Równoległe zarządzanie autoryzacją

  • Enkapsulacja klientów: utwórz warstwę abstrakcji lub interfejs dla „usługi zdrowotnej”. Dzięki temu pozostała część aplikacji może żądać danych bez wiedzy o tym, która biblioteka (Fitbit OAuth czy Google OAuth) jest aktywna w przypadku danego użytkownika.
  • Aktualizacja schematu bazy danych: zaktualizuj tabelę użytkowników, aby uwzględnić flagę oauth_type. Na przykład użyj fitbit w przypadku OAuth Fitbita i google w przypadku OAuth Google.
    • Nowi użytkownicy: domyślnie korzystają z interfejsu Google Health API i biblioteki Google OAuth. Ustaw wartość oauth_type na google.
    • Dotychczasowi użytkownicy: nadal korzystają z interfejsu Fitbit Web API, dopóki nie przejdą ponownie procesu uzyskiwania zgody. Ustaw wartość oauth_type na fitbit.

Proces ponownego uzyskiwania zgody „Step-Up”

Zamiast wymuszać wylogowanie, użyj autoryzacji przyrostowej:

  1. Wykrywanie tokena open source Fitbit: gdy użytkownik interfejsu Fitbit Web API otworzy aplikację, wyślij powiadomienie „Aktualizacja usługi”.
  2. Uruchom obsługę protokołu Google OAuth: gdy użytkownik kliknie „Aktualizuj”, uruchom obsługę biblioteki Google OAuth2.
  3. Zastąp i unieważnij: po otrzymaniu tokena OAuth Google zapisz go w profilu użytkownika, zaktualizuj oauth_type z fitbit na google i (w miarę możliwości) programowo unieważnij stary token fitbit, aby zachować bezpieczeństwo profilu użytkownika.

Maksymalizacja utrzymania użytkowników

Ponowne uzyskanie zgody to „strefa zagrożenia” utratą klientów. Aby zapobiec porzucaniu aplikacji przez użytkowników, postępuj zgodnie z tymi sprawdzonymi metodami dotyczącymi wygody użytkownika:

Komunikacja oparta na wartości

Nie zaczynaj od słów „Zaktualizowaliśmy nasz interfejs API”. Zacznij od korzyści nowego systemu wspieranego przez Google:

  • Większe bezpieczeństwo: wspomnij o najlepszej w branży ochronie konta Google i uwierzytelnianiu dwuskładnikowym.
  • Niezawodność: krótszy czas synchronizacji i stabilniejsze połączenia z danymi.
  • Blokowanie funkcji: delikatne informowanie użytkowników, że nowe funkcje i typy danych wymagają aktualizacji.

Inteligentne wyznaczanie czasu

  • Nie przerywaj ważnych zadań: nigdy nie wyświetlaj ekranu ponownej zgody, gdy użytkownik jest w trakcie treningu lub rejestruje posiłek.
  • Faza „zachęty”: przez pierwsze 30 dni używaj banera, który można zamknąć.
  • Faza „ostatecznego wyłączenia”: ponowne uzyskanie zgody będzie obowiązkowe dopiero po kilku tygodniach wyświetlania ostrzeżeń, co zbiegnie się w czasie z oficjalnymi terminami wycofania interfejsu Fitbit Web API.

Porównanie procesu migracji

Wyraźne rozróżnienie wizualne między starym a nowym przepływem pomaga deweloperom zrozumieć, gdzie następuje rozwidlenie logiki.

Funkcja Fitbit Web API (starsza wersja) Google Health API (Google-Identity)
Biblioteka uwierzytelniania Standard Open Source Google Identity Services (GIS) / Google Auth
Konta użytkowników Starsze dane logowania Fitbita Konto Google
Typ tokena Dostęp do Fitbita i odświeżanie danych Tokeny dostępu i tokeny odświeżania wydane przez Google
Zarządzanie zakresem Szerokie uprawnienia Szczegółowe / przyrostowe uprawnienia

Zrozumienie niuansów migracji konta

Zgodnie z dokumentacją Fitbita użytkownicy, którzy przenoszą swoje konto do Google, zwykle nie tracą od razu połączeń z usługami innych firm, ale zmiana wersji interfejsu API jest wymagana po stronie programisty.

  • Sprawdzanie ważności tokena: użyj procesu w tle, aby sprawdzić, czy tokeny Fitbit nie powodują błędów „Nieautoryzowany”. Może to oznaczać, że użytkownik przeniósł konto, ale Twoja aplikacja nie została jeszcze zaktualizowana.
  • Eleganckie błędy: jeśli wywołanie OAuth Fitbita nie powiedzie się, przekieruj użytkownika na niestandardową stronę „Połącz ponownie Fitbita”, która korzysta z nowego przepływu OAuth Google.

Przykładowy kod

Aby przejść z starszej wersji interfejsu Fitbit Web API na interfejs Google Health API, musisz zastąpić ogólne biblioteki OAuth2 biblioteką Google Auth Library. Poniżej znajdziesz sugestię dotyczącą architektury i implementację w pseudokodzie napisaną w JavaScript, która umożliwia obsługę stanu „Dual-Library”.

1. „Przełącznik oprogramowania pośredniczącego”

Nie możesz przenieść wszystkich użytkowników naraz, dlatego backend musi określić, której biblioteki użyć, na podstawie bieżącego apiVersion użytkownika przechowywanego w Twojej bazie danych.

Implementacja

const { OAuth2Client } = require('google-auth-library');
const FitbitV1Strategy = require('fitbit-oauth2-library').Strategy;

// 1. Initialize the Google Health API Client
const GHAClient = new OAuth2Client(
  process.env.GOOGLE_CLIENT_ID,
  process.env.GOOGLE_CLIENT_SECRET,
  process.env.REDIRECT_URI
);

// 2. Create a Unified Fetcher
async function fetchSteps(user) {
  if (user.apiVersion === 4) {
    // ---- GOOGLE OAUTH LIBRARY LOGIC ----
    GHAClient.setCredentials({ refresh_token: user.refreshToken });
    const url = 'GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints';
    const res = await GHAClient.request({ url });
    return res.data;
  } else {
    // ---- FITBIT WEB API LEGACY LOGIC ----
    // Use your existing Fitbit open-source library logic here
    return callLegacyV1Api(user.accessToken);
  }
}

2. Migracja przepływu UX

Aby zmaksymalizować utrzymanie klientów, użyj wzorca „Przerwa i przejście na wyższy pakiet”. Dzięki temu użytkownik nie musi ponownie logować się, dopóki nie zacznie korzystać z aplikacji.

Logika przekierowania

Gdy użytkownik interfejsu Fitbit Web API skorzysta z określonej funkcji, uruchom migrację:

app.get('/dashboard', async (req, res) => {
  const user = await db.users.find(req.user.id);

  if (user.apiVersion === 1) {
    // Render a "soft" migration page explaining the Google transition
    return res.render('migrate-to-google', {
      title: "Keep your data syncing",
      message: "Fitbit is moving to Google accounts. Re-connect now to stay updated."
    });
  }

  const data = await fetchSteps(user);
  res.render('dashboard', { data });
});

3. Kluczowe zmiany techniczne

Podczas pisania skryptów migracji JavaScriptu pamiętaj o tych różnicach:

Funkcja Fitbit Web API (starsza wersja) Google Health API (Google-Identity)
Token Endpoint (Punkt końcowy tokena) https://api.fitbit.com/oauth2/token https://oauth2.googleapis.com/token
Biblioteka uwierzytelniania Standard Open Source Uwierzytelnianie Google
Zakres aktywność https://www.googleapis.com/auth/googlehealth.activity_and_fitness
Identyfikator użytkownika Identyfikator zakodowany w Fitbicie zwrócony w odpowiedzi /oauth2/token Identyfikator użytkownika zwrócony z punktu końcowego users.getIdentity

4. Lista kontrolna przechowywania

  • Trwałość sesji: nie czyść starej sesji interfejsu Fitbit Web API użytkownika, dopóki token dostępu Google Health API nie zostanie zweryfikowany i zapisany w Twojej bazie danych.
  • Automatyczne wycofywanie: po zakończeniu migracji do interfejsu Google Health API użyj żądania POST do starszego punktu końcowego wycofywania Fitbita: https://api.fitbit.com/oauth2/revoke. Dzięki temu użytkownik nie będzie widzieć „zduplikowanych” uprawnień aplikacji w ustawieniach Fitbita.
  • Obsługa błędów: jeśli wywołanie Fitbit zwraca kod 401 Unauthorized, automatycznie przekieruj użytkownika do procesu OAuth Google zamiast wyświetlać komunikat o błędzie.