Riferimento per il client JavaScript di Accedi con Google

Questa pagina di riferimento descrive i metodi e gli attributi del client JavaScript che utilizzerai per implementare Accedi con Google nelle tue applicazioni web.

Se riscontri un problema durante l'utilizzo della libreria, segnalalo nel nostro repository GitHub. .

Configurazione Auth

Carica la libreria della piattaforma API di Google per creare l'oggetto gapi:

<script src="https://apis.google.com/js/platform.js?onload=init" async defer></script>

Dopo aver caricato la libreria della piattaforma, carica la libreria auth2:

function init() {
  gapi.load('auth2', function() {
    /* Ready. Make a call to gapi.auth2.init or some other API */
  });
}

gapi.auth2.init(params)

Inizializza l'oggetto GoogleAuth. Devi chiamare questo metodo prima di chiamare i metodi di gapi.auth2.GoogleAuth.

Quando lo configuri, l'oggetto GoogleAuth viene configurato con il tuo ID client OAuth 2.0 e con eventuali opzioni aggiuntive da specificare. Se l'utente ha già eseguito l'accesso, l'oggetto GoogleAuth ripristina lo stato di accesso dell'utente dalla sessione precedente.

Argomenti
params Un oggetto contenente coppie chiave-valore di dati di configurazione del client. Consulta gapi.auth2.ClientConfig per le diverse proprietà configurabili. Ad esempio: 
{
  client_id: 'CLIENT_ID.apps.googleusercontent.com'
}
Resi
gapi.auth2.GoogleAuth L'oggetto gapi.auth2.GoogleAuth. Utilizza il metodo then() per ottenere una promessa che viene risolta al termine dell'inizializzazione dell'oggetto gapi.auth2.GoogleAuth.

GoogleAuth.then(onInit, onError)

Richiama la funzione onInit quando l'oggetto GoogleAuth è completamente inizializzato. Se viene sollevato un errore durante l'inizializzazione (ciò può accadere nei browser meno recenti non supportati), verrà chiamata la funzione onError.

Argomenti
onInit La funzione chiamata con l'oggetto GoogleAuth quando è completamente inizializzato.
onError La funzione chiamata con un oggetto contenente una proprietà error, se l'inizializzazione di GoogleAuth non è riuscita.
Resi
Promessa Un Promise che viene soddisfatto al termine della funzione onInit o rifiutato se è stato sollevato un errore di inizializzazione. Viene risolto con il valore restituito dalla funzione onInit, se presente.

Codici di errore

idpiframe_initialization_failed
Impossibile inizializzare un iframe richiesto da Google, ad esempio a causa di un ambiente non supportato. Una proprietà details fornirà ulteriori informazioni sull'errore rilevato.

gapi.auth2.ClientConfig

Interfaccia che rappresenta i diversi parametri di configurazione per il metodo gapi.auth2.init.

Parametri
client_id string Obbligatorio. L'ID client dell'app, trovato e creato nella console API di Google.
cookie_policy string I domini per i quali creare cookie di accesso. Un URI, single_host_origin o none. Se non specificato, il valore predefinito è single_host_origin.
scope string Gli ambiti da richiedere, come stringa delimitata da spazi. Facoltativo se fetch_basic_profile non è impostato su false.
fetch_basic_profile boolean Recupera le informazioni di base del profilo degli utenti quando accedono. Aggiunge "profile", "email" e "openid" agli ambiti richiesti. Vero se non specificato.
hosted_domain string Il dominio G Suite a cui gli utenti devono appartenere per accedere. Questo valore è soggetto a modifiche da parte dei client, quindi assicurati di verificare la proprietà del dominio ospitato dell'utente restituito. Utilizza GoogleUser.getHostedDomain() sul client e il claim hd nel token ID sul server per verificare che il dominio sia quello previsto.
use_fedcm boolean Facoltativo, il valore predefinito è True. Attiva o disattiva l'utilizzo delle API FedCM del browser durante l'accesso.
ux_mode string La modalità UX da utilizzare per il flusso di accesso. Per impostazione predefinita, il flusso di consenso si aprirà in un popup. I valori validi sono popup e redirect.
redirect_uri string Se utilizzi ux_mode='redirect', questo parametro ti consente di ignorare il valore predefinito redirect_uri che verrà utilizzato alla fine del flusso di consenso. Il valore predefinito redirect_uri è l'URL corrente privato dei parametri di query e del frammento di hash.
enable_granular_consent boolean Facoltativo. Se abilitare le autorizzazioni granulari. Se impostato su false, le autorizzazioni dell'Account Google più granulari verranno disattivate per gli ID client OAuth creati prima del 2019. Nessun effetto per gli ID client OAuth creati durante o dopo il 2019, poiché per questi sono sempre abilitate autorizzazioni più granulari.
plugin_name string Facoltativo. Se questo valore è impostato, i nuovi Client-ID creati prima del 29 luglio 2022 possono utilizzare la libreria della piattaforma Google precedente. Per impostazione predefinita, gli ID client appena creati non possono più utilizzare la libreria della piattaforma e devono utilizzare la libreria Servizi di identità Google più recente. Puoi scegliere qualsiasi valore, ma per l'identificazione è consigliabile un nome descrittivo come il nome del prodotto o del plug-in. Esempio: plugin_name: 'YOUR_STRING_HERE'

