Questo 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, segnala l'errore nel nostro repository di 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>
Una volta caricata 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 inizializza l'oggetto GoogleAuth
, lo configuri con l'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 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' } |
Valori restituiti | |
---|---|
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 si verifica un errore durante l'inizializzazione (questa operazione può verificarsi nei browser non supportati meno recenti), 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 GoogleAuth non è stato inizializzato.
|
Valori restituiti | |
---|---|
Promessa | Un Promise completato quando la funzione onInit è stata completata o rifiutata se è stato generato 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 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. Può essere 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 falso. |
fetch_basic_profile |
boolean |
Recuperare 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
è suscettibile di modifiche da parte dei client, quindi assicurati di verificare la
proprietà del dominio ospitato dell'utente restituito. Utilizza
GoogleUser.getHostedDomain() sul
client e la richiesta hd nel token ID del
server per verificare che il dominio sia quello previsto.
|
ux_mode |
string |
La modalità UX da usare per il flusso di accesso. Per impostazione predefinita, apre 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 alla fine del flusso di consenso. Il valore predefinito redirect_uri è l'URL corrente rimosso dai parametri di query e dal frammento hash.
|
plugin_name |
string |
(Facoltativo) Se questo valore è impostato, i nuovi ID client creati prima del 29 luglio 2022 possono utilizzare la libreria Google Platform precedente.
Per impostazione predefinita, gli ID client appena creati non possono più utilizzare la libreria della piattaforma, ma devono utilizzare la libreria dei servizi Google Identity più recente. Puoi scegliere qualsiasi valore; per la facile identificazione, ti consigliamo di utilizzare un nome descrittivo, ad esempio 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 suo profilo Google, 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.
Valori restituiti | |
---|---|
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.
Valori restituiti | |
---|---|
Booleano |
true se l'utente ha eseguito l'accesso o false se non ha eseguito l'accesso o l'oggetto GoogleAuth non è inizializzato.
|
GoogleAuth.isSignedIn.listen(listener)
Consente di ascoltare le modifiche nello 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 per la disconnessione.
|
GoogleAuth.signin()
Esegue l'accesso dell'utente con le opzioni specificate per gapi.auth2.init()
.
Valori restituiti | |
---|---|
Promessa | Un elemento Promise completato 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)
Esegue l'accesso dell'utente utilizzando le opzioni specificate.
Argomenti | |
---|---|
options |
Procedi in uno dei seguenti modi:
|
Valori restituiti | |
---|---|
Promessa | Un elemento Promise completato 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 per gli ambiti richiesti.
immediate_failed
-
Non è possibile selezionare automaticamente nessun utente senza richiedere il flusso di consenso. Errore durante l'utilizzo di
signIn
con l'opzioneprompt: 'none'
. Questa opzione non deve essere utilizzata, in quantogapi.auth2.init
eseguirà automaticamente l'accesso dell'utente se aveva 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:
|
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, apre 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 alla fine del flusso di consenso. Il valore predefinito redirect_uri è l'URL corrente rimosso dai parametri di query e dal frammento hash.
|
GoogleAuth.signOut()
Esci dall'account corrente dall'applicazione.
Valori restituiti | |
---|---|
Promessa | Un 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 offline agli ambiti specificati.
Argomenti | |
---|---|
options |
Un oggetto gapi.auth2.OfflineAccessOptions
contenente le coppie chiave-valore di parametri. Ad esempio: { scope: 'profile email' } |
Valori restituiti | |
---|---|
Promessa | Un Promise che viene soddisfatto 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
-
Non è possibile selezionare automaticamente nessun utente senza richiedere il flusso di consenso. Errore durante l'utilizzo di
signIn
con l'opzioneprompt: 'none'
. Questa opzione non deve essere utilizzata, in quantogapi.auth2.init
eseguirà automaticamente l'accesso dell'utente se aveva 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:
|
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)
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 di 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
appena inizializzata, l'utente corrente non è stato impostato. Utilizza il metodo currentUser.listen()
o GoogleAuth.then()
per ottenere un'istanza GoogleAuth
inizializzata.
Valori restituiti | |
---|---|
GoogleUser |
L'utente corrente |
GoogleAuth.currentUser.listen(listener)
Consente di ascoltare le modifiche in currentUser.
Argomenti | |
---|---|
listener |
Una funzione che accetta un parametro GoogleUser .
listen trasmette questa funzione un'istanza GoogleUser a ogni modifica che modifica currentUser .
|
UtenteGoogle.getId()
Recupera la stringa ID univoca dell'utente.
Valori restituiti | |
---|---|
Stringa | L'ID univoco dell'utente. |
UtenteGoogle.isSignedIn()
Restituisce true se l'utente ha eseguito l'accesso.
Valori restituiti | |
---|---|
Booleano | True se l'utente ha eseguito l'accesso |
GoogleUser.getHostedDomain()
Richiedi il dominio G Suite dell'utente se quest'ultimo ha eseguito l'accesso con un account G Suite.
Valori restituiti | |
---|---|
Stringa | Il dominio G Suite dell'utente. |
UtenteGoogle.getGrantedScopes()
Recupera gli ambiti che l'utente ha concesso come stringa delimitata da spazi.
Valori restituiti | |
---|---|
Stringa | Gli ambiti concessi dall'utente |
UtenteGoogle.GetBaseprofile()
Visualizzare le informazioni di base del profilo dell'utente.
Valori restituiti | |
---|---|
gapi.auth2.BasicProfile |
Puoi recuperare le proprietà di gapi.auth2.BasicProfile
con i seguenti metodi:
|
GoogleUser.getAuthResponse(includePermissionData)
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 sono richiesti ambiti aggiuntivi. |
Valori restituiti | |
---|---|
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.
Valori restituiti | |
---|---|
Promise |
Un Promise che viene completato con gapi.auth2.AuthResponse ricaricato quando viene ricaricato il token OAuth.
|
gapi.auth2.AuthResponse
La risposta è stata restituita durante la chiamata ai 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 fino 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. |
Valori restituiti | |
---|---|
Booleano | True se gli ambiti sono stati concessi |
UtenteGoogle.grant (options)
Richiedere ambiti aggiuntivi all'utente.
Consulta GoogleAuth.signIn()
per l'elenco dei parametri e il codice di errore.
UtenteGoogle.grantOfflineAccess(options)
Chiedi all'utente l'autorizzazione per accedere offline agli ambiti specificati.
Argomenti | |
---|---|
options |
Un oggetto gapi.auth2.OfflineAccessOptions
contenente le coppie chiave-valore di parametri. Ad esempio: { scope: 'profile email' } |
Google.disconnect()
Revoca tutti gli ambiti che l'utente ha concesso 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 eseguire il rendering del 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:
|
Avanzati
gapi.auth2.authorized(params, callback)
Esegue un'autorizzazione OAuth 2.0 una tantum. A seconda dei parametri utilizzati, verrà aperta una finestra popup del flusso dell'accesso di Google o verrà tentata di caricare la risposta richiesta senza alcuna 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 la prima volta che esegue l'accesso.
- L'applicazione dispone di una propria infrastruttura di gestione delle sessioni e richiede il token ID una sola volta per identificare l'utente nel backend.
- Diversi ID client sono utilizzati nella stessa pagina.
Argomenti | |
---|---|
params |
Un oggetto contenente coppie chiave-valore dei dati di configurazione. Consulta
gapi.auth2.AuthorizeConfig per informazioni sulle
varie 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 che la richiesta è stata completata (correttamente 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 per gli ambiti richiesti.
immediate_failed
-
Non è possibile selezionare automaticamente nessun utente senza richiedere il flusso di consenso. Errore durante l'utilizzo di
signIn
con l'opzioneprompt: '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 del tipo di risposta delimitato da spazi. Il valore predefinito è 'permission' . I valori possibili sono:
|
prompt |
string |
Forza una modalità specifica per il flusso di consenso. I valori possibili sono:
|
cookie_policy |
string |
I domini per i quali creare 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 accedere. Questo può essere modificato dai client, quindi assicurati di verificare la proprietà del dominio ospitato dell'utente restituito. |
login_hint |
string |
L'indirizzo email, o lo User-ID, di un utente da preselezionare nel flusso di accesso. Ciò è suscettibile di 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 oppure solo gli ambiti richiesti nella chiamata attuale. 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, per gli ID client appena creati
l'utilizzo della Libreria Platform non è consentito e deve utilizzare la libreria dei servizi
Google Identity più recente. Puoi scegliere qualsiasi valore; per la facile identificazione è consigliabile utilizzare 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 sono stati specificati in 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 sono stati specificati in response_type .
|
expires_in |
number |
Il numero di secondi fino alla scadenza del token di accesso. Presente solo se permission o token sono stati specificati 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 permission o token sono stati specificati in response_type .
|
expires_at |
number |
Il timestamp alla scadenza del token di accesso. Presente solo se permission o token sono stati specificati in response_type .
|
error |
string |
Se la richiesta non è andata a buon fine, contiene il codice di errore. |
error_subtype |
string |
Quando la richiesta non va a buon fine, possono essere fornite informazioni aggiuntive sul codice di errore. |