Inizia subito la migrazione o lo sviluppo di una nuova app. Le app con più di 100 utenti possono essere inviate per la verifica a partire dal 30 marzo.

Per garantire un'esperienza ottimale ai tuoi utenti, ti consigliamo di attendere la fine di maggio 2026 per lanciare ufficialmente l'integrazione, in modo da allinearla al ritiro degli account Fitbit legacy. Tieni presente che da ora fino alla fine di maggio potrebbero verificarsi modifiche che causano interruzioni in base ai feedback degli sviluppatori.

Guida alla migrazione

L'API Google Health è una nuova API creata da zero che consente agli sviluppatori di eseguire query sui dati utente di Fitbit. Non si tratta solo di un aggiornamento, ma di una mossa strategica per garantire che le tue app siano sicure, affidabili e pronte per i futuri progressi della tecnologia sanitaria. L'API supporta una nuova console per registrare le tue app, il supporto di Google OAuth 2.0, nuovi tipi di dati, nuovi schemi degli endpoint e un nuovo formato di risposta.

La guida è progettata per aiutare gli sviluppatori a eseguire la migrazione delle app API Fitbit Web esistenti alla nuova API Google Health.

Perché eseguire la migrazione?

I vantaggi dell'utilizzo dell'API Google Health sono:

Sicurezza avanzata: conformità alle best practice di Google in materia di sicurezza, in linea con gli standard di Google per sicurezza, privacy e identità.
Coerenza: elimina le incoerenze legacy nei formati dei dati, nei fusi orari, nelle unità di misura e nella gestione degli errori per un'esperienza di sviluppo più intuitiva.
Scalabilità e a prova di futuro: progettato per scalare in modo da soddisfare le esigenze future e supporta protocolli moderni come gRPC.

Registrazione app

Tutte le app API Google Health devono essere registrate utilizzando la console Google Cloud, che funge da hub centrale per la gestione di tutte le tue app Google.

Per istruzioni su come registrare l'app, segui i passaggi descritti in Guida introduttiva. Ecco le differenze che noterai durante la registrazione delle tue app.

	API Fitbit Web	API Google Health
Link pubblico/i	https://dev.fitbit.com/apps	https://console.cloud.google.com
Aggiunta di una nuova app	Premi Registra una nuova app.	Crea un progetto Google Cloud Abilita l'API Google Health
Informazioni di base	Campi da compilare: Nome applicazione Descrizione URL del sito web dell'applicazione Organizzazione URL del sito web dell'organizzazione URL dei Termini di servizio URL delle Norme sulla privacy	Campi da compilare: Nome applicazione Email dell'assistenza Segmento di pubblico (interno o esterno) Email di contatto Icona del logo URL del sito web dell'applicazione URL Norme sulla privacy URL dei Termini di servizio Dominio autorizzato
Tipi di applicazioni	Uno sviluppatore è tenuto a selezionare: Server Cliente Personale	Applicazione web Android Estensione di Chrome iOS TV Applicazione desktop Universal Windows Platform
ID client	Registrato quando le impostazioni dell'applicazione vengono salvate	Registrato separatamente
Tipo di accesso	L'accesso in lettura e scrittura è controllato a livello di app	L'accesso in lettura e scrittura è controllato a livello di ambito
URL aggiuntivi	URL di reindirizzamento: il sito a cui gli utenti vengono reindirizzati dopo l'autorizzazione degli ambiti	Origini JavaScript autorizzate: origine HTTP che ospita l'applicazione web URL di reindirizzamento: il sito a cui gli utenti vengono reindirizzati dopo l'autorizzazione degli ambiti

Implementazione di OAuth

Le app API Google Health supportano solo le librerie client Google OAuth2. Le librerie client sono disponibili per i framework più comuni, il che semplifica l'implementazione di OAuth 2.0. Di seguito sono riportate le differenze tra le librerie Google OAuth2 e le librerie OAuth2 open source:

	API Fitbit Web	API Google Health
