Riferimento per il client JavaScript di Accedi con Google

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

Se riscontri problemi nell'utilizzo della libreria, segnalali al nostro repository GitHub.

Configurazione autorizzazione

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 il caricamento della 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 inizializzi l'oggetto GoogleAuth, devi configurarlo con il tuo ID client OAuth 2.0 e le eventuali opzioni aggiuntive che vuoi specificare. Quindi, 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'
}
Ritorni
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 generato un errore durante l'inizializzazione (può verificarsi nei browser precedenti non supportati), verrà richiamata la funzione onError.

Argomenti
onInit La funzione chiamata con l'oggetto GoogleAuth quando è completamente inizializzata.
onError La funzione chiamata con un oggetto contenente una proprietà error, se l'inizializzazione di GoogleAuth non è riuscita.
Ritorni
Promessa Un Promise che viene completato quando la funzione onInit è stata completata o viene rifiutato se è stato generato un errore di inizializzazione. Viene risolto con il valore restituito dall'eventuale funzione onInit.

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 generato.

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 in Google Developers Console.
cookie_policy string I domini per cui creare i cookie di accesso. Può essere un URI, single_host_origin o none. Se non specificato, il valore predefinito è single_host_origin.
scope string Gli ambiti da richiedere, sotto forma di stringa delimitata da spazi. Facoltativo se fetch_basic_profile non è impostato su false.
fetch_basic_profile boolean Recuperare le informazioni di base del profilo degli utenti quando accedono. Aggiunge "profile", "email" e "openid" agli ambiti richiesti. True se non specificato.
hosted_domain string Il dominio G Suite a cui gli utenti devono appartenere per eseguire l'accesso. Questo è 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 l'attestazione hd nel token ID sul server per verificare che il dominio corrisponda a quanto previsto.
ux_mode string La modalità UX da utilizzare per il flusso di accesso. Per impostazione predefinita, si aprirà il flusso di consenso in un popup. I valori validi sono popup e redirect.
redirect_uri string Se utilizzi ux_mode='redirect', questo parametro ti consente di sostituire il valore redirect_uri predefinito che verrà utilizzato al termine del flusso di consenso. Il valore predefinito redirect_uri è l'URL corrente senza parametri di query e frammento hash.
plugin_name string Campo facoltativo. Se questo valore è impostato, i nuovi ID client creati prima del 29 luglio 2022 possono utilizzare la libreria della piattaforma Google precedente. Per impostazione predefinita, gli ID client appena creati non possono utilizzare la libreria della piattaforma e devono invece utilizzare la nuova libreria dei Servizi di identità Google. Puoi scegliere qualsiasi valore. Per una facile identificazione, è consigliato 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, conoscere lo stato di accesso attuale dell'utente, ottenere 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.

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

GoogleAuth.isSignedIn.get()

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

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

GoogleAuth.isSignedIn.listen(listener)

Monitora i cambiamenti 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()

Esegue l'accesso dell'utente con le opzioni specificate in gapi.auth2.init().

Ritorni
Promessa Un elemento Promise completato con l'istanza GoogleUser quando l'utente esegue correttamente l'autenticazione e concede gli ambiti richiesti oppure viene rifiutato con un oggetto contenente una proprietà error in caso di errore (vedi di seguito per i codici di errore).

Codici di errore

Leggi i GoogleAuth.signIn(options).

GoogleAuth.signIn(options)

Consente di accedere all'utente 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');
Ritorni
Promessa Un elemento Promise completato con l'istanza GoogleUser quando l'utente esegue correttamente l'autenticazione e concede gli ambiti richiesti oppure viene rifiutato con un oggetto contenente una proprietà error in caso di errore (vedi di seguito per i codici di errore).

Codici di errore

popup_closed_by_user
L'utente ha chiuso il popup prima di completare il flusso 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 generato quando si utilizza signIn con l'opzione prompt: 'none'. Non deve essere necessario utilizzare questa opzione, perché gapi.auth2.init farà accedere automaticamente l'utente se ha eseguito l'accesso in precedenza durante una sessione precedente.

gapi.auth2.SignInOptions

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

