Provisioning degli account controllati dall'utente - Guida per gli sviluppatori API

Questo documento spiega concetti importanti sull'utilizzo dell'API Provisioning per creare nuovi account Google Analytics.

Introduzione

L'API Provisioning può essere utilizzata per creare nuovi account Google Analytics e abilitare Google Analytics per i tuoi clienti su larga scala. È rivolto a fornitori di servizi qualificati e grandi partner. Consulta la pagina relativa alla Panoramica dell'API di provisioning per un'introduzione all'API di provisioning.

Prima di iniziare

L'accesso a tutte le API di Google Analytics è simile a quello delle API. Prima di iniziare a utilizzare l'API di provisioning, devi:

  • Leggi la pagina Librerie client per un elenco completo delle librerie client specifiche dei linguaggi di programmazione che funzionano con l'API.
  • Leggi la Guida di riferimento per saperne di più sull'interfaccia dell'API e su come accedere ai dati senza una libreria client.

Ogni libreria client fornisce un singolo oggetto del servizio di analisi per accedere all'API di provisioning. Per creare l'oggetto di servizio, in genere devi seguire questi passaggi:

  1. Registra la tua applicazione nella console API di Google.
  2. Autorizza la creazione di un nuovo account Google Analytics.
  3. Creare un oggetto di servizio Analytics.

Se non hai completato questi passaggi, ti invitiamo a leggere il tutorial sull'API Hello Google Analytics. Questo tutorial illustra i passaggi iniziali per la creazione di un'applicazione API di Google Analytics. Al termine, capirai come accedere alle API di Google Analytics per eseguire attività reali.

Panoramica

Quando crei account Google Analytics utilizzando l'API di provisioning, devi prendere in considerazione due flussi distinti:

  • Flusso tecnico: il flusso end-to-end per il provisioning programmatico di un account Google Analytics per un utente.
  • Flusso utente: le considerazioni relative all'implementazione da tenere presenti per il flusso di creazione dell'account dal punto di vista dell'utente.

Questo documento descrive per ogni flusso i passaggi e i requisiti di alto livello.

Flusso tecnico

I passaggi di alto livello per utilizzare l'API di provisioning per creare un nuovo account e l'integrazione con Google Analytics sono:

  1. Chiedi all'utente di autenticare e autorizzare l'applicazione o il servizio utilizzando OAuth 2.0.
  2. Crea un ticket account utilizzando l'API Provisioning.
  3. Reindirizza l'utente all'accettazione dei Termini di servizio (TdS) di Google Analytics e gestisci la risposta.
  4. (Facoltativo) Configura le opportunità di integrazione e dell'account.

Se tutti questi passaggi sono stati completati correttamente, verrà creato un account Google Analytics per l'utente e avrai l'ID account, l'ID proprietà e l'ID vista (profilo) per il nuovo account.

Per ogni passaggio riportato di seguito sono disponibili i Requisiti per completare il passaggio, i Risultati del passaggio e una descrizione del Flusso tecnico per il passaggio.

1. Autenticazione e autorizzazione

Ogni utente deve autorizzare la tua applicazione e concederle la possibilità di eseguire il provisioning di un account Google Analytics per suo conto. Si consiglia di utilizzare il flusso dell'applicazione Server web OAuth 2.0 per eseguire questo passaggio.

Che cosa serve per completare questo passaggio

  • ID client: il valore Client ID del progetto che utilizzerai. Questa funzionalità è disponibile da Google Developers Console. Per scoprire di più, leggi il flusso Server web OAuth 2.0.
  • URI di reindirizzamento: è a cui l'utente viene reindirizzato e viene inviata la risposta OAuth 2.0.
    • Configura Redirect URIs e ottieni Client ID per il tuo progetto utilizzando Google Developers Console.
    • Il valore di questo parametro deve corrispondere esattamente a uno dei valori registrati in Google Developers Console (inclusi gli schemi http o https, le maiuscole/minuscole e il carattere "/").
  • Auth Scope per l'API di provisioning di Google Analytics

Il risultato di questo passaggio

Una volta completato il flusso OAuth 2.0, l'utente avrà autorizzato la tua applicazione a eseguire il provisioning di un account per suo conto e avrai un token di accesso per l'utente.