Supporto della libreria OAuth2	Open source	Librerie client Google OAuth2
Funzionalità	Incoerenza tra le piattaforme	Coerenza tra le piattaforme
URL di autorizzazione	https://www.fitbit.com/oauth2/authorize	https://accounts.google.com/o/oauth2/v2/auth
URL del token	https://api.fitbit.com/oauth2/token	https://oauth2.googleapis.com/token
Durata del token di accesso	8 ore	1 ora
Dimensione token di accesso	1024 byte	2048 byte
Aggiorna token	I token di aggiornamento vengono generati quando si utilizza il flusso di concessione del codice di autorizzazione. Per un utente può essere generato un solo token di aggiornamento. I token non scadono mai e possono essere utilizzati una sola volta.	Per generare un token di aggiornamento, la stringa di autorizzazione deve contenere il parametro di query "access_type=offline". È possibile creare più token di aggiornamento per un singolo utente. I token di aggiornamento possono essere basati sul tempo. Scadranno se non vengono utilizzati per 6 mesi, se l'utente ha concesso l'accesso in base al tempo o se l'app è in modalità "Test". Per maggiori dettagli, vedi Scadenza del token di aggiornamento.
Token Response	La risposta JSON contiene: token di accesso scadenza del token di accesso ambiti tipo di token token di aggiornamento ID utente	La risposta JSON contiene: token di accesso scadenza del token di accesso ambiti tipo di token token di aggiornamento Per ottenere l'ID utente, utilizza l'endpoint users.getIdentity.

Gli utenti Fitbit devono dare nuovamente il consenso alla nuova integrazione perché la tua app utilizza una libreria OAuth diversa. Non è possibile trasferire e utilizzare i token di accesso e i token di aggiornamento nell'API Google Health.

Ambiti

Devi aggiornare la richiesta di autorizzazione per utilizzare gli ambiti dell'API Google Health. Gli ambiti definiscono se la tua app supporta le operazioni di lettura o scrittura. Non utilizzare ambiti non necessari per la tua app. Puoi sempre aggiungere altri ambiti in un secondo momento se il design dell'app cambia.

Gli ambiti dell'API Google Health sono un URL HTTP che inizia con https://www.googleapis.com/auth/googlehealth.{scope}. Ad esempio, https://www.googleapis.com/auth/googlehealth.activity_and_fitness.

Mappature degli ambiti

Ecco come gli ambiti dell'API Fitbit Web corrispondono agli ambiti dell'API Google Health:

*Tabella: mappature degli ambiti dell'API Fitbit Web all'API Google Health*
Ambiti dell'API Fitbit Web	Ambiti API Google Health
attività	.activity_and_fitness .activity_and_fitness.readonly
cardio_fitness	.activity_and_fitness .activity_and_fitness.readonly
battito cardiaco	.health_metrics_and_measurements .health_metrics_and_measurements.readonly
località	.location.readonly
alimentazione	.nutrition .nutrition.readonly
oxygen_saturation	.health_metrics_and_measurements .health_metrics_and_measurements.readonly
profilo	.profile .profile.readonly
respiratory_rate	.health_metrics_and_measurements .health_metrics_and_measurements.readonly
impostazioni	.settings .settings.readonly
sonno	.sleep .sleep.readonly
temperatura	.health_metrics_and_measurements .health_metrics_and_measurements.readonly
peso	.health_metrics_and_measurements .health_metrics_and_measurements.readonly

Tipi di dati

Di seguito è riportato un elenco dei tipi di dati dell'API Google Health e della loro mappatura all'API Fitbit Web.

*Tabella: mappature dei tipi di dati dall'API Fitbit Web all'API Google Health*
Tipo di dati dell'API Fitbit Web	Tipo di dati API Google Health ID endpoint
Minuti in zona attiva	Minuti in zona attiva `active-zone-minutes`
Contiene modifiche ai livelli di attività dell'utente	Livello di attività `activity-level`
Elevazione	Altitudine `altitude`
Grasso corporeo	Grasso corporeo `body-fat`
`caloriesOut` in ogni zona del battito cardiaco	Calorie nella zona battito cardiaco `calories-in-heart-rate-zone`
Riepilogo HRV	Variabilità del battito cardiaco giornaliera `daily-heart-rate-variability`
Riepilogo SpO2	Saturazione di ossigeno giornaliera `daily-oxygen-saturation`
Battito cardiaco a riposo	Battito cardiaco a riposo giornaliero `daily-resting-heart-rate`
Temperatura cutanea	Derivazioni della temperatura del sonno giornaliera `daily-sleep-temperature-derivations`
Distanza	Distanza `distance`
Attività registrata	Allenamento `exercise`
Piani	Piani `floors`
Frequenza cardiaca	Battito cardiaco `heart-rate`
HRV infragiornaliero	Variabilità del battito cardiaco `heart-rate-variability`
SpO2 infragiornaliero	Saturazione di ossigeno `oxygen-saturation`
Valore VO2 max quando l'utente corre	VO2 max corsa `run-vo2-max`
Serie temporale di minuti di attività sedentaria	Periodo sedentario `sedentary-period`
Sonno	Sonno `sleep`
Passaggi	Passaggi `steps`
Attività `caloriesOut`	Calorie totali `total-calories`
Valore VO2 max	VO2 max `vo2-max`
Peso	Peso `weight`