Autenticazione

GoogleAuth è una classe singleton che fornisce metodi per consentire all'utente di accedere con un Account Google, recuperare lo stato di accesso corrente dell'utente, recuperare dati specifici dal profilo Google dell'utente, richiedere ambiti aggiuntivi e uscire dall'account corrente.

gapi.auth2.getAuthInstance()

Restituisce l'oggetto GoogleAuth. Devi inizializzare l'oggetto GoogleAuth con gapi.auth2.init() prima di chiamare questo metodo.

Resi
gapi.auth2.GoogleAuth L'oggetto gapi.auth2.GoogleAuth. Utilizza questo oggetto per chiamare i metodi di gapi.auth2.GoogleAuth.

GoogleAuth.isSignedIn.get()

Restituisce se l'utente corrente ha eseguito l'accesso.

Resi
Booleano true se l'utente ha eseguito l'accesso o false se l'utente non ha eseguito l'accesso o se l'oggetto GoogleAuth non è stato inizializzato.

GoogleAuth.isSignedIn.listen(listener)

Rilevamento delle modifiche dello stato di accesso dell'utente corrente.

Argomenti
listener Una funzione che accetta un valore booleano. listen() passa true a questa funzione quando l'utente accede e false quando l'utente esce.

GoogleAuth.signIn()

Consente all'utente di accedere con le opzioni specificate per gapi.auth2.init().

Resi
Promessa Un Promise che viene soddisfatto con l'istanza GoogleUser quando l'utente autentica e concede correttamente gli ambiti richiesti oppure viene rifiutato con un oggetto contenente una proprietà error se si è verificato un errore. Consulta la sezione successiva per i codici di errore.

Codici di errore

Consulta GoogleAuth.signIn(options).

GoogleAuth.signIn(options)

Consente all'utente di accedere utilizzando le opzioni specificate.

Argomenti
options Una di queste soglie:
  • Un oggetto gapi.auth2.SignInOptions contenente coppie chiave/valore di parametri di accesso. Ad esempio: 
    {
  scope: 'profile email'
}
  • Un'istanza di gapi.auth2.SigninOptionsBuilder. Ad esempio:
    options = new gapi.auth2.SigninOptionsBuilder();
options.setAppPackageName('com.example.app');
options.setFetchBasicProfile(True);
options.setPrompt('select_account');
options.setScope('profile').setScope('email');
Resi
Promessa Un Promise che viene soddisfatto con l'istanza GoogleUser quando l'utente autentica e concede correttamente gli ambiti richiesti oppure rifiutato con un oggetto contenente una proprietà error se si è verificato un errore (vedi di seguito i codici di errore).

Codici di errore

popup_closed_by_user
L'utente ha chiuso il popup prima di completare la procedura di accesso.
access_denied
L'utente ha negato l'autorizzazione per gli ambiti richiesti.
immediate_failed
Nessun utente può essere selezionato automaticamente senza richiedere il flusso di consenso. Errore rilevato quando si utilizza signIn con l'opzione prompt: 'none'. L'utilizzo di questa opzione non dovrebbe essere obbligatorio, poiché gapi.auth2.init consente all'utente di accedere automaticamente se ha eseguito l'accesso in precedenza durante una sessione precedente.