Parametri
prompt string Forza una modalità specifica per il flusso di consenso. Campo facoltativo.
I valori possibili sono:
  • consent
    Il server di autorizzazione richiede all'utente il consenso prima di restituire informazioni all'applicazione.
  • select_account
    Il server di autorizzazione chiede all'utente di selezionare un Account Google. Ciò consente a un utente con più account di selezionare tra i vari account per cui potrebbe avere sessioni correnti.
  • none (sconsigliato)
    Il server di autorizzazione non mostrerà alcuna schermata di autenticazione o di consenso dell'utente; restituirà un errore se l'utente non è già stato autenticato e non ha precedentemente acconsentito agli ambiti richiesti.
    Poiché gapi.auth2.init farà accedere automaticamente un utente all'applicazione se ha eseguito l'accesso in precedenza, in genere le chiamate a signIn({prompt: 'none'}) non riusciranno.
scope string Gli ambiti da richiedere, sotto forma di stringa delimitata da spazi, in aggiunta 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, si aprirà il flusso di consenso in un popup. I valori validi sono popup e redirect.
redirect_uri string Se utilizzi ux_mode='redirect', questo parametro ti consente di eseguire l'override del valore redirect_uri predefinito che verrà utilizzato al termine del flusso di consenso. Il valore predefinito redirect_uri è l'URL corrente senza parametri di query e frammento hash.

GoogleAuth.signOut()

Disconnette l'account corrente dall'applicazione.

Ritorni
Promessa Un Promise che viene compilato quando l'utente è disconnesso.

GoogleAuth.disconnect()

Revoca tutti gli ambiti concessi dall'utente.

GoogleAuth.grantOfflineAccess(options)

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

Argomenti
options Un oggetto gapi.auth2.OfflineAccessOptions contenente coppie chiave-valore di parametri. Ad esempio:
{
  scope: 'profile email'
}
Ritorni
Promessa Un Promise che viene completato quando l'utente concede gli ambiti richiesti, passando un oggetto contenente il codice di autorizzazione al gestore di fulfillment di 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 il flusso 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 generato quando si utilizza signIn con l'opzione prompt: 'none'. Non deve essere necessario utilizzare questa opzione, perché gapi.auth2.init farà accedere automaticamente l'utente 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. Campo facoltativo.
I valori possibili sono:
  • consent
    Il server di autorizzazione richiede all'utente il consenso prima di restituire informazioni all'applicazione.
  • select_account
    Il server di autorizzazione chiede all'utente di selezionare un Account Google. Ciò consente a un utente con più account di selezionare tra i vari account per cui potrebbe avere sessioni correnti.
scope string Gli ambiti da richiedere, sotto forma di stringa delimitata da spazi, in aggiunta 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 container specificato.

Argomenti
container L'ID o un riferimento all'elemento div a cui associare il gestore dei clic.
options Un oggetto contenente coppie chiave-valore di parametri. Vedi GoogleAuth.signIn().
onsuccess La funzione da chiamare dopo il completamento dell'accesso.
onfailure La funzione da chiamare se l'accesso non va a buon fine.

Utenti

Un oggetto GoogleUser rappresenta un account utente. Gli oggetti GoogleUser sono in genere 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.

Ritorni
GoogleUser L'utente corrente

GoogleAuth.currentUser.listen(listener)

Attendi le modifiche in currentUser.

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

GoogleUser.getId()

Recupera la stringa ID univoca dell'utente.

Ritorni
Stringa L'ID univoco dell'utente

GoogleUser.isSignedIn()

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

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

GoogleUser.getHostedDomain()

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

Ritorni
Stringa Il dominio G Suite dell'utente

GoogleUser.getGrantedScopes()

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

Ritorni
Stringa Gli ambiti concessi dall'utente

GoogleUser.getBasicProfile()

Recupera le informazioni di base del profilo dell'utente.

Ritorni
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 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 (valore predefinito) e non vengono richiesti ambiti aggiuntivi.
Ritorni
gapi.auth2.AuthResponse Un oggetto gapi.auth2.AuthResponse.

GoogleUser.reloadAuthResponse()

Forza un aggiornamento del token di accesso, quindi restituisce una Promise per la nuova risposta AuthResponse.

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

gapi.auth2.AuthResponse

La risposta restituita durante la chiamata dei metodi GoogleUser.getAuthResponse(includeAuthorizationData) o GoogleUser.reloadAuthResponse().

Proprietà
access_token string Il token di accesso concesso.
id_token string Il token ID concesso.
scope string Gli ambiti concessi nel token di accesso.
expires_in number Il numero di secondi che mancano alla 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 di scadenza del token di accesso.

GoogleUser.hasGrantedScopes(scopes)

Restituisce true se all'utente sono stati concessi gli ambiti specificati.

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

