Beginnen Sie noch heute mit der Migration oder der Entwicklung einer neuen App. Apps mit mehr als 100 Nutzern können ab dem 30. März zur Überprüfung eingereicht werden.

Damit deine Nutzer eine reibungslose Nutzung der Integration haben, empfehlen wir, mit der offiziellen Einführung bis Ende Mai 2026 zu warten. So kann die Integration mit der Einstellung der alten Fitbit-Konten abgestimmt werden. Bitte beachten Sie, dass es bis Ende Mai zu Breaking Changes kommen kann, da wir auf Entwicklerfeedback reagieren.

Migrationsanleitung

Die Google Health API ist eine neue API, die von Grund auf neu entwickelt wurde und es Entwicklern ermöglicht, Fitbit-Nutzerdaten abzufragen. Es handelt sich nicht nur um ein Update, sondern um einen strategischen Schritt, um sicherzustellen, dass Ihre Apps sicher, zuverlässig und für zukünftige Fortschritte in der Gesundheitstechnologie gerüstet sind. Die API unterstützt eine neue Konsole für die Registrierung Ihrer Apps, Google OAuth 2.0, neue Datentypen, ein neues Endpunktschema und ein neues Antwortformat.

Diese Anleitung soll Entwicklern helfen, ihre bestehenden Fitbit Web API-Apps zur neuen Google Health API zu migrieren.

Warum sollten Sie migrieren?

Die Google Health API bietet folgende Vorteile:

Höhere Sicherheit: Einhaltung der Best Practices für Sicherheit von Google, die den Sicherheits-, Datenschutz- und Identitätsstandards von Google entsprechen.
Konsistenz: Beseitigt alte Inkonsistenzen bei Datenformaten, Zeitzonen, Maßeinheiten und der Fehlerbehandlung für eine intuitivere Entwicklerumgebung.
Skalierbarkeit und Zukunftssicherheit: Die Lösung ist so konzipiert, dass sie sich an zukünftige Anforderungen anpassen lässt und moderne Protokolle wie gRPC unterstützt.

App-Registrierung

Alle Google Health API-Apps müssen über die Google Cloud Console registriert werden. Diese dient als zentrale Anlaufstelle für die Verwaltung aller Ihrer Google-Apps.

Eine Anleitung zum Registrieren Ihrer App finden Sie unter Erste Schritte. Hier sind die Unterschiede, die Sie bei der Registrierung Ihrer Apps feststellen werden.

	Fitbit Web API	Google Health API
Öffentliche Links	https://dev.fitbit.com/apps	https://console.cloud.google.com
Neue App hinzufügen	Drücken Sie auf Neue App registrieren.	Google Cloud-Projekt erstellen Google Health API aktivieren
Allgemeine Informationen	Felder, die ausgefüllt werden müssen: Anwendungsname Beschreibung Website-URL der Anwendung Organisation URL der Website der Organisation URL für die Nutzungsbedingungen URL für die Datenschutzerklärung	Felder, die ausgefüllt werden müssen: Name der Anwendung Support-E-Mail-Adresse Zielgruppe (intern oder extern) E-Mail-Adresse Logo-Symbol Website-URL der Anwendung URL der Datenschutzerklärung URL für die Nutzungsbedingungen Autorisierte Domain
Anwendungstypen	Entwickler müssen Folgendes auswählen: Server Kunde Persönlich	Webanwendung Android Chrome-Erweiterung iOS Fernseher Desktopanwendung Universelle Windows-Plattform
Client-ID	Registrierung beim Speichern der Anwendungseinstellungen	Separat registriert
Zugriffstyp	Lese- und Schreibzugriff wird auf App-Ebene gesteuert	Lese- und Schreibzugriff wird auf Bereichsebene gesteuert.
Zusätzliche URLs	Weiterleitungs-URL: Website, auf die Nutzer weitergeleitet werden, nachdem sie die Bereiche autorisiert haben.	Autorisierte JavaScript-Quellen: HTTP-Quelle, die die Webanwendung hostet Weiterleitungs-URL: Website, auf die Nutzer weitergeleitet werden, nachdem sie die Bereiche autorisiert haben.

OAuth-Implementierung