Nota su token e ambiti:

  • Se intendi effettuare richieste aggiuntive per la configurazione dell'account dell'utente o i dati dei report dopo la creazione dell'account, puoi anche autorizzare ulteriori ambiti durante questo passaggio. Ad esempio, gli ambiti readonly o edit.
  • I token di accesso hanno una durata limitata. Se la tua applicazione deve accedere all'API Google Analytics oltre la durata di un singolo token di accesso, puoi anche richiedere un token di aggiornamento impostando access_type=offline. Un token di aggiornamento deve essere salvato in uno spazio di archiviazione sicuro a lungo termine per ogni utente, poiché consente all'applicazione di ottenere nuovi token di accesso. Per ulteriori dettagli, consulta Accesso offline.

Flusso tecnico per questo passaggio

Devi ottenere un token di accesso per l'utente. In base al flusso descritto nel server web OAuth 2.0, invia l'utente al servizio Google Account, quindi gestisci la risposta quando l'utente viene reindirizzato nuovamente al tuo servizio dopo aver completato il flusso di autenticazione.

Inserisci l'URL OAuth 2.0 che l'utente potrà visitare

Quando l'utente fa clic su un pulsante o su un link per iniziare o per creare un account, il link deve indirizzare all'inizio del flusso OAuth 2.0 per richiedere all'utente di concedere autorizzazioni di provisioning. Ad esempio:

https://accounts.google.com/o/oauth2/auth?
  scope=https://www.googleapis.com/auth/analytics.provision
  &redirect_uri={YOUR REDIRECT URI for OAUTH}
  &response_type=code
  &client_id={YOUR CLIENT ID}
Gestire la risposta del servizio Account Google

Quando l'utente decide di concedere l'accesso all'applicazione, verrà reindirizzato a redirect_uri come specificato nell'URL che hai creato con un parametro di query contenente un codice di autorizzazione. Se l'utente ha approvato la richiesta, la risposta del codice di autorizzazione può essere utilizzata per scambiare il codice di autorizzazione con un token di accesso tramite una richiesta POST all'API Google Account.

Salva il token di aggiornamento (se applicabile)

Il token di accesso verrà utilizzato nel passaggio successivo per consentirti di archiviarlo temporaneamente. Se hai richiesto anche un token di aggiornamento per l'utente, devi archiviarlo in modo sicuro per un utilizzo più a lungo termine. Un token di aggiornamento ha vita lunga e può essere utilizzato per emettere nuovi token di accesso.

2. Crea un ticket account utilizzando l'API di provisioning

Una volta che disponi di un token di accesso per l'utente autorizzato, puoi utilizzarlo per effettuare una richiesta all'API Provisioning in modo da creare un ticket account per l'utente. Il ticket dell'account è il primo passaggio per creare un account per un utente.

Che cosa serve per completare questo passaggio

Un token di accesso per l'utente autorizzato come descritto in Autenticazione e autorizzazione e i seguenti dettagli di provisioning:

  • URI di reindirizzamento
    • Definisce la destinazione a cui l'utente viene reindirizzato dopo la pagina dei Termini di servizio (TdS) di Google Analytics. Può essere diverso dall'URI di reindirizzamento specificato durante il flusso di autorizzazione OAuth 2.0.
    • Il valore del parametro URI di reindirizzamento deve corrispondere esattamente a uno dei valori registrati in Google Developers Console (inclusi gli schemi http o https, maiuscole e minuscole e il carattere "/" finale).
  • Campi account
    • Una proprietà name è obbligatoria per l'account.
  • Campi proprietà web
    • Una proprietà name è obbligatoria per la proprietà.
    • È obbligatorio un websiteUrl.
  • Campi del profilo
    • Per il profilo è obbligatoria una proprietà name.
    • È possibile fornire facoltativamente un timezone. Il valore predefinito è America/Los_Angeles.

Quando si crea un ticket per l'account, è possibile impostare solo i campi di base identificati sopra. Una volta creato l'account, è possibile apportare ulteriori modifiche alla configurazione della proprietà o della vista (profilo) utilizzando l'API di gestione.

Per ulteriori dettagli su questi campi, consulta la sezione di riferimento API per Account, Proprietà e Visualizzazioni (profili).

Il risultato di questo passaggio