Endpoint

Gli endpoint REST adottano una sintassi coerente per tutti i tipi di dati.

Endpoint di servizio: l'URL HTTP di base cambia in https://health.googleapis.com.
Sintassi dell'endpoint: l'API Google Health supporta un numero limitato di endpoint, che possono essere utilizzati dalla maggior parte dei tipi di dati supportati. In questo modo viene fornita una sintassi coerente per tutti i tipi di dati e gli endpoint sono più facili da usare.
Identificatore utente: nella sintassi dell'endpoint deve essere specificato l'ID utente o me. Quando mi utilizzi, lo User-ID viene dedotto dal token di accesso.

Esempio: ecco un esempio dell'endpoint GET Profile chiamato utilizzando l'API Google Health

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

Mapping degli endpoint

Consulta la tabella Disponibilità dei tipi di dati per un elenco dei tipi di dati disponibili e dei metodi API che supportano.

Tipo di endpoint API Fitbit Web	API Google Health
GET (Log \| Summary \| Daily Summary) in cui richiedi un singolo giorno di dati	Metodo dailyRollup con `windowSize` = 1 giorno
GET (infragiornaliero) in cui richiedi dati granulari	Metodo list
GET (Time Series) by Date or Interval	Metodo rollUp o dailyRollUp che include un intervallo di date
GET (elenco log)	Metodo list
CREARE E AGGIORNARE i log	Metodo patch
DELETE Logs	Metodo batchDelete
GET Profile	users.getProfile restituisce le informazioni specifiche dell'utente users.getSettings restituisce le unità e i fusi orari dell'utente
AGGIORNA Profilo	users.updateProfile modifica le informazioni specifiche dell'utente users.updateSettings modifica le unità e i fusi orari dell'utente
Recuperare l'ID utente	users.getIdentity restituisce l'ID utente legacy di Fitbit e Google dell'utente.

Eseguire la migrazione degli utenti

La migrazione dall'API Fitbit Web all'API Google Health è più di un aggiornamento tecnico. I tuoi utenti devono dare nuovamente il consenso alla nuova integrazione a causa della modifica della libreria OAuth. Non è possibile trasferire e utilizzare i token di accesso e di aggiornamento nell'API Google Health. Per favorire la fidelizzazione degli utenti durante la migrazione, ecco alcuni suggerimenti tecnici e strategici per una migrazione riuscita.

Strategia a doppia libreria

Poiché l'API Fitbit Web e l'API Google Health utilizzano librerie OAuth2 diverse, devi gestire un periodo di "bridging" in cui entrambe le librerie esistono nel tuo codebase.

Parallel Authorization Management

Encapsulate Clients: crea un livello di astrazione o un'interfaccia per il tuo "servizio sanitario". In questo modo, il resto dell'app può richiedere dati senza sapere quale libreria (OAuth Fitbit o OAuth Google) è attiva per quello specifico utente.
Aggiornamento dello schema del database: aggiorna la tabella degli utenti in modo che includa un flag oauth_type. Ad esempio, usa fitbit per Fitbit OAuth e google per Google OAuth.
- Nuovi utenti: impostazione predefinita dell'API Google Health e della libreria Google OAuth. Imposta oauth_type su google.
- Utenti esistenti: continua a utilizzare l'API Fitbit Web fino al completamento del flusso di consenso. Imposta oauth_type su fitbit.

Flusso di riacquisizione del consenso "Step-Up"

Invece di forzare la disconnessione, utilizza un approccio di autorizzazione incrementale:

Rileva token open source Fitbit: quando un utente dell'API Fitbit Web apre l'app, attiva una notifica "Aggiornamento del servizio".
Avvia il flusso OAuth di Google: quando l'utente fa clic su "Aggiorna", avvia il flusso della libreria OAuth2 di Google.
Sostituisci e revoca: una volta ricevuto correttamente il token Google OAuth, salvalo nel profilo utente, aggiorna oauth_type da fitbit a google e (se possibile) revoca a livello di programmazione il vecchio token fitbit per mantenere pulito il profilo di sicurezza dell'utente.

Massimizzare la fidelizzazione degli utenti

Il nuovo consenso è la "zona di pericolo" per l'abbandono. Per evitare che gli utenti abbandonino l'app, segui queste best practice UX:

Comunicazione "Value-First"

Non iniziare con "Abbiamo aggiornato la nostra API". Inizia con i vantaggi del nuovo sistema supportato da Google:

