Configurare Google Cloud e OAuth

L'accesso all'API Google Health viene fornito tramite Google Cloud. Per abilitare l'API e autorizzare un Account Google, ti servirà un progetto Google Cloud.

Che tu sia uno sviluppatore di API Fitbit esistente o un nuovo utente dell'API Google Health, dovrai completare questo passaggio per effettuare chiamate all'API.

Crea un progetto e un client OAuth

Utilizza il pulsante Abilita l'API e ottieni un ID client OAuth 2.0 per abilitare l'API Google Health e ottenere un ID client OAuth 2.0:

  1. Se hai un progetto Google Cloud esistente che vuoi utilizzare per l'API Google Health, assicurati di aver eseguito l'accesso all'account amministratore per quel progetto. Poi seleziona il progetto esistente dall'elenco dei progetti disponibili dopo aver fatto clic sul pulsante. In caso contrario, crea un nuovo progetto.
  2. Seleziona Web Server quando ti viene chiesto "Da dove stai chiamando?".
  3. Inserisci https://www.google.com come valore per URI di reindirizzamento autorizzati. È necessario un URI di reindirizzamento per ottenere un codice di autorizzazione utilizzando OAuth 2.0.
  4. Una volta completata la configurazione, copia i valori dell'ID client e del client secret OAuth 2.0 e scarica il file JSON delle credenziali sul tuo computer.
Abilita l'API e ottieni un ID client OAuth 2.0

Se vuoi configurare manualmente il tuo progetto Google Cloud o verificare la configurazione e recuperare di nuovo le credenziali:

  1. Abilita l'API Google Health nella pagina Abilitazione API.
  2. Ottieni un ID client OAuth 2.0 nella pagina Credenziali.

Per saperne di più sulla configurazione di OAuth 2.0 utilizzando la console Google, consulta Utilizzare OAuth 2.0 per accedere alle API di Google.

Utilizzare progetti separati per lo staging e la produzione

L'API Google Health non fornisce un ambiente sandbox o di staging separato. Tutti i tuoi ambienti chiamano l'API Google Health di produzione, quindi gestisci la separazione degli ambienti a livello di progetto Google Cloud.

Quando configuri gli ambienti per la tua app, segui queste best practice:

  • Crea progetti Google Cloud separati per gli ambienti di sviluppo, gestione temporanea e produzione. Ogni progetto gestisce il proprio client OAuth 2.0, la schermata per il consenso e gli abbonati webhook.
  • Non utilizzare il progetto Google Cloud di produzione o il relativo client OAuth 2.0 per i test, perché le modifiche apportate a questo progetto influiscono direttamente sulla tua app di produzione.
  • Sviluppa e testa prima in un progetto non di produzione, poi applica le modifiche al progetto di produzione quando è tutto pronto.
  • Utilizza i tag nella console Google Cloud per distinguere visivamente i tuoi progetti in base all'ambiente. Per istruzioni, vedi Designare gli ambienti di progetto con i tag.

Aggiungere utenti di test

Per impostazione predefinita, i client OAuth appena creati si trovano in uno stato non verificato con un limite di 100 utenti sia per i test che per la produzione. Per attivare l'autorizzazione durante questo periodo, devi aggiungere manualmente l'indirizzo email di ogni utente all'elenco degli utenti di test nella configurazione del progetto.

Aggiorna l'elenco degli utenti di test nella pagina Segmento di pubblico:

  1. In questa pagina, lo "Stato di pubblicazione" dovrebbe essere impostato su Test e il "Tipo di utente" su Esterno.
  2. Nella sezione "Utenti di test", fai clic su + Aggiungi utenti. Inserisci l'indirizzo email di tutti gli utenti di test che devono essere autorizzati a concedere alla tua app l'autorizzazione ad accedere ai propri dati sulla salute.
  3. Fai clic su Salva.

Il supporto di più di 100 utenti con l'API Google Health richiede il completamento di una revisione della sicurezza di terze parti. Per ulteriori informazioni, consulta il Centro assistenza per la verifica delle app OAuth.

Aggiungere ambiti

Devi specificare gli ambiti che il tuo client è autorizzato a chiamare nella pagina Accesso ai dati:

  1. In questa pagina, fai clic su Aggiungi o rimuovi ambiti.
  2. Nella colonna API, cerca "API Google Health". Seleziona gli ambiti di cui hai bisogno per la tua applicazione.
  3. Dopo aver selezionato tutti gli ambiti necessari, fai clic su Aggiorna per tornare alla pagina Accesso ai dati.
  4. Fai clic su Salva.

Prima di selezionare gli ambiti, esamina l'implementazione degli ambiti.

Hai completato la configurazione dell'ID client e ora dovresti essere in grado di effettuare chiamate all'API Google Health.

