Riferimento per il client JavaScript di Accedi con Google

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

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

Configurazione di autenticazione

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>

Al termine del 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 si inizializza l'oggetto GoogleAuth, si configura l'oggetto con l'ID client OAuth 2.0 ed eventuali opzioni aggiuntive da specificare. Quindi, se l'utente ha già eseguito l'accesso, l'oggetto GoogleAuth ripristina lo stato di accesso dell'utente della sessione precedente.

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

GoogleAuth.then(onInit, onError)

Chiama la funzione onInit quando l'oggetto GoogleAuth è completamente inizializzato. Se durante l'inizializzazione viene generato un errore (può verificarsi nei vecchi browser 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
Promise Un Promise che viene soddisfatto quando onInit viene completata o rifiutata se è stato generato un errore di inizializzazione. Si risolve con valore restituito dalla funzione onInit, se presente.

Codici di errore

idpiframe_initialization_failed
Impossibile inizializzare un iframe obbligatorio da Google, ad esempio a causa di una completamente gestito di Google Cloud. Una proprietà details fornirà ulteriori informazioni sull'errore generato.

gapi.auth2.ClientConfig

Interfaccia che rappresenta i diversi parametri di configurazione per 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. Il valore predefinito è single_host_origin se non specificato.
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 account utente informazioni di base del profilo quando eseguono l'accesso. Aggiunge "profilo", "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 modifiche da parte del cliente, quindi assicurati di verificare proprietà del dominio ospitato dell'utente restituito. Utilizza le funzionalità di GoogleUser.getHostedDomain() su il client e l'attestazione hd nel token ID sulla per verificare che il dominio sia quello previsto.
use_fedcm boolean Facoltativo, il valore predefinito è True. Abilita o disabilita l'utilizzo di le API FedCM del browser durante l'accesso.
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 consente di ignorare il valore redirect_uri predefinito che verrà utilizzato al termine del flusso di consenso. La Il valore predefinito redirect_uri è l'URL corrente senza i parametri di ricerca e l'hash .
enable_granular_consent boolean (Facoltativo) Se abilitare granulare autorizzazioni. Se impostato su false, più granulare sarà Google Le autorizzazioni dell'account verranno disattivate per gli ID client OAuth creati prima del giorno 2019. Nessun effetto per gli ID client OAuth creati durante o dopo il 2019, dal momento che autorizzazioni più granulari siano sempre abilitate.
plugin_name string (Facoltativo) Se questo valore viene impostato, i nuovi ID cliente creati prima di luglio Il 29 giugno 2022 potrà utilizzare la libreria della piattaforma Google precedente. Per impostazione predefinita, ai nuovi ID client creati è ora impedito l'utilizzo la libreria della piattaforma e deve utilizzare la versione più recente di Google Identity Libreria di servizi. Puoi scegliere qualsiasi valore, ad esempio un nome descrittivo si consiglia di identificare 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, ottenere 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.

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

GoogleAuth.isSignedIn.get()

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

Resi
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 nello stato di accesso dell'utente corrente.

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

GoogleAuth.signIn()

Accede all'utente con le opzioni specificate su gapi.auth2.init().

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

Codici di errore

Leggi i GoogleAuth.signIn(options).

GoogleAuth.signIn(options)

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

Argomenti
options Una di queste soglie:
  • Un oggetto gapi.auth2.SignInOptions che contiene coppie chiave-valore dei parametri di accesso. Ad esempio: 
    {
  scope: 'profile email'
}
  • Un'istanza di gapi.auth2.SigninOptionsBuilder. Per esempio:
    options = new gapi.auth2.SigninOptionsBuilder();
options.setAppPackageName('com.example.app');
options.setFetchBasicProfile(True);
options.setPrompt('select_account');
options.setScope('profile').setScope('email');
Resi
Promise Un Promise che viene completato con l'istanza GoogleUser quando l'utente autentica e concede gli ambiti richiesti o viene 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 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 utilizzando signIn con l'opzione prompt: 'none'. Questa opzione non deve essere è obbligatorio utilizzare, in quanto gapi.auth2.init eseguirà automaticamente l'accesso dell'utente se aveva effettuato l'accesso durante una sessione precedente.

gapi.auth2.SignInOptions

Interfaccia che rappresenta i diversi parametri di configurazione per 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 il consenso all'utente prima di restituire informazioni sull'applicazione.
  • select_account
    Il server di autorizzazione chiede all'utente di selezionare un Account Google. Questo consente a un utente che ha più account di selezionare tra più account per cui potrebbero avere sessioni in corso.
  • none (sconsigliato)
    Il server di autorizzazione non mostrerà alcuna autenticazione o consenso dell'utente schermate; verrà restituito un errore se l'utente non è già autenticato che non ha già dato il consenso per gli ambiti richiesti.
    Poiché gapi.auth2.init eseguirà automaticamente l'accesso di un utente al se avete eseguito l'accesso in precedenza, la chiamata Generalmente signIn({prompt: 'none'}) non riesce.
scope string Gli ambiti da richiedere, sotto forma di stringa delimitata da spazi, sopra gli ambiti definiti nella gapi.auth2.init parametro. Facoltativo se il criterio 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 consente di eseguire l'override il valore predefinito di redirect_uri che verrà utilizzato alla fine del consenso flusso di lavoro. Il valore predefinito redirect_uri è l'URL corrente rimosso dalla query e il frammento hash.

GoogleAuth.signOut()

Disconnette l'account corrente dall'applicazione.

Resi
Promise Un Promise che viene completato quando l'utente è stato firmato fuori.

GoogleAuth.disconnect()

Revoca tutti gli ambiti concessi dall'utente.

GoogleAuth.grantOfflineAccess(options)

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

Argomenti
options gapi.auth2.OfflineAccessOptions contenente coppie chiave-valore di parametri. Ad esempio: 
{
  scope: 'profile email'
}
Resi
Promise Un Promise che viene completato quando l'utente concede la richiesti, passando un oggetto contenente il codice di autorizzazione gestore del fulfillment 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 terminare 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 utilizzando signIn con l'opzione prompt: 'none'. Questa opzione non deve essere è obbligatorio utilizzare, in quanto gapi.auth2.init eseguirà automaticamente l'accesso dell'utente se aveva effettuato l'accesso durante una sessione precedente.

gapi.auth2.OfflineAccessOptions

Interfaccia che rappresenta i diversi parametri di configurazione per 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 il consenso all'utente prima di restituire informazioni sull'applicazione.
  • select_account
    Il server di autorizzazione chiede all'utente di selezionare un Account Google. Questo consente a un utente che ha più account di selezionare tra più account per cui potrebbero avere sessioni in corso.
di Gemini Advanced.
scope string Gli ambiti da richiedere, sotto forma di stringa delimitata da spazi, sopra gli ambiti definiti nella gapi.auth2.init parametro. Facoltativo se il criterio fetch_basic_profile non è impostato su false.

GoogleAuth.attachClickGestori(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. Consulta: 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. GoogleUser oggetti vengono generalmente ottenuti richiamando GoogleAuth.currentUser.get().

GoogleAuth.currentUser.get()

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

Resi
GoogleUser L'utente corrente

GoogleAuth.currentUser.listen(listener)

Monitora le modifiche nell'utente corrente.

Argomenti
listener Una funzione che richiede un parametro GoogleUser. listen trasmette questa funzione a GoogleUser su ogni modifica che modifica currentUser.

GoogleUser.getId()

Recupera la stringa dell'ID univoco 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 quest'ultimo 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()

Recupera 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 risposta dalla sessione di autenticazione dell'utente.

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

GoogleUser.reloadAuthResponse()

Forza l'aggiornamento del token di accesso e restituisce una Promise per la nuova risposta AuthResponse.

Resi
Promise Un Promise che è esaurito con l'elemento ricaricato gapi.auth2.AuthResponse quando ricarichi il Il token OAuth è stato completato.

gapi.auth2.AuthResponse

La risposta restituita durante la chiamata GoogleUser.getAuthResponse(includeAuthorizationData) o GoogleUser.reloadAuthResponse() di machine learning.

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 prima della scadenza del token di accesso.
first_issued_at number Timestamp in corrispondenza del quale l'utente ha concesso per la prima volta gli ambiti richiesti.
expires_at number 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 delimitata da spazi.
Resi
Booleano True se gli ambiti sono stati concessi

GoogleUser.grant(options)

Richiedi ambiti aggiuntivi all'utente.

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

GoogleUser.grantOfflineAccess(options)

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

Argomenti
options 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 eseguire 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 all'accesso dell'utente (impostazione predefinita: profile).
larghezza La larghezza del pulsante in pixel (valore predefinito: 120).
altezza L'altezza del pulsante in pixel (valore predefinito: 36).
titolo lungo Mostra etichette lunghe, ad esempio "Accedi con Google" anziché "Accedi" (valore predefinito: false). Quando usi titoli lunghi, devi aumentare la larghezza del pulsante rispetto a quella predefinita.
tema Il tema a colori del pulsante: light o dark (valore predefinito: light).
alla 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 caso di errore La funzione di callback da chiamare quando l'accesso non riesce. Questa funzione non accetta argomenti (predefinito: nessuno).

Avanzate

gapi.auth2.PERMISSION(params, callback)

Esegue un'autorizzazione OAuth 2.0 una tantum. In base ai parametri utilizzati, si aprirà una al flusso di accesso di Google o prova 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 dall'utente al primo accesso.
  • L'applicazione dispone di una propria infrastruttura di gestione delle sessioni e richiede solo Token ID una volta sola per identificare l'utente nel tuo backend.
  • All'interno della stessa pagina vengono utilizzati più ID cliente.
di Gemini Advanced.
Argomenti
params Un oggetto contenente coppie chiave-valore di dati di configurazione. Consulta: gapi.auth2.AuthorizeConfig per 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 gapi.auth2.AuthorizeResponse oggetto dopo che la richiesta è stata completata (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 obbligatorio da Google, ad esempio a causa di una completamente gestito di Google Cloud. 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 utilizzando signIn con l'opzione prompt: 'none'.

gapi.auth2.AuthorizeConfig

Interfaccia che rappresenta i diversi parametri di configurazione per gapi.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'. Il possibile 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 il consenso all'utente prima di restituire informazioni sull'applicazione.
  • select_account
    Il server di autorizzazione chiede all'utente di selezionare un Account Google. Questo consente a un utente che ha più account di selezionare tra più account per cui potrebbero avere sessioni in corso.
  • none
    Il server di autorizzazione non mostrerà alcuna autenticazione o consenso dell'utente schermate; verrà restituito un errore se l'utente non è già autenticato che non ha già dato il consenso per gli ambiti richiesti.
    Se viene richiesto code come tipo di risposta, il codice restituito sarà scambiabile con access_token, non con refresh_token.
cookie_policy string I domini per i quali creare cookie di accesso. Un URI, single_host_origin o none. Il valore predefinito è single_host_origin se non specificato.
hosted_domain string Il dominio G Suite a cui gli utenti devono appartenere per accedere. Può essere modificato dai 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. È suscettibile a modifica apportata dall'utente, a meno che non venga utilizzato prompt: "none".
include_granted_scopes boolean 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 corrente. Il valore predefinito è true.
enable_granular_consent boolean (Facoltativo) Se abilitare granulare autorizzazioni. Se impostato su false, più granulare sarà Google Le autorizzazioni dell'account verranno disattivate per gli ID client OAuth creati prima del giorno 2019. Nessun effetto per gli ID client OAuth creati durante o dopo il 2019, dal momento che autorizzazioni più granulari siano sempre abilitate.
plugin_name string (Facoltativo) Se impostato, gli ID client creati prima del 29 luglio 2022 possono utilizzare il valore libreria della piattaforma Google. Per impostazione predefinita, gli ID client appena creati sono bloccati di usare la libreria della piattaforma, ma di usare la versione più recente nella libreria Servizi di identità. Puoi scegliere qualsiasi valore, 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 gapi.auth2.authorize.

Proprietà
access_token string Il token di accesso concesso. Presente solo se permission o token era specificato in response_type.
id_token string Il token ID concesso. Presente solo se id_token è stato specificato nel response_type.
code string Il codice di autorizzazione concesso. Presente solo se code è stato specificato nel 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 prima della scadenza del token di accesso. Presente solo se permission o token è stato specificato in response_type.
first_issued_at number Timestamp in corrispondenza del quale 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 Timestamp della scadenza del token di accesso. Presente solo se permission o token è stato specificato in response_type.
error string Quando la richiesta non è andata a buon fine, contiene codice di errore.
error_subtype string Quando la richiesta non è andata a buon fine, queste informazioni possono contenere anche informazioni aggiuntive sul codice di errore restituito.