Google Health API-Apps unterstützen nur die Google OAuth2-Clientbibliotheken. Clientbibliotheken sind für gängige Frameworks verfügbar, was die Implementierung von OAuth 2.0 vereinfacht. Die Unterschiede zwischen den Google OAuth2-Bibliotheken und den Open-Source-OAuth2-Bibliotheken sind folgende:

	Fitbit Web API	Google Health API
Unterstützung von OAuth2-Bibliotheken	Open Source	Google OAuth2-Clientbibliotheken
Funktionen	Plattformübergreifend inkonsistent	Plattformübergreifend konsistent
Autorisierungs-URL	https://www.fitbit.com/oauth2/authorize	https://accounts.google.com/o/oauth2/v2/auth
Token-URL	https://api.fitbit.com/oauth2/token	https://oauth2.googleapis.com/token
Lebensdauer von Zugriffstokens	8 Stunden	1 Stunde
Größe des Zugriffstokens	1.024 Byte	2.048 Byte
Aktualisierungstoken	Aktualisierungstokens werden beim Autorisierungscode-Grant-Vorgang generiert. Für einen Nutzer kann nur ein Aktualisierungstoken generiert werden. Tokens laufen nie ab und können nur einmal verwendet werden.	Zum Generieren eines Aktualisierungstokens muss der Autorisierungsstring den Abfrageparameter „access_type=offline“ enthalten. Für einen einzelnen Nutzer können mehrere Aktualisierungstokens erstellt werden. Aktualisierungstokens können zeitbasiert sein. Sie laufen ab, wenn sie sechs Monate lang nicht verwendet wurden, der Nutzer zeitbasierten Zugriff gewährt hat oder sich die App im Testmodus befindet. Weitere Informationen finden Sie unter Ablauf von Aktualisierungstokens.
Token-Antwort	Die JSON-Antwort enthält: Zugriffstoken Ablauf des Zugriffstokens Umfang Tokentyp Aktualisierungstoken Nutzer-ID	Die JSON-Antwort enthält: Zugriffstoken Ablauf des Zugriffstokens Umfang Tokentyp Aktualisierungstoken Verwenden Sie den Endpunkt users.getIdentity, um die Nutzer-ID abzurufen.

Fitbit-Nutzer müssen der neuen Integration noch einmal zustimmen, da in Ihrer App eine andere OAuth-Bibliothek verwendet wird. Es ist nicht möglich, Zugriffstokens und Aktualisierungstokens an die Google Health API zu übertragen und zu verwenden.

Bereiche

Sie müssen Ihre Autorisierungsanfrage aktualisieren, um die Google Health API-Bereiche zu verwenden. Die Bereiche definieren, ob Ihre App Lese- oder Schreibvorgänge unterstützt. Verwenden Sie keine Bereiche, die für Ihre App nicht erforderlich sind. Sie können später jederzeit weitere Bereiche hinzufügen, wenn sich das Design Ihrer App ändert.

Die Google Health API-Bereiche sind HTTP-URLs, die mit https://www.googleapis.com/auth/googlehealth.{scope} beginnen. Beispiel: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.

Bereichszuordnungen

So werden die Fitbit Web API-Bereiche den Google Health API-Bereichen zugeordnet:

*Tabelle: Zuordnung von Fitbit Web API-Bereichen zu Google Health API-Bereichen*
Fitbit Web API-Bereiche	Google Health API-Bereiche
Aktivität	.activity_and_fitness .activity_and_fitness.readonly
cardio_fitness	.activity_and_fitness .activity_and_fitness.readonly
Herzfrequenz	.health_metrics_and_measurements .health_metrics_and_measurements.readonly
Standort	.location.readonly
Ernährung	.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
Einstellungen	.settings .settings.readonly
Schlaf	.sleep .sleep.readonly
Temperatur	.health_metrics_and_measurements .health_metrics_and_measurements.readonly
Gewicht	.health_metrics_and_measurements .health_metrics_and_measurements.readonly

Datentypen

Hier finden Sie eine Liste der Google Health API-Datentypen und wie sie der Fitbit Web API zugeordnet werden.

