Riferimento client JavaScript per Accedi con Google

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

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

Se riscontri un problema durante l'utilizzo della libreria, segnala il problema al nostro repository di GitHub.

Configurazione autenticazione

Carica la libreria di piattaforme delle 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 di piattaforme, 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, lo configuri con il tuo ID client OAuth 2.0 ed eventuali altre opzioni 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 dei dati di configurazione del client. Consulta gapi.auth2.ClientConfig per informazioni sulle diverse proprietà configurabili. Ad esempio:
{
  client_id: 'CLIENT_ID.apps.googleusercontent.com'
}
Restituisce
gapi.auth2.GoogleAuth L'oggetto gapi.auth2.GoogleAuth. Utilizza il metodo then() per ottenere una promessa che viene risolta quando l'oggetto gapi.auth2.GoogleAuth completa l'inizializzazione.

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 vecchi browser non supportati), verrà richiamata la funzione onError.

Argomenti
onInit La funzione con nome oggetto GoogleAuth in fase di inizializzazione completa.
onError La funzione chiamata con un oggetto contenente una proprietà error se GoogleAuth non è stato inizializzato.
Restituisce
Promessa Un Promise che viene completato quando la funzione onInit è stata completata o rifiutato se viene generato un errore di inizializzazione. Si risolve 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 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 i quali creare cookie di accesso. 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. True se non specificato.
hosted_domain string Il dominio G Suite a cui gli utenti devono appartenere per accedere. Questo è suscettibile di modifica da parte dei client, quindi assicurati di verificare la proprietà del dominio ospitato dell'utente restituito. Utilizza GoogleUser.getHostedDomain() sul client e la rivendicazione hd nel token ID sul server per verificare il dominio come previsto.
ux_mode string La modalità UX da usare per il flusso di accesso. Per impostazione predefinita, 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 redirect_uri predefinito che verrà utilizzato alla fine del flusso di consenso. Il valore predefinito redirect_uri è l'URL corrente privo di parametri di ricerca e frammento hash.
plugin_name string (Facoltativo) Se questo valore è impostato, i nuovi ID client creati prima del 29 luglio 2022 potranno utilizzare la libreria Google Platform precedente. Per impostazione predefinita, ora gli ID client appena creati non possono utilizzare la libreria Platform, ma devono utilizzare la libreria Servizi Google Identity più recente. Puoi scegliere qualsiasi valore; un nome descrittivo, come il nome del prodotto o del plug-in, è consigliato per una facile identificazione. Esempio: plugin_name: 'YOUR_STRING_HERE'

Autenticazione

GoogleAuth è una classe singleton che fornisce metodi per consentire all'utente di accedere con un Account Google, ottenere lo stato di accesso attuale dell'utente, ottenere dati specifici dal profilo Google dell'utente, richiedere ulteriori ambiti 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.

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

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

GoogleAuth.isSignedIn.listen(elenco)

Consente di ascoltare le modifiche relative allo stato di accesso dell'utente corrente.

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

GoogleAuth.signIn()

Consente all'utente di eseguire l'accesso con le opzioni specificate in gapi.auth2.init().

Restituisce
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 (vedi di seguito per i codici di errore).

Codici di errore

Leggi i GoogleAuth.signIn(options).

GoogleAuth.signIn(options)

Consente l'accesso dell'utente utilizzando le opzioni specificate.

Argomenti
options Scegli una di queste opzioni:
  • Un oggetto gapi.auth2.SignInOptions contenente coppie chiave-valore dei 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');