gapi.auth2.SignInOptions

Interfaccia che rappresenta i diversi parametri di configurazione per il metodoGoogleAuth.signIn(options).

Parametri
prompt string Forza una modalità specifica per il flusso di consenso. Facoltativo.
I valori possibili sono:
  • consent
    Il server di autorizzazione chiede all'utente il consenso prima di restituire le informazioni all'applicazione.
  • select_account
    Il server di autorizzazione chiede all'utente di selezionare un Account Google. In questo modo, un utente con più account può selezionare tra i vari account per i quali potrebbe avere sessioni attive.
  • none (non consigliato)
    Il server di autorizzazione non mostrerà schermate di autenticazione o per il consenso dell'utente. Riporterà un errore se l'utente non è già autenticato e non ha precedentemente dato il consenso per gli ambiti richiesti.
    Poiché gapi.auth2.init consente a un utente di accedere automaticamente all'applicazione se ha eseguito l'accesso in precedenza, in genere la chiamata a signIn({prompt: 'none'}) non andrà a buon fine.
scope string Gli ambiti da richiedere, come stringa separata da spazi, oltre agli ambiti definiti nei parametri gapi.auth2.init. Facoltativo se fetch_basic_profile non è impostato su false.
ux_mode string La modalità UX da utilizzare per il flusso di accesso. Per impostazione predefinita, il flusso di consenso si aprirà in un popup. I valori validi sono popup e redirect.
redirect_uri string Se utilizzi ux_mode='redirect', questo parametro ti consente di ignorare il valore predefinito redirect_uri che verrà utilizzato alla fine del flusso per il consenso. Il valore predefinito di redirect_uri è l'URL corrente privato dei parametri di query e del frammento di hash.

GoogleAuth.signOut()

Esce dall'applicazione con l'account corrente.

Resi
Promessa Un Promise che viene soddisfatto quando l'utente è stato disconnesso.

GoogleAuth.disconnect()

Revoca tutti gli ambiti concessi dall'utente.

GoogleAuth.grantOfflineAccess(options)

Ricevere l'autorizzazione dall'utente per accedere agli ambiti specificati offline.

Argomenti
options Un oggetto gapi.auth2.OfflineAccessOptions contenente coppie chiave-valore di parametri. Ad esempio: 
{
  scope: 'profile email'
}
Resi
Promessa Un Promise che viene eseguito quando l'utente concede gli scopi richiesti, passando un oggetto contenente il codice di autorizzazione all'handler di adempimento del Promise. Ad esempio: 
auth2.grantOfflineAccess().then(function(resp) {
  var auth_code = resp.code;
});

Codici di errore

popup_closed_by_user
L'utente ha chiuso il popup prima di completare la procedura di consenso.
access_denied
L'utente ha negato l'autorizzazione per gli ambiti richiesti.
immediate_failed
Nessun utente può essere selezionato automaticamente senza richiedere il flusso di consenso. Errore rilevato quando si utilizza signIn con l'opzione prompt: 'none'. L'utilizzo di questa opzione non dovrebbe essere obbligatorio, poiché gapi.auth2.init consente all'utente di accedere automaticamente se ha eseguito l'accesso in precedenza durante una sessione precedente.

gapi.auth2.OfflineAccessOptions

Interfaccia che rappresenta i diversi parametri di configurazione per il metodo GoogleAuth.grantOfflineAccess(options).

Parametri
prompt string Forza una modalità specifica per il flusso di consenso. Facoltativo.
I valori possibili sono:
  • consent
    Il server di autorizzazione chiede all'utente il consenso prima di restituire le informazioni all'applicazione.
  • select_account
    Il server di autorizzazione chiede all'utente di selezionare un Account Google. In questo modo, un utente con più account può selezionare tra i vari account per i quali potrebbe avere sessioni attive.
scope string Gli ambiti da richiedere, come stringa separata da spazi, oltre agli ambiti definiti nei parametri gapi.auth2.init. Facoltativo se fetch_basic_profile non è impostato su false.

GoogleAuth.attachClickHandler(container, options, onsuccess, onfailure)

Collega il flusso di accesso al gestore dei clic del contenitore specificato.