Dopo che la richiesta all'API di provisioning è andata a buon fine, avrai un ticket account di breve durata per l'utente. L'ID ticket account viene utilizzato nel passaggio finale per richiedere all'utente di accettare i Termini di servizio (TdS) e attivare l'account. L'account non può essere utilizzato fino a quando i TdS non verranno accettati.

Flusso tecnico per questo passaggio

Utilizzando il token di accesso per l'utente ottenuto durante l'autenticazione e l'autorizzazione, viene effettuata una richiesta HTTP POST all'API di provisioning.

Richiesta API di provisioning per creare il ticket dell'account

Esamina il metodo createAccountTicket nel riferimento dell'API di provisioning per informazioni dettagliate su come effettuare la richiesta.

Risposta dall'API di provisioning

Una richiesta andata a buon fine restituisce una risposta di tipo 200. Il corpo della risposta contiene un ticket account, che è di breve durata. Il ticket dell'account è composto da un ID e i dettagli della nuova struttura ad albero.

Esamina Account Ticket resource nel riferimento dell'API di provisioning per i dettagli sulla risposta.

L'applicazione deve gestire anche le risposte di errore.

3. L'utente accetta i Termini di servizio di Google Analytics

Dopo aver ottenuto un ID ticket account per l'utente, puoi utilizzarlo con la richiesta dei TdS per chiedere all'utente di accettare i Termini di servizio di Google Analytics.

Che cosa serve per completare questo passaggio

Un ID ticket account dell'utente autorizzato.

Il risultato di questo passaggio

Dopo aver completato correttamente il flusso di TdS utilizzando l'ID ticket dell'account, verranno creati l'account, la proprietà e la vista (profilo). Ora l'utente avrà un account attivo. La risposta dalla pagina TdS includerà l'ID account, l'ID proprietà e l'ID vista (profilo).

Flusso tecnico per questo passaggio

Utilizzando l'ID del ticket account, reindirizza l'utente alla pagina dei TdS di Google Analytics dove potrà accettare i TdS, dopodiché dovrai gestire la risposta dall'API.

Forma l'URL dei TdS che l'utente può visitare

Reindirizza l'utente alla pagina dei TdS e includi l'ID ticket dell'account all'interno dell'URL:

https://analytics.google.com/analytics/web/?provisioningSignup=false#/termsofservice/{account_ticket_id}
Gestire la risposta dei TdS

Dopo aver eseguito un'azione nella pagina dei TdS, l'utente verrà reindirizzato al redirectUri specificato durante la creazione dei ticket per l'account. La risposta dalla pagina TdS sarà inclusa nella stringa di query.

Le risposte riuscite restituiranno i dati sulla struttura dell'account appena creata e sulla accountTicketId originale:

https://{YOUR REDIRECT URI for TOS}?
  accountId={accountId}
  &webPropertyId={webPropertyId}
  &profileId={profileId}
  &accountTicketId={accountTicketId}

Ad esempio, se il gestore dei TdS per la tua applicazione si trova su http://www.your-app.com/gaTOS, deve essere impostato come redirectUri durante la creazione di ticket per l'account. Il gestore dei TdS della tua applicazione deve prevedere e gestire correttamente le richieste HTTP GET contenenti i parametri di query accountId, webPropertyId, profileId e accountTicketId nei casi in cui il ticket dell'account sia valido e l'utente abbia accettato i TdS.

Le risposte non riuscite includono la risposta di errore:

https://{YOUR REDIRECT URI for TOS}?
  error={error_code}
  &accountTicketId={accountTicketId}

Il gestore dei TdS deve anche gestire correttamente le richieste HTTP GET contenenti un parametro di query error, che indica che si è verificato un errore. Il valore del parametro di query può essere utilizzato per eseguire ulteriori azioni o per visualizzare un messaggio all'utente:

  • error=user_cancel - L'utente non ha accettato i Termini di servizio.
  • error=max_accounts_reached: l'utente ha raggiunto il limite di account Google Analytics.
  • error=backend_error: un errore generale. Il server ha restituito un errore non incluso nelle categorie precedenti.

4. (Facoltativo) Opportunità di integrazione