Restituisce
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 (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 agli 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 è necessario utilizzare questa opzione, dato che gapi.auth2.init accederà automaticamente all'utente se ha già eseguito l'accesso 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. (Facoltativo)
I valori possibili sono:
  • consent
    Il server di autorizzazione richiede all'utente il consenso prima di restituire le informazioni all'applicazione.
  • select_account
    Il server di autorizzazione richiede all'utente di selezionare un Account Google. In questo modo, un utente che ha più account può scegliere tra quelli per i quali potrebbe avere sessioni correnti.
  • none (non consigliato)
    Il server di autorizzazione non mostrerà schermate di autenticazione o di consenso dell'utente, ma restituirà un errore se l'utente non è già autenticato e non ha precedentemente acconsentito agli ambiti richiesti.
    Dato che gapi.auth2.init farà automaticamente l'accesso all'applicazione dall'utente, se ha eseguito l'accesso in precedenza, la chiamata a signIn({prompt: 'none'}) di solito non andrà a buon fine.
scope string Gli ambiti da richiedere, come stringa delimitata da spazi, sopra gli ambiti definiti nei parametri gapi.auth2.init. Facoltativo se fetch_basic_profile non è impostato su falso.
ux_mode string La modalità UX da usare per il flusso di accesso. Per impostazione predefinita, 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 redirect_uri predefinito che verrà utilizzato alla fine del flusso di consenso. Il valore predefinito redirect_uri è l'URL corrente privo di parametri di ricerca e frammento hash.

GoogleAuth.signOut()

Disconnette l'account corrente dall'applicazione.

Restituisce
Promessa Promise che viene completato quando l'utente è stato disconnesso.

GoogleAuth.disconnect()

Revoca tutti gli ambiti concessi dall'utente.

GoogleAuth.grantOfflineAccess(options)

Chiedi all'utente l'autorizzazione per accedere agli ambiti specificati offline.

Argomenti
options Un oggetto gapi.auth2.OfflineAccessOptions contenente coppie chiave-valore di parametri. Ad esempio:
{
  scope: 'profile email'
}
Restituisce
Promessa Un Promise che viene soddisfatto quando l'utente concede gli ambiti richiesti, passando un oggetto contenente il codice di autorizzazione al gestore di evasione 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 agli 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 è necessario utilizzare questa opzione, dato che gapi.auth2.init accederà automaticamente all'utente se ha già eseguito l'accesso 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 richiede all'utente il consenso prima di restituire le informazioni all'applicazione.
  • select_account
    Il server di autorizzazione richiede all'utente di selezionare un Account Google. In questo modo, un utente che ha più account può scegliere tra quelli per i quali potrebbe avere sessioni correnti.
scope string Gli ambiti da richiedere, come stringa delimitata da spazi, sopra gli ambiti definiti nei parametri gapi.auth2.init. Facoltativo se fetch_basic_profile non è impostato su falso.

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

Consente di associare il flusso di accesso al gestore di 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 se l'accesso non riesce.

Utenti

Un oggetto GoogleUser rappresenta un account utente. Gli oggetti GoogleUser vengono 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 inizializzata di recente, l'utente corrente non è stato impostato. Utilizza il metodo currentUser.listen() o GoogleAuth.then() per ottenere un'istanza GoogleAuth inizializzata.

Restituisce
GoogleUser L'utente corrente

GoogleAuth.currentUser.listen(listener)

Monitora le modifiche di currentUser.

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

UtenteGoogle.getId()

Recupera la stringa ID unica dell'utente.

Restituisce
Stringa ID univoco dell'utente

GoogleUser.isSignedIn()

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

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

UtenteGoogle.getHostedDomain()

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

Restituisce
Stringa Il dominio G Suite dell'utente

UtenteGoogle.getGrantedScopes()

Recupera gli ambiti che l'utente ha concesso come stringa delimitata da spazi.

Restituisce
Stringa Gli ambiti concessi dall'utente

GoogleUser.getBasicProfile()

Recupera le informazioni di base del profilo dell'utente.

Restituisce
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(includeConsentData)

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

Argomenti
includeAuthorizationData Facoltativo: un valore booleano che specifica se restituire sempre un token e gli ambiti di accesso. 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.
Restituisce
gapi.auth2.AuthResponse Un oggetto gapi.auth2.AuthResponse.

GoogleUser.reloadAuthResponse()

Forza l'aggiornamento del token di accesso, quindi restituisce una promessa per la nuova AuthResponse.

Restituisce
Promise Un Promise completato con il gapi.auth2.AuthResponse ricaricato quando viene ricaricato il token OAuth.

gapi.auth2.AuthResponse

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

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

GoogleUser.hasGrantedScopes(scopes)

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

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

UtenteGoogle.grant(options)

Richiedere ulteriori ambiti all'utente.

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

GoogleUser.grantOfflineAccess(options)

Chiedi all'utente l'autorizzazione 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 UI

gapi.signin2.render(id, options)

Esegue il rendering di 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 eseguire il rendering del pulsante di accesso.
options Un oggetto contenente le impostazioni da utilizzare per visualizzare il 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 esegue l'accesso (impostazione predefinita: profile).
width La larghezza del pulsante in pixel (valore predefinito: 120).
height L'altezza del pulsante in pixel (valore predefinito: 36).
longtitle Mostra etichette lunghe come "Accedi con Google" anziché "Accedi" (impostazione predefinita: false). Quando utilizzi titoli lunghi, dovresti aumentare la larghezza del pulsante rispetto alle impostazioni predefinite.
tema Il tema a colori del pulsante: light o dark (valore predefinito: light).
operazione riuscita La funzione di callback da chiamare quando un utente esegue l'accesso. Questa funzione deve assumere un argomento: un'istanza di gapi.auth2.GoogleUser (valore predefinito: nessuno).
in errore La funzione di callback da chiamare quando l'accesso non riesce. Questa funzione non richiede argomenti (valore predefinito: nessuno).

Avanzate

gapi.auth2.authorized(params, callback)

Esegue un'autorizzazione OAuth 2.0 una tantum. A seconda dei parametri utilizzati, si aprirà una finestra popup del flusso di accesso di Google oppure verrà provata a caricare la risposta richiesta in modalità silenziosa, senza interazione da parte dell'utente.

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

  • L'applicazione deve richiedere un endpoint API Google solo una volta, ad esempio per caricare i video di YouTube preferiti dell'utente al primo accesso.
  • L'applicazione dispone di una propria infrastruttura di gestione delle sessioni e richiede solo un token ID per identificare l'utente nel backend.
  • Nella stessa pagina vengono utilizzati diversi ID client.
Argomenti
params Un oggetto contenente coppie chiave-valore dei dati di configurazione. Consulta gapi.auth2.AuthorizeConfig per informazioni sulle diverse proprietà configurabili. Ad esempio:
{
  client_id: 'CLIENT_ID.apps.googleusercontent.com',
  scope: 'email profile openid',
  response_type: 'id_token permission'
}
callback Una funzione denominata con un oggetto gapi.auth2.AuthorizeResponse in seguito al completamento della richiesta (con esito positivo o con un errore).

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 agli 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 Required. L'ID client dell'app, trovato e creato in Google Developers Console.
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 richiede all'utente il consenso prima di restituire le informazioni all'applicazione.
  • select_account
    Il server di autorizzazione richiede all'utente di selezionare un Account Google. In questo modo, un utente che ha più account può scegliere tra quelli per i quali potrebbe avere sessioni correnti.
  • none
    Il server di autorizzazione non mostra schermate di autenticazione o di consenso degli utenti; restituirà un errore se l'utente non è già autenticato e non ha precedentemente acconsentito agli ambiti richiesti.
    Se viene richiesto code come tipo di risposta, il codice restituito potrà essere scambiato solo con un elemento access_token, non con valore refresh_token.
cookie_policy string I domini per i quali creare cookie di accesso. 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 accedere. Questo è suscettibile di modifiche dai client, quindi assicurati di verificare la proprietà Dominio ospitato dell'utente restituito.
login_hint string L'indirizzo email o ID utente di un utente da preselezionare nel flusso di accesso. Questo è suscettibile di modifica 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 oppure solo gli ambiti richiesti nella chiamata corrente. Il valore predefinito è true.
plugin_name string (Facoltativo) Se questa opzione è impostata, gli ID client creati prima del 29 luglio 2022 possono utilizzare la libreria di Google Platform. Per impostazione predefinita, ai nuovi ID client viene impedito l'utilizzo della Libreria Platform e devono utilizzare la libreria Servizi di identità Google più recente. Puoi scegliere qualsiasi valore; un nome descrittivo, come il nome del prodotto o del plug-in, è consigliato per una facile identificazione. Esempio: plugin_name: 'YOUR_STRING_HERE'

gapi.auth2.AuthorizeResponse

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

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