Argomenti
container L'ID o un riferimento all'elemento div a cui collegare il gestore dei clic.
options Un oggetto contenente coppie chiave/valore di parametri. Vedi GoogleAuth.signIn().
onsuccess La funzione da chiamare al termine dell'accesso.
onfailure La funzione da chiamare in caso di fallimento dell'accesso.

Utenti

Un oggetto GoogleUser rappresenta un account utente. Gli oggetti GoogleUser vengono solitamente ottenuti chiamando GoogleAuth.currentUser.get().

GoogleAuth.currentUser.get()

Restituisce un oggetto GoogleUser che rappresenta l'utente corrente. Tieni presente che in un'istanza GoogleAuth appena inizializzata, l'utente corrente non è stato impostato. Utilizza il metodo currentUser.listen() o GoogleAuth.then() per ottenere un'istanza GoogleAuth inizializzata.

Resi
GoogleUser L'utente corrente

GoogleAuth.currentUser.listen(listener)

Rileva le modifiche in currentUser.

Argomenti
listener Una funzione che accetta un parametro GoogleUser. listen passa a questa funzione un'istanza di GoogleUser a ogni modifica che modifica currentUser.

GoogleUser.getId()

Recupera la stringa ID univoca dell'utente.

Resi
Stringa L'ID univoco dell'utente

GoogleUser.isSignedIn()

Restituisce true se l'utente ha eseguito l'accesso.

Resi
Booleano True se l'utente ha eseguito l'accesso

GoogleUser.getHostedDomain()

Recupera il dominio G Suite dell'utente se ha eseguito l'accesso con un account G Suite.

Resi
Stringa Il dominio G Suite dell'utente

GoogleUser.getGrantedScopes()

Recupera gli ambiti concessi dall'utente come stringa delimitata da spazi.

Resi
Stringa Gli ambiti concessi dall'utente

GoogleUser.getBasicProfile()

Ottenere le informazioni di base del profilo dell'utente.

Resi
gapi.auth2.BasicProfile Puoi recuperare le proprietà di gapi.auth2.BasicProfile con i seguenti metodi:
  • BasicProfile.getId()
  • BasicProfile.getName()
  • BasicProfile.getGivenName()
  • BasicProfile.getFamilyName()
  • BasicProfile.getImageUrl()
  • BasicProfile.getEmail()

GoogleUser.getAuthResponse(includeAuthorizationData)

Recupera l'oggetto di risposta dalla sessione di autenticazione dell'utente.

Argomenti
includeAuthorizationData Facoltativo:un valore booleano che specifica se restituire sempre un token di accesso e gli ambiti. Per impostazione predefinita, il token di accesso e gli ambiti richiesti non vengono restituiti quando fetch_basic_profile è true (il valore predefinito) e non vengono richiesti ambiti aggiuntivi.
Resi
gapi.auth2.AuthResponse Un oggetto gapi.auth2.AuthResponse.

GoogleUser.reloadAuthResponse()

Forza un aggiornamento del token di accesso e restituisce una promessa per la nuova AuthResponse.

Resi
Promise Un Promise che viene soddisfatto con il gapi.auth2.AuthResponse ricaricato al termine del ricaricamento del token OAuth.

gapi.auth2.AuthResponse

La risposta restituita quando vengono chiamati i metodi GoogleUser.getAuthResponse(includeAuthorizationData) o GoogleUser.reloadAuthResponse().

Proprietà
access_token string Il token di accesso concesso.
id_token string L'ID token concesso.
scope string Gli ambiti concessi nel token di accesso.
expires_in number Il numero di secondi che rimangono prima della scadenza del token di accesso.
first_issued_at number Il timestamp in cui l'utente ha concesso per la prima volta gli ambiti richiesti.
expires_at number Il timestamp della scadenza del token di accesso.

GoogleUser.hasGrantedScopes(scopes)

Restituisce true se l'utente ha concesso gli ambiti specificati.

Argomenti
scopes Una stringa di ambiti delimitati da spazi.
Resi
Booleano True se gli ambiti sono stati concessi

GoogleUser.grant(options)

Richiedi all'utente ulteriori ambiti.

Consulta GoogleAuth.signIn() per l'elenco dei parametri e il codice di errore.