*Tabelle: Zuordnung von Fitbit Web API- zu Google Health API-Datentypen*
Fitbit Web API-Datentyp	Google Health API-Datentyp Endpunkt-ID
Aktivzonenminuten	Aktivzonenminuten `active-zone-minutes`
Enthält Änderungen an den Aktivitätsstufen des Nutzers	Aktivitätsniveau `activity-level`
Höhe	Höhe `altitude`
Körperfett	Körperfett `body-fat`
`caloriesOut` in jeder Herzfrequenzzone	Kalorien in Herzfrequenzzone `calories-in-heart-rate-zone`
Zusammenfassung der HRV	Tägliche Herzfrequenzvariabilität `daily-heart-rate-variability`
SpO2-Zusammenfassung	Tägliche Sauerstoffsättigung `daily-oxygen-saturation`
Ruheherzfrequenz	Tägliche Ruheherzfrequenz `daily-resting-heart-rate`
Hauttemperatur	Tägliche Ableitungen der Schlaftemperatur `daily-sleep-temperature-derivations`
Entfernung	Distanz `distance`
Aufgezeichnete Aktivität	Training `exercise`
Stockwerke	Stockwerke `floors`
Herzfrequenz	Herzfrequenz `heart-rate`
HFV-Tagesverlauf	Herzfrequenzvariabilität `heart-rate-variability`
SpO2-Tagesverlauf	Sauerstoffsättigung `oxygen-saturation`
VO2 Max-Wert beim Laufen	Maximale Sauerstoffaufnahme bei Lauf `run-vo2-max`
Zeitreihe der Aktivität – Minuten im Sitzen	Inaktiver Zeitraum `sedentary-period`
Schlaf	Schlaf `sleep`
Schritte	Schritte `steps`
Aktivität `caloriesOut`	Kalorien insgesamt `total-calories`
Maximaler VO2‑Wert	Maximale Sauerstoffaufnahme `vo2-max`
Gewicht	Gewicht `weight`

Endpunkte

Die REST-Endpunkte verwenden für alle Datentypen eine einheitliche Syntax.

Dienstendpunkt: Die Basis-HTTP-URL ändert sich zu https://health.googleapis.com.
Endpunktsyntax: Die Google Health API unterstützt eine begrenzte Anzahl von Endpunkten, die für die meisten unterstützten Datentypen verwendet werden können. So wird eine einheitliche Syntax für alle Datentypen erreicht und die Endpunkte sind einfacher zu verwenden.
Nutzer-ID: In der Endpunktsyntax muss entweder die Nutzer-ID oder „me“ angegeben werden. Wenn Sie mich verwenden, wird die Nutzer-ID aus dem Zugriffstoken abgeleitet.

Beispiel: Hier ist ein Beispiel für den GET-Profil-Endpunkt, der über die Google Health API aufgerufen wird.

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

Endpunktzuordnungen

Eine Liste der verfügbaren Datentypen und der API-Methoden, die sie unterstützen, finden Sie in der Tabelle Verfügbarkeit von Datentypen.

Fitbit Web API-Endpunkttyp	Google Health API
GET (Log \| Summary \| Daily Summary), wenn Sie Daten für einen einzelnen Tag anfordern	Methode dailyRollup mit `windowSize` = 1 Tag
GET (Tagesdaten), wenn Sie detaillierte Daten anfordern	list-Methode
GET (Zeitreihen) nach Datum oder Intervall	rollUp- oder dailyRollUp-Methode mit einem Zeitraum
GET (Log List)	list-Methode
LOGS ERSTELLEN UND AKTUALISIEREN	patch-Methode
Protokolle löschen	Methode batchDelete
GET Profile	users.getProfile gibt die spezifischen Informationen des Nutzers zurück. users.getSettings gibt die Einheiten und Zeitzonen des Nutzers zurück.
Profil aktualisieren	Mit users.updateProfile werden die spezifischen Informationen des Nutzers geändert. users.updateSettings ändert die Einheiten und Zeitzonen des Nutzers.
Nutzer-ID abrufen	users.getIdentity gibt die alte Fitbit-Nutzer-ID und die Google-Nutzer-ID des Nutzers zurück.

Nutzer migrieren