Sicurezza avanzata: menziona la protezione dell'account leader del settore di Google e l'autenticazione a due fattori.
Affidabilità: tempi di sincronizzazione più rapidi e connessioni dati più stabili.
Feature Gating: informa gli utenti che i nuovi tipi di dati e le nuove funzionalità richiedono l'aggiornamento.

Smart Timing

Non interrompere le attività di alto valore: non attivare mai la schermata di riacquisizione del consenso mentre un utente si sta allenando o sta registrando il cibo.
Fase "Sollecito": per i primi 30 giorni, utilizza un banner chiudibile.
Fase di "interruzione definitiva": rendi obbligatorio il nuovo consenso solo dopo diverse settimane di avvisi, in concomitanza con le scadenze ufficiali di ritiro dell'API Fitbit Web.

Confronto del flusso di migrazione

Una chiara distinzione visiva tra i flussi precedenti e quelli nuovi aiuta gli sviluppatori a capire dove si dirama la logica.

Funzionalità	API Fitbit Web (legacy)	API Google Health (Google-Identity)
Libreria di autenticazione	Standard open source	Servizi di identità Google (GIS) / Google Auth
Account utente	Credenziali legacy di Fitbit	Account Google
Tipo di token	Accesso / aggiornamento specifico per Fitbit	Token di accesso/aggiornamento emessi da Google
Gestione dell'ambito	Autorizzazioni generiche	Autorizzazioni granulari / incrementali

Gestire le sfumature della migrazione dell'account

Secondo la documentazione di Fitbit, gli utenti che eseguono la migrazione del proprio account a Google in genere non perdono immediatamente le connessioni di terze parti, ma la modifica della versione dell'API è un requisito lato sviluppatore.

Controlla la validità del token: utilizza un backgroundworker per verificare se i token Fitbit non funzionano e restituiscono errori "Non autorizzato". Ciò potrebbe indicare che l'utente ha eseguito la migrazione del proprio account, ma la tua app non è ancora aggiornata.
Errori controllati: se una chiamata OAuth di Fitbit non va a buon fine, reindirizza l'utente a una pagina personalizzata "Riconnetti Fitbit" che utilizza in modo specifico il nuovo flusso OAuth di Google.

Codice di esempio

Per eseguire la migrazione dalla precedente API Fitbit Web all'API Google Health, passerai dalle librerie OAuth2 generali alla libreria Google Auth. Di seguito è riportato un suggerimento di architettura e un'implementazione di pseudocodice scritta in JavaScript per gestire questo stato di "doppia libreria".

1. "Middleware Switch"

Poiché non puoi eseguire la migrazione di tutti gli utenti contemporaneamente, il backend deve determinare quale libreria utilizzare in base all'attuale apiVersion dell'utente memorizzato nel tuo database.

Implementazione

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. Esegui la migrazione del flusso UX

Per massimizzare la fidelizzazione, utilizza un pattern "Interrompi e aggiorna". In questo modo, l'utente non è costretto a eseguire nuovamente l'accesso finché non interagisce con l'app.

Logica di reindirizzamento

Quando un utente dell'API Fitbit Web accede a una funzionalità specifica, attiva la migrazione:

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. Transizioni tecniche chiave

Quando scrivi gli script di migrazione JavaScript, tieni presente queste differenze:

Funzionalità	API Fitbit Web (legacy)	API Google Health (Google-Identity)
Endpoint token	https://api.fitbit.com/oauth2/token	https://oauth2.googleapis.com/token
Libreria di autenticazione	Standard open source	Google Auth
Ambito	attività	https://www.googleapis.com/auth/googlehealth.activity_and_fitness
ID utente	ID codificato Fitbit restituito nella risposta /oauth2/token	User-ID restituito dall'endpoint users.getIdentity

4. Elenco di controllo per la fidelizzazione

Persistenza della sessione: non cancellare la vecchia sessione dell'API Fitbit Web finché l'access_token dell'API Google Health non viene verificato e salvato nel tuo database.
Revoca automatica: una volta completata la migrazione dell'API Google Health, utilizza una richiesta POST all'endpoint di revoca Fitbit legacy: https://api.fitbit.com/oauth2/revoke. In questo modo l'utente non vedrà autorizzazioni app "duplicate" nelle impostazioni di Fitbit.
Gestione degli errori: se una chiamata Fitbit restituisce un errore 401 Unauthorized, reindirizza automaticamente al flusso OAuth di Google anziché mostrare un messaggio di errore.

Guida alla migrazione Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.