GoogleUser.grantOfflineAccess(options)

Ricevere l'autorizzazione dall'utente per accedere agli ambiti specificati offline.

Argomenti
options Un oggetto gapi.auth2.OfflineAccessOptions contenente coppie chiave-valore di parametri. Ad esempio: 
{
  scope: 'profile email'
}

GoogleUser.disconnect()

Revoca tutti gli ambiti concessi dall'utente per l'applicazione.

Elementi dell'interfaccia utente

gapi.signin2.render(id, options)

Mostra un pulsante di accesso nell'elemento con l'ID specificato, utilizzando le impostazioni specificate dall'oggetto options.

Argomenti
id L'ID dell'elemento in cui visualizzare il pulsante di accesso.
options Un oggetto contenente le impostazioni da utilizzare per il rendering del pulsante. Ad esempio: 
{
  scope: 'email',
  width: 200,
  height: 50,
  longtitle: true,
  theme: 'dark',
  onsuccess: handleSuccess,
  onfailure: handleFailure
}
Puoi specificare le seguenti opzioni:
Parametri
ambito Gli ambiti da richiedere quando l'utente accede (valore predefinito: profile).
larghezza La larghezza del pulsante in pixel (valore predefinito: 120).
altezza L'altezza del pulsante in pixel (valore predefinito: 36).
longtitle Mostra etichette lunghe come "Accedi con Google" anziché "Accedi" (valore predefinito: false). Quando utilizzi titoli lunghi, devi aumentare la larghezza del pulsante rispetto al valore predefinito.
tema Il tema di colore del pulsante: light o dark (valore predefinito: light).
onsuccess La funzione di callback da chiamare quando un utente accede correttamente. Questa funzione deve accettare un argomento: un'istanza di gapi.auth2.GoogleUser (valore predefinito: nessuno).
onfailure La funzione di callback da chiamare in caso di errore di accesso. Questa funzione non accetta argomenti (valore predefinito: nessuno).

Avanzate

gapi.auth2.authorize(params, callback)

Esegue un'autorizzazione OAuth 2.0 una tantum. A seconda dei parametri utilizzati, si aprirà un popup per il flusso di accesso a Google o verrà tentata la caricamento della risposta richiesta in silenzio, senza interazione dell'utente.

Ecco alcuni casi d'uso in cui questo metodo è utile:

  • La tua applicazione deve richiedere un endpoint dell'API di Google una sola volta, ad esempio per caricare i video di YouTube preferiti dell'utente la prima volta che accede.
  • La tua applicazione ha una propria infrastruttura di gestione delle sessioni e richiede solo un ID token per identificare l'utente nel tuo backend.
  • Vengono utilizzati più ID client nella stessa pagina.
Argomenti
params Un oggetto contenente coppie chiave-valore di dati di configurazione. Consulta gapi.auth2.AuthorizeConfig per le diverse proprietà configurabili. Ad esempio: 
{
  client_id: 'CLIENT_ID.apps.googleusercontent.com',
  scope: 'email profile openid',
  response_type: 'id_token permission'
}
callback Una funzione chiamata con un oggetto gapi.auth2.AuthorizeResponse dopo il completamento della richiesta (con esito positivo o negativo).

Esempio

gapi.auth2.authorize({
  client_id: 'CLIENT_ID.apps.googleusercontent.com',
  scope: 'email profile openid',
  response_type: 'id_token permission'
}, function(response) {
  if (response.error) {
    // An error happened!
    return;
  }
  // The user authorized the application for the scopes requested.
  var accessToken = response.access_token;
  var idToken = response.id_token;
  // You can also now use gapi.client to perform authenticated requests.
});

Codici di errore

idpiframe_initialization_failed
Impossibile inizializzare un iframe richiesto da Google, ad esempio a causa di un ambiente non supportato. Una proprietà details fornirà ulteriori informazioni sull'errore rilevato.
popup_closed_by_user
L'utente ha chiuso il popup prima di completare la procedura di accesso.
access_denied
L'utente ha negato l'autorizzazione per gli ambiti richiesti.
immediate_failed
Nessun utente può essere selezionato automaticamente senza richiedere il flusso di consenso. Errore rilevato quando si utilizza signIn con l'opzione prompt: 'none'.