GoogleUser.grant(options)

Richiedi ambiti aggiuntivi all'utente.

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

GoogleUser.grantOfflineAccess(options)

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

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 UI

gapi.signin2.render(id, options)

Visualizza 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).
width La larghezza del pulsante in pixel (valore predefinito: 120).
altezza L'altezza del pulsante in pixel (valore predefinito: 36).
titolo lungo Mostra etichette lunghe, come "Accedi con Google" anziché "Accedi" (valore predefinito: false). Quando usi titoli lunghi, dovresti aumentare la larghezza del pulsante rispetto all'impostazione predefinita.
tema Il tema a colori del pulsante: light o dark (valore predefinito: light).
insuccesso La funzione di callback da chiamare quando un utente accede. Questa funzione deve utilizzare un argomento: un'istanza di gapi.auth2.GoogleUser (valore predefinito: nessuno).
onfailure La funzione di callback da chiamare quando l'accesso non va a buon fine. Questa funzione non accetta argomenti (valore predefinito: nessuno).

Avanzato

gapi.auth2.authorized(params, callback)

Esegue un'autorizzazione OAuth 2.0 una tantum. A seconda dei parametri utilizzati, si aprirà un popup del flusso di accesso di Google o si proverà a caricare la risposta richiesta in modalità invisibile, senza interazione dell'utente.

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

  • L'applicazione deve richiedere un endpoint API di Google solo una volta, ad esempio per caricare i video di YouTube preferiti dell'utente al primo accesso.
  • L'applicazione ha la propria infrastruttura di gestione delle sessioni e richiede il token ID una sola volta per identificare l'utente nel backend.
  • Nella stessa pagina vengono utilizzati diversi ID client.
Argomenti
params Un oggetto contenente coppie chiave-valore di dati di configurazione. Consulta gapi.auth2.AuthorizeConfig per conoscere 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 generato.
popup_closed_by_user
L'utente ha chiuso il popup prima di completare il flusso 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 generato quando si utilizza signIn con l'opzione prompt: 'none'.

gapi.auth2.AuthorizeConfig

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

Proprietà
client_id string Obbligatorio. L'ID client dell'app, trovato e creato in Google Developers Console.
scope string Obbligatorio. Gli ambiti da richiedere, sotto forma di 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 richiede all'utente il consenso prima di restituire informazioni all'applicazione.
  • select_account
    Il server di autorizzazione chiede all'utente di selezionare un Account Google. Ciò consente a un utente con più account di selezionare tra i vari account per cui potrebbe avere sessioni correnti.
  • none
    Il server di autorizzazione non mostrerà alcuna schermata di autenticazione o di consenso degli utenti; restituirà un errore se l'utente non è già stato autenticato e non ha precedentemente acconsentito agli ambiti richiesti.
    Se viene richiesto code come tipo di risposta, il codice restituito sarà scambiabile solo con un access_token, non con un refresh_token.
cookie_policy string I domini per cui creare i cookie di accesso. Può essere 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 gli utenti devono appartenere per eseguire l'accesso. Questo è 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 lo User-ID di un utente da preselezionare nel flusso di accesso. Questa opzione è soggetta 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 concessi in precedenza dall'utente all'app o solo gli ambiti richiesti nella chiamata in corso. Il valore predefinito è true.
plugin_name string Campo facoltativo. Se impostato, gli ID client creati prima del 29 luglio 2022 possono utilizzare la libreria della piattaforma Google. Per impostazione predefinita, agli ID client appena creati viene bloccato l'utilizzo della libreria della piattaforma, che devono invece utilizzare la nuova libreria dei Servizi di identità Google. Puoi scegliere qualsiasi valore. Per una facile identificazione, è consigliato un nome descrittivo, ad esempio il nome del prodotto o del plug-in. Esempio: plugin_name: 'YOUR_STRING_HERE'

gapi.auth2.AuthorizeResponse

La risposta è stata 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 nel response_type.
id_token string Il token ID 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 nel response_type.
expires_in number Il numero di secondi che mancano alla scadenza del token di accesso. Presente solo se permission o token è stato specificato nel response_type.
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 nel response_type.
expires_at number Il timestamp di scadenza del token di accesso. Presente solo se permission o token è stato specificato nel response_type.
error string Se la richiesta non va a buon fine, contiene il codice di errore.
error_subtype string Quando la richiesta non è andata a buon fine, questo può contenere ulteriori informazioni rispetto al codice di errore restituito.