Se hai seguito il flusso tecnico riportato sopra, avrai creato un account per l'utente e avrai l'ID account, l'ID proprietà e l'ID vista (profilo). Se hai richiesto autorizzazioni aggiuntive, puoi anche avere un token di aggiornamento per l'utente. Con questi dati puoi:

Flusso utente

Questa sezione descrive le considerazioni sull'implementazione relative ai passaggi del flusso di creazione dell'account dal punto di vista dell'utente.

Il flusso inizia con l'offerta all'utente delle due opzioni seguenti per attivare l'analisi per la sua proprietà:

  1. Crea un account Google Analytics
  2. Utilizza un account Google Analytics esistente. (Nota: questo flusso non è trattato in questo documento. Consulta l'API di gestione per i dettagli su come accedere ai dati di configurazione di Google Analytics di un utente.

Quando crei un nuovo account Google Analytics, devi inviare alcune informazioni con la richiesta di provisioning, ad esempio nome dell'account, nome della proprietà e così via. A seconda delle informazioni che hai sull'utente e del flusso preferito che vuoi mostrare, sono disponibili tre opzioni principali per avviare la procedura dopo che l'utente fa clic su "Crea account":

Chiedere i dettagli dell'account dopo l'autorizzazione

In questo caso, all'utente vengono richiesti i dettagli dell'account a metà della procedura. Il flusso sarà simile al seguente:

  1. L'utente viene reindirizzato al servizio Account Google per il flusso OAuth 2.0. Se l'utente non ha un Account Google o non ha eseguito l'accesso, gli verrà chiesto di creare un Account Google o di accedere.
  2. All'utente viene chiesto di autorizzare l'applicazione per "Crea account Google Analytics".
  3. L'utente accetta la richiesta di autorizzazione per l'applicazione.
  4. L'utente viene reindirizzato al fornitore di servizi. Tieni presente che se l'utente nega l'autorizzazione, viene comunque reindirizzato al fornitore di servizi.
  5. All'utente viene presentato un modulo per raccogliere dettagli sull'account da creare (ad es. nome dell'account, nome della proprietà, nome del profilo, fuso orario, URL del sito web e così via).
  6. L'utente compila e invia il modulo e viene reindirizzato a Google o visualizza i Termini di servizio (TdS) di Google Analytics.
  7. L'utente accetta i TdS.
  8. L'utente viene reindirizzato al fornitore di servizi e viene visualizzato un messaggio che indica che ha creato correttamente un account Google Analytics con i dettagli dell'account e le modalità di accesso. Tieni presente che se l'utente non accetta i TdS, verrà comunque reindirizzato al fornitore di servizi.

Chiedere i dettagli dell'account prima dell'autorizzazione

In questo caso, all'utente vengono richiesti in anticipo i dettagli di configurazione dell'account per essere creato. Il flusso sarà simile al seguente:

  1. Sul sito del fornitore di servizi viene presentato all'utente un modulo per raccogliere i dettagli dell'account da creare (ad es. nome dell'account, nome della proprietà, nome del profilo, fuso orario, URL del sito web).
  2. L'utente compila il modulo, fa clic su Invia e viene reindirizzato al servizio Account Google per il flusso OAuth 2.0. Se l'utente non ha un Account Google o non ha eseguito l'accesso, gli verrà chiesto di creare un Account Google o di accedere.
  3. All'utente viene chiesto di autorizzare l'applicazione per "Crea account Google Analytics".
  4. L'utente accetta le autorizzazioni richieste per l'applicazione.
  5. L'utente viene reindirizzato al fornitore di servizi.
  6. L'utente viene reindirizzato a Google/vengono mostrati i Termini di servizio (TdS) di Google Analytics.
  7. L'utente accetta i TdS.
  8. L'utente viene reindirizzato al fornitore di servizi e viene visualizzato un messaggio che indica che ha creato correttamente un account Google Analytics con i dettagli dell'account e le modalità di accesso.

Precompila i dettagli dell'account o salta i moduli

Se le informazioni sull'account utente sono già disponibili (ad es. URL del sito web, nome del sito web, fuso orario e così via), entrambe le opzioni sopra riportate possono essere ulteriormente semplificate:

  • Precompilare il modulo e consentire all'utente di modificarlo se lo desidera
  • Ignorando del tutto il passaggio del modulo e creando automaticamente l'account utilizzando le informazioni esistenti.