gapi.auth2.AuthorizeConfig

Interfaccia che rappresenta i diversi parametri di configurazione per il metodogapi.auth2.authorize.

Proprietà
client_id string Required. L'ID client dell'app, trovato e creato nella console API di Google.
scope string Required. Gli ambiti da richiedere, come stringa delimitata da spazi.
response_type string Un elenco di tipi di risposta delimitati da spazi. Il valore predefinito è 'permission'. I valori possibili sono:
  • id_token, per recuperare un token ID
  • permission (o token) per recuperare un token di accesso
  • code per recuperare un codice di autorizzazione
prompt string Forza una modalità specifica per il flusso di consenso. I valori possibili sono:
  • consent
    Il server di autorizzazione chiede all'utente il consenso prima di restituire le informazioni all'applicazione.
  • select_account
    Il server di autorizzazione chiede all'utente di selezionare un Account Google. In questo modo, un utente con più account può selezionare tra i vari account per i quali potrebbe avere sessioni attive.
  • none
    Il server di autorizzazione non mostrerà schermate di autenticazione o per il consenso dell'utente. Riporterà un errore se l'utente non è già autenticato e non ha precedentemente dato il consenso per gli ambiti richiesti.
    Se viene richiesto code come tipo di risposta, il codice restituito potrà essere scambiato solo per un access_token, non per un refresh_token.
cookie_policy string I domini per i quali creare i cookie di accesso. Un URI, single_host_origin o none. Se non specificato, il valore predefinito è single_host_origin.
hosted_domain string Il dominio G Suite a cui devono appartenere gli utenti per accedere. Questo valore è soggetto a modifiche da parte dei client, quindi assicurati di verificare la proprietà del dominio ospitato dell'utente restituito.
login_hint string L'email o l'ID utente di un utente da preselezionare nel flusso di accesso. Questo valore è soggetto a modifiche da parte dell'utente, a meno che non venga utilizzato prompt: "none".
include_granted_scopes boolean Indica se richiedere un token di accesso che includa tutti gli ambiti precedentemente concessi dall'utente all'app o solo gli ambiti richiesti nella chiamata corrente. Il valore predefinito è true.
enable_granular_consent boolean Facoltativo. Se abilitare le autorizzazioni granulari. Se impostato su false, le autorizzazioni dell'Account Google più granulari verranno disattivate per gli ID client OAuth creati prima del 2019. Nessun effetto per gli ID client OAuth creati durante o dopo il 2019, poiché per questi sono sempre abilitate autorizzazioni più granulari.
plugin_name string Facoltativo. Se impostato, gli ID cliente creati prima del 29 luglio 2022 possono utilizzare la biblioteca della piattaforma Google. Per impostazione predefinita, gli ID client appena creati non possono utilizzare la libreria della piattaforma e devono utilizzare la libreria Servizi di identità Google più recente. Puoi scegliere qualsiasi valore, ma ti consigliamo di utilizzare un nome descrittivo come il nome del prodotto o del plug-in per una facile identificazione. Esempio: plugin_name: 'YOUR_STRING_HERE'

gapi.auth2.AuthorizeResponse

La risposta restituita al callback del metodo gapi.auth2.authorize.

Proprietà
access_token string Il token di accesso concesso. Presente solo se permission o token è stato specificato in response_type.
id_token string L'ID token concesso. Presente solo se id_token è stato specificato in response_type.
code string Il codice di autorizzazione concesso. Presente solo se code è stato specificato in response_type.
scope string Gli ambiti concessi nel token di accesso. Presente solo se permission o token è stato specificato in response_type.
expires_in number Il numero di secondi che rimangono prima della scadenza del token di accesso. Presente solo se in response_type è stato specificato permission o token.
first_issued_at number Il timestamp in cui l'utente ha concesso per la prima volta gli ambiti richiesti. Presente solo se permission o token è stato specificato in response_type.
expires_at number Il timestamp della scadenza del token di accesso. Presente solo se in response_type è stato specificato permission o token.
error string Quando la richiesta non va a buon fine, contiene il codice di errore.
error_subtype string Quando la richiesta non va a buon fine, può contenere informazioni aggiuntive rispetto al codice di errore anche restituito.