Die Migration von der Fitbit Web API zur Google Health API ist mehr als nur ein technisches Update. Ihre Nutzer müssen der neuen Integration aufgrund der Änderung der OAuth-Bibliothek noch einmal zustimmen. Es ist nicht möglich, Zugriffstokens und Aktualisierungstokens an die Google Health API zu übertragen und zu verwenden. Damit Sie Nutzer während der Migration binden können, haben wir einige technische und strategische Vorschläge für eine erfolgreiche Migration zusammengestellt.

Die Dual-Library-Strategie

Da die Fitbit Web API und die Google Health API unterschiedliche OAuth 2.0-Bibliotheken verwenden, müssen Sie einen „Übergangszeitraum“ verwalten, in dem beide Bibliotheken in Ihrem Code vorhanden sind.

Parallele Autorisierungsverwaltung

Clients kapseln: Erstelle eine Abstraktionsebene oder Schnittstelle für deinen „Health Service“. So kann der Rest Ihrer App Daten anfordern, ohne zu wissen, welche Bibliothek (Fitbit OAuth oder Google OAuth) für den jeweiligen Nutzer aktiv ist.
Datenbankschema aktualisieren: Aktualisieren Sie Ihre Nutzertabelle, um ein oauth_type-Flag einzufügen. Verwenden Sie beispielsweise fitbit für Fitbit-OAuth und google für Google-OAuth.
- Neue Nutzer: Verwenden Sie standardmäßig die Google Health API und die Google OAuth-Bibliothek. Setzen Sie oauth_type auf google.
- Bestehende Nutzer: Die Fitbit Web API kann weiterhin verwendet werden, bis die erneute Einwilligung erfolgt ist. Setzen Sie oauth_type auf fitbit.

Ablauf für die erneute Einwilligung („Step-Up“)

Anstatt einen Logout zu erzwingen, sollten Sie die inkrementelle Autorisierung verwenden:

Fitbit-Open-Source-Token erkennen: Wenn ein Fitbit Web API-Nutzer die App öffnet, wird eine Benachrichtigung über ein „Service-Update“ ausgelöst.
Google-OAuth-Ablauf starten: Wenn der Nutzer auf „Aktualisieren“ klickt, starten Sie den Ablauf der Google OAuth2-Bibliothek.
Ersetzen und widerrufen: Sobald das Google-OAuth-Token erfolgreich empfangen wurde, speichern Sie es im Nutzerprofil, aktualisieren Sie oauth_type von fitbit auf google und widerrufen Sie (falls möglich) das alte fitbit-Token programmatisch, um das Sicherheitsprofil des Nutzers sauber zu halten.

Nutzerbindung maximieren

Die erneute Einwilligung ist die „Gefahrenzone“ für Churn. So verhindern Sie, dass Nutzer die App verlassen:

Value-First-Kommunikation

Beginnen Sie nicht mit „Wir haben unsere API aktualisiert“. Beginnen Sie mit den Vorteilen des neuen, von Google unterstützten Systems:

Erhöhte Sicherheit: Erwähnen Sie den branchenführenden Kontoschutz von Google und die 2‑Faktor-Authentifizierung.
Zuverlässigkeit: Schnellere Synchronisierung und stabilere Datenverbindungen.
Feature-Gating: Nutzer werden sanft darauf hingewiesen, dass für neue Funktionen und Datentypen ein Update erforderlich ist.

Smart Timing

Wichtige Aufgaben nicht unterbrechen: Das Fenster für die erneute Einwilligung darf niemals ausgelöst werden, während ein Nutzer gerade trainiert oder Lebensmittel protokolliert.
Phase 1: Aufforderung: Verwenden Sie in den ersten 30 Tagen ein Banner, das geschlossen werden kann.
Phase des „harten Cutoffs“: Die erneute Einwilligung wird erst nach mehreren Wochen mit Warnungen obligatorisch. Dies fällt mit den offiziellen Fristen für die Einstellung der Fitbit Web API zusammen.

Vergleich der Migrationsabläufe

Eine klare visuelle Unterscheidung zwischen den alten und neuen Abläufen hilft Entwicklern, zu verstehen, wo sich die Logik verzweigt.