Aggiorna ambiti

Puoi chiedere all'utente di autorizzare nuovamente la tua app impostando il parametro prompt su consent nella richiesta di autenticazione. Quando è incluso prompt=consent, la schermata per il consenso viene visualizzata ogni volta che l'app richiede l'autorizzazione degli ambiti di accesso, anche se tutti gli ambiti sono stati precedentemente concessi al progetto API di Google.

Per aggiungere o modificare gli ambiti utilizzando il parametro prompt=consent:

  1. Identifica l'elenco completo degli ambiti di cui ha bisogno la tua applicazione. Devono essere inclusi sia gli ambiti esistenti sia quelli nuovi che devi aggiungere.

  2. Modifica il parametro scope nell'URL di autorizzazione in modo da includere l'elenco aggiornato di valori di scope separati da spazi.

  3. Aggiungi prompt=consent ai parametri URI di autenticazione. In questo modo, il server di autorizzazione richiede il consenso dell'utente prima di restituire le informazioni al client.

    L'esempio seguente mostra una richiesta GET HTTPS all'endpoint di autorizzazione OAuth 2.0 di Google che richiede più ambiti con prompt=consent aggiunto:

    https://accounts.google.com/o/oauth2/v2/auth?client_id=client-id&redirect_uri=redirect-uri&response_type=code&access_type=offline&scope=https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly%20https://www.googleapis.com/auth/googlehealth.sleep.readonly&prompt=consent

  4. Quando l'utente segue il link aggiornato, viene visualizzata una pagina di consenso che elenca tutti gli ambiti richiesti. Una volta che l'utente fa clic su "Continua" o "Consenti", riceverai un nuovo codice di autorizzazione che può essere scambiato con token che coprono l'intero insieme di ambiti.

    Includi prompt=consent solo quando necessario, ad esempio quando devi ottenere un nuovo token di aggiornamento o quando gli ambiti richiesti sono cambiati.

Librerie client OAuth2

L'elenco delle librerie client OAuth2 disponibili utilizzate per l'integrazione con i framework più diffusi è disponibile all'indirizzo Utilizzare OAuth 2.0 per accedere alle API di Google.

Quando implementi Google OAuth in app mobile o desktop, utilizza sempre i browser di sistema (come le schede personalizzate di Chrome su Android o ASWebAuthenticationSession su iOS) e non utilizzare mai WebView incorporate, che bloccano le passkey e interrompono i flussi Google OAuth. Consulta le best practice per Accedi con Google per indicazioni.

Prima che un utente completi il flusso di consenso Google OAuth 2.0 nella tua app, deve accedere all'app mobile Google Health per collegare Google Health al proprio Account Google. Google OAuth 2.0 autentica qualsiasi Account Google valido e non può verificare se l'account ha un profilo Google Health attivo durante la schermata per il consenso.

Invita gli utenti a completare i seguenti passaggi nell'app mobile Google Health prima di avviare il flusso di consenso OAuth nella tua app:

  1. Scarica e apri l'app mobile Google Health dal Google Play Store o dall'App Store di Apple.
  2. Tocca Accedi con Google e seleziona l'Account Google che vuoi collegare alla tua app.
  3. Segui le istruzioni nell'app per creare un nuovo profilo Google Health oppure segui i passaggi per la migrazione dell'account Fitbit per trasferire un account Fitbit esistente al tuo Account Google.

Dopo aver scambiato il codice di autorizzazione con i token OAuth, chiama l'endpoint users.getIdentity (GET https://health.googleapis.com/v4/users/me/identity) per verificare che l'Account Google dell'utente sia collegato a Google Fit prima di contrassegnare l'account come collegato nella tua app. Per informazioni dettagliate sulla gestione degli account scollegati (400 ACCOUNT_NOT_LINKED), consulta Gestire gli Account Google scollegati.

Token di aggiornamento

Per mantenere l'accesso a lungo termine alle API di Google senza richiedere la costante riautenticazione dell'utente, la tua applicazione deve utilizzare un token di aggiornamento. Per informazioni dettagliate sull'implementazione, incluse le richieste HTTP e i parametri specifici richiesti, consulta la documentazione della piattaforma Google Identity.

Per scambiare un token di aggiornamento con un token di accesso, effettua una chiamata POST HTTPS all'endpoint token di Google OAuth 2.0. Il seguente snippet mostra un esempio di richiesta e risposta:

Richiesta

curl -L -X POST 'https://oauth2.googleapis.com/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id=client-id&client_secret=client-secret&refresh_token=refresh-token&grant_type=refresh_token'

Risposta

{
  "access_token": "access-token",
  "expires_in": 3599,
  "scope": "scope-list",
  "token_type": "Bearer",
  "refresh_token": "refresh-token",
  "refresh_token_expires_in": 112154
}

