Panoramica

L'API Google Health è una soluzione completa creata da zero che offre agli sviluppatori un accesso affidabile a un'ampia gamma di dati sulla salute degli utenti con consenso e a diversi tipi di dati. L'API Google Health utilizza una nuova console per la registrazione delle app, Google OAuth 2.0, nuovi tipi di dati, un nuovo schema di endpoint e un nuovo formato di risposta.

Questa guida è progettata per aiutare gli sviluppatori a eseguire la migrazione delle app API Fitbit Web esistenti alla nuova API Google Health. Include consigli per garantire una migrazione senza problemi mantenendo gli utenti.

Perché eseguire la migrazione?

Non si tratta solo di un aggiornamento, ma di una mossa strategica per garantire che le tue app siano sicure e pronte per i futuri progressi della tecnologia sanitaria. Di seguito sono riportati alcuni dei vantaggi dell'utilizzo dell'API Google Health:

  • Accesso a dati completi: ottieni un accesso affidabile a un'ampia gamma di dati sulla salute degli utenti con consenso e a diversi tipi di dati.
  • Sicurezza avanzata: conformità alle best practice di sicurezza di Google, in linea con gli standard di sicurezza, privacy e identità di Google.
  • 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 preparazione per il futuro: progettata per scalare in base alle esigenze future e supporta protocolli moderni come gRPC.

La transizione dall'API Fitbit Web all'API Google Health comporta più di semplici modifiche tecniche. A causa del passaggio a una nuova libreria OAuth, i token di accesso e di aggiornamento esistenti non possono essere trasferiti, pertanto gli utenti devono fornire nuovamente il consenso per l'integrazione aggiornata.

Supportare entrambi i metodi di accesso

Poiché l'API Fitbit Web e l'API Google Health utilizzano sistemi diversi per gestire gli accessi degli utenti, mentre le API Fitbit Web sono ancora attive, la tua app dovrà supportare temporaneamente entrambi i metodi contemporaneamente.

Anziché chiedere i dati direttamente, implementa un livello che decida se comunicare con l'API Fitbit Web o l'API Google Health per un utente specifico, in modo che il resto dell'app non debba preoccuparsi dei dettagli.

Aggiorna il database degli utenti in modo da includere un flag (ad esempio, oauth_type) per identificare il sistema di accesso che utilizzano.

  • Per i nuovi utenti: configura automaticamente la nuova API Google Health (oauth_type: google).
  • Per gli utenti esistenti: mantienili sull'API Fitbit Web finché non aggiornano il consenso (oauth_type: fitbit).

Per evitare di interrompere l'esperienza utente, ti consigliamo di non forzare tutti gli utenti a uscire e rientrare. Invece:

  1. Quando un utente che rimane connesso alle API Fitbit Web interagisce con la tua app, mostra una notifica che lo incoraggia ad aggiornare la connessione.
  2. Quando l'utente accetta l'azione di aggiornamento, attiva immediatamente il flusso di accesso a Google Health.
  3. Una volta eseguito l'accesso a Google, salva le nuove credenziali Google nel profilo dell'utente e cambia il flag oauth_type da fitbit a google. Se la configurazione lo consente, disconnetti l'utente dal vecchio sistema Fitbit a livello di programmazione revocando i suoi token per mantenere tutto in ordine e sicuro.

Garantire la continuità dei dati

Quando si esegue la transizione di un'integrazione dall'API Fitbit Web legacy all'API Google Health, le applicazioni per sviluppatori devono tenere conto di una modifica delle strutture di identificazione degli utenti.

L'API Fitbit Web legacy identifica gli account utilizzando una stringa alfanumerica di 6 caratteri (ad esempio A1B2C3), mentre l'API Google Health utilizza un healthUserId formattato come una stringa di un massimo di 63 cifre e caratteri.

Per colmare questa lacuna senza perdere il contesto utente, gli sviluppatori possono eseguire una query sull'endpoint getIdentity per ottenere gli ID utente di Fitbit e Health. Questo endpoint restituisce un payload contenente sia legacyUserId sia il nuovo healthUserId, consentendo alle applicazioni di creare dinamicamente un mapping tra i record esistenti e il nuovo sistema di account.

Eseguire il backfill dei dati storici

Se un utente non esegue l'autenticazione ai nuovi endpoint dell'API Google Health prima che gli endpoint legacy vengano disattivati, i suoi dati saranno comunque disponibili a condizione che continui a sincronizzare il dispositivo con l'app Google Health. Tuttavia, potresti riscontrare una lacuna nei dati di questo utente.

Per eseguire il backfill dei dati, una volta che l'utente ha eseguito nuovamente l'autenticazione ai nuovi endpoint, puoi utilizzare l'API Google Health per eseguire il backfill dei dati storici. Per indicazioni, consulta Eseguire query sui dati storici.

Comunicazione e tempistiche

Per aiutare gli utenti a passare dall'OAuth Fitbit esistente al nuovo OAuth Google, segui queste best practice.

Comunicazione incentrata sul valore

Non iniziare con "Abbiamo aggiornato la nostra API", ma con i vantaggi dell'integrazione dei dati di Google Health nella tua app, assicurandoti che gli utenti siano consapevoli di dover eseguire nuovamente l'autenticazione se vogliono che i loro dati vengano sincronizzati:

  • Spiega chiaramente quali funzionalità sono disponibili nella tua app e sono basate sull'integrazione e personalizza il messaggio in base ai vantaggi che un utente può trarre da queste funzionalità.
  • Concentrati sulle funzionalità e fornisci casi d'uso anziché dettagli di implementazione tecnica.
  • Non dire: "Non potrai connetterti all'API Fitbit".
  • Di': "Per continuare a visualizzare allenamenti dettagliati con i dati sulla frequenza cardiaca, fornisci nuovamente il consenso alle API Google Health".

Quando inviare notifiche agli utenti

In tutte le comunicazioni con gli utenti, rispetta le linee guida del brand Google Health, e utilizza banner, schede o avvisi ignorabili.

  • Non attivare la schermata di consenso durante un allenamento o la registrazione manuale di un'attività.
  • Rendi obbligatorio il consenso solo dopo diverse settimane di avvisi, in concomitanza con le scadenze ufficiali per il ritiro dell'API Fitbit Web.
  • Se un utente non ha fornito nuovamente il consenso dopo la scadenza, fornisci un percorso di ripristino graduale. Fornisci un messaggio di aiuto in un banner, scheda o suggerimento che aiuti gli utenti a capire perché i loro dati non sono presenti e come risolvere il problema.