Übersicht

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 bereit für zukünftige Fortschritte in der Gesundheitstechnologie 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.

Dieser Leitfaden 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:

  • Erhöhte Sicherheit: Einhaltung der Best Practices für Sicherheit von Google, die den Sicherheits-, Datenschutz- und Identitätsstandards von Google entsprechen.
  • Konsistenz: Beseitigt alte Inkonsistenzen in 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.

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 Ihrer Codebasis 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: Standardmäßig werden die Google Health API und die Google OAuth-Bibliothek verwendet. 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:

  1. Fitbit-Open-Source-Token erkennen: Wenn ein Fitbit Web API-Nutzer die App öffnet, wird eine Benachrichtigung über ein „Service-Update“ ausgelöst.
  2. Google-OAuth-Ablauf starten: Wenn der Nutzer auf „Aktualisieren“ klickt, starten Sie den Ablauf der Google OAuth2-Bibliothek.
  3. 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 angezeigt werden, während ein Nutzer gerade ein Training absolviert 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 Weitreichende 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.