Quando aggiornare un token

Aggiorna i token di aggiornamento on demand nell'ambito della progressione naturale della sessione attiva di un utente quando i token di accesso sono scaduti o in scadenza. Evita di aggiornare i token in batch (ad esempio, utilizzando un servizio o un job cron pianificato per aggiornare i token per tutti gli utenti a un'ora fissa).

L'aggiornamento dei token in batch non è consigliato per i seguenti motivi:

  • L'aggiornamento batch impedisce l'allineamento degli aggiornamenti dei token con i pattern di sincronizzazione degli utenti attivi. Anche se puoi utilizzare la chiamata Get Devices per visualizzare l'ultimo orario di sincronizzazione di un utente, questa operazione richiede un ambito OAuth aggiuntivo che gli utenti non sono obbligati ad approvare.
  • L'elaborazione batch aggiorna i token che non devono essere aggiornati, causando un sovraccarico di elaborazione ridondante sia per i tuoi sistemi sia per i server di Google.
  • Se si verifica un problema di rete o un'interruzione del server durante un aggiornamento batch, tutti i token utente interessati vengono interessati contemporaneamente. L'aggiornamento dei token individualmente durante la normale progressione delle sincronizzazioni degli utenti isola l'impatto dei errori temporanei su un singolo utente.
  • La diagnosi dei problemi è più difficile con i job batch. Poiché le richieste batch si verificano meno frequentemente e generano una serie di voci di log tutte insieme, è più difficile individuare l'inizio di un incidente.
  • I picchi di concorrenza elevata nelle richieste di token durante le esecuzioni batch aumentano la probabilità di raggiungere i limiti di frequenza o di riscontrare errori di autenticazione intermittenti.

Comportamento dei token durante i test

Tieni presente il comportamento dei token di aggiornamento a seconda dello stato di pubblicazione del progetto Google Cloud:

  • Modalità di test:se la schermata per il consenso OAuth è configurata con lo stato di pubblicazione "Test in corso", i token di aggiornamento emessi sono basati sul tempo e scadono dopo 7 giorni. Durante questo periodo, riceverai un singolo token di aggiornamento che rimane valido e utilizzabile per ottenere nuovi token di accesso fino alla data di scadenza.
  • Modalità pubblicata:una volta che l'app viene spostata allo stato"In produzione", i token di aggiornamento in genere non scadono, a meno che non vengano revocati o rimangano inutilizzati per un periodo prolungato (in genere sei mesi).

Per un'esperienza utente senza interruzioni, assicurati di pubblicare l'applicazione prima che venga spostata in un ambiente di produzione per evitare la scadenza dei token dopo 7 giorni.

Generare dati di esempio

Google non fornisce dati sulla salute di esempio o simulati precompilati. Per testare l'integrazione, devi generare i tuoi dati di test. Utilizza uno dei seguenti metodi per generare dati di esempio per i tuoi utenti di test:

  • Indossa un tracker: indossa un tracker Fitbit, Pixel Watch o un altro smartwatch compatibile con l'app Google Health e cammina per generare dati su passi, battito cardiaco e allenamento.
  • Attiva MobileTrack: attiva MobileTrack nell'app Google Health e cammina con il tuo dispositivo mobile.
  • Registra i dati manualmente:inserisci manualmente le metriche di salute (come sonno, peso, acqua o assunzione di cibo) tramite l'app Google Health.
  • Scrivi dati utilizzando l'API:invia richieste di scrittura (ad esempio POST o PATCH) direttamente agli endpoint dell'API REST per popolare i dati in modo programmatico. Per ulteriori dettagli sulla creazione e sull'aggiornamento dei punti dati, consulta la documentazione di riferimento REST.

Protezione su più account (API RISC)

Attiva la condivisione e il coordinamento di rischi e incidenti (RISC) se vuoi ricevere notifiche relative alle modifiche ai token evento o al collegamento degli account, ad esempio account disconnessi o token revocati, per liberare spazio dai token archiviati e aggiornare lo stato della connessione dell'interfaccia utente. L'abilitazione dell'API RISC è facoltativa.

Per abilitare l'API RISC per il tuo progetto Google Cloud:

  1. Apri la pagina API RISC nella console Google Cloud. Assicurati che sia selezionato il progetto che utilizzi per l'API Google Health.
  2. Leggi i Termini RISC e assicurati di comprendere i requisiti.
  3. Fai clic su Attiva se accetti i termini.

Dopo aver attivato l'API, devi creare e registrare un endpoint HTTPS per ricevere e convalidare i token evento inviati da Google.

Per saperne di più sulla Protezione su più account e su RISC, vedi Proteggere gli account utente con la Protezione su più account.