Feature	Fitbit Web API (Legacy)	Google Health API (Google-Identität)
Auth-Bibliothek	Standard-Open-Source	Google Identity Services (GIS) / Google Auth
Nutzerkonten	Alte Fitbit-Anmeldedaten	Google-Konto
Tokentyp	Fitbit-spezifischer Zugriff / Aktualisierung	Von Google ausgestellte Zugriffs-/Aktualisierungstokens
Management des Projektumfangs	Umfassende Berechtigungen	Detaillierte / inkrementelle Berechtigungen

Umgang mit der Nuance der Kontomigration

Laut der Dokumentation von Fitbit verlieren Nutzer, die ihr Konto zu Google migrieren, ihre Drittanbieterverbindungen in der Regel nicht sofort. Die Änderung der API-Version ist jedoch eine Anforderung für Entwickler.

Token-Gültigkeit prüfen: Verwende einen Backgroundworker, um zu prüfen, ob Fitbit-Tokens mit „Nicht autorisiert“-Fehlern fehlschlagen. Das kann darauf hindeuten, dass der Nutzer sein Konto migriert hat, Ihre App aber noch nicht aktualisiert wurde.
Graceful Failures: Wenn ein Fitbit-OAuth-Aufruf fehlschlägt, leite den Nutzer zu einer benutzerdefinierten Seite „Fitbit neu verbinden“ weiter, auf der speziell der neue Google-OAuth-Ablauf verwendet wird.

Codebeispiel

Wenn Sie von der alten Fitbit Web API zur Google Health API migrieren, wechseln Sie von allgemeinen OAuth2-Bibliotheken zur Google Auth Library. Im Folgenden finden Sie einen Architekturvorschlag und eine in JavaScript geschriebene Pseudocode-Implementierung für diesen „Dual-Library“-Zustand.

1. Der „Middleware Switch“

Da Sie nicht alle Nutzer gleichzeitig migrieren können, muss Ihr Backend anhand der aktuellen apiVersion des Nutzers, die in Ihrer Datenbank gespeichert ist, ermitteln, welche Bibliothek verwendet werden soll.

Implementierung

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. UX-Ablauf migrieren

Verwenden Sie das Muster Unterbrechen und upgraden, um die Kundenbindung zu maximieren. So wird der Nutzer erst dann zum erneuten Anmelden aufgefordert, wenn er die App bereits verwendet.

Weiterleitungslogik

Wenn ein Fitbit Web API-Nutzer auf eine bestimmte Funktion zugreift, wird die Migration ausgelöst:

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. Wichtige technische Umstellungen

Beachten Sie beim Schreiben Ihrer JavaScript-Migrationsskripts die folgenden Unterschiede:

Feature	Fitbit Web API (Legacy)	Google Health API (Google-Identität)
Token-Endpunkt	https://api.fitbit.com/oauth2/token	https://oauth2.googleapis.com/token
Auth-Bibliothek	Standard-Open-Source	Google Auth
Umfang	Aktivität	https://www.googleapis.com/auth/googlehealth.activity_and_fitness
Nutzer-ID	In der Antwort von /oauth2/token zurückgegebene codierte Fitbit-ID	Nutzer-ID, die vom Endpunkt „users.getIdentity“ zurückgegeben wird

4. Checkliste zur Kundenbindung

Sitzungsdauer: Löschen Sie die alte Fitbit Web API-Sitzung des Nutzers erst, wenn das Google Health API-access_token erfolgreich bestätigt und in Ihrer Datenbank gespeichert wurde.
Automatisch widerrufen: Wenn die Migration der Google Health API abgeschlossen ist, senden Sie eine POST-Anfrage an den alten Fitbit-Widerrufsendpunkt: https://api.fitbit.com/oauth2/revoke. Dadurch wird verhindert, dass dem Nutzer in seinen Fitbit-Einstellungen „doppelte“ App-Berechtigungen angezeigt werden.
Fehlerbehandlung: Wenn ein Fitbit-Aufruf den Fehler „401 Unauthorized“ zurückgibt, leite den Nutzer automatisch zum Google-OAuth-Ablauf weiter, anstatt eine Fehlermeldung anzuzeigen.

Migrationsanleitung Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.