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 con l'utilizzo della libreria, segnalali al nostro repository di GitHub.
Configurazione autorizzazione
Carica la libreria della piattaforma delle 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
, configuri l'oggetto con il tuo 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 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 . Usa il metodo then() per ottenere una Promise 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ò accadere 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 valore Promise completato quando la funzione onInit è stata completata o rifiutato in caso di 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à maggiori 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, 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 accedere. Questa
è soggetta 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 sia come previsto.
|
ux_mode |
string |
La modalità UX da utilizzare per il flusso di accesso. Per impostazione predefinita, il flusso di consenso si aprirà in un popup. I valori validi sono popup e redirect . |
redirect_uri |
string |
Se utilizzi ux_mode='redirect' , questo parametro ti consente di sostituire il valore redirect_uri predefinito che verrà utilizzato alla fine del flusso di consenso. Il valore predefinito redirect_uri è l'URL corrente privo dei parametri di query e del frammento hash.
|
plugin_name |
string |
Campo facoltativo. Se questo valore viene 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 di piattaforma e devono invece utilizzare la più recente libreria dei Servizi di identità Google. Puoi scegliere qualsiasi valore. Per una facile identificazione, è consigliabile utilizzare 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, 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.
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 oppure false se
l'utente è disconnesso o l'oggetto GoogleAuth non è
inizializzato.
|
GoogleAuth.isSignedIn.listen(listener)
Esamina i cambiamenti 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 quando l'utente esce.
|
GoogleAuth.signIn()
Consente di accedere all'utente con le opzioni specificate in gapi.auth2.init()
.
Ritorni | |
---|---|
Promessa | Un Promise completato con l'istanza GoogleUser quando
l'utente autentica e concede gli ambiti richiesti oppure viene rifiutato con un oggetto
contenente una proprietà error se si è verificato un errore (vedi di seguito 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:
|
Ritorni | |
---|---|
Promessa | Un Promise completato con l'istanza GoogleUser quando
l'utente autentica e concede gli ambiti richiesti oppure 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 la procedura di consenso. Si è verificato un errore durante l'utilizzo di
signIn
con l'opzioneprompt: 'none'
. Questa opzione non deve essere obbligatoria per utilizzare questa opzione, perché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. Campo facoltativo. I valori possibili sono:
|
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, il flusso di consenso si aprirà in un popup. I valori validi sono popup e redirect . |
redirect_uri |
string |
Se utilizzi ux_mode='redirect' , questo parametro ti consente di sostituire
il valore predefinito di redirect_uri che verrà utilizzato alla fine del flusso
di consenso. Il valore predefinito redirect_uri è l'URL corrente privo dei parametri di ricerca e del 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)
Richiedi all'utente l'autorizzazione 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 del 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 terminare la procedura di consenso.
access_denied
- L'utente ha negato l'autorizzazione per gli ambiti richiesti.
immediate_failed
-
Nessun utente può essere selezionato automaticamente senza richiedere la procedura di consenso. Si è verificato un errore durante l'utilizzo di
signIn
con l'opzioneprompt: 'none'
. Questa opzione non deve essere obbligatoria per utilizzare questa opzione, perché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. Campo facoltativo. I valori possibili sono:
|
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 contenitore specificato.
Argomenti | |
---|---|
container | L'ID o un riferimento all'elemento div a cui associare il gestore di 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.
In genere gli oggetti GoogleUser
si ottengono 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. Usa il metodo currentUser.listen()
o GoogleAuth.then()
per ottenere un'istanza GoogleAuth
inizializzata.
Ritorni | |
---|---|
GoogleUser |
L'utente corrente |
GoogleAuth.currentUser.listen(listener)
Ascolta le modifiche nell'utente corrente.
Argomenti | |
---|---|
listener |
Una funzione che accetta un parametro GoogleUser .
listen passa a questa funzione 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 ha eseguito l'accesso con un account G Suite.
Ritorni | |
---|---|
Stringa | Il dominio G Suite dell'utente |
GoogleUser.getGrantedScopes()
Visualizza 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:
|
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 sono 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 AuthResponse.
Ritorni | |
---|---|
Promise |
Un Promise completato con il gapi.auth2.AuthResponse ricaricato al termine del ricaricamento del token OAuth.
|
gapi.auth2.AuthResponse
La risposta 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 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 l'utente ha concesso gli ambiti specificati.
Argomenti | |
---|---|
scopes | Una stringa di ambiti delimitata da spazi. |
Ritorni | |
---|---|
Booleano | True se gli ambiti sono stati concessi |
GoogleUser.grant(options)
Richiedi ambiti aggiuntivi all'utente.
Consulta GoogleAuth.signIn()
per l'elenco dei
parametri e il codice di errore.
GoogleUser.grantOfflineAccess(options)
Richiedi all'utente l'autorizzazione 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:
|
Avanzato
gapi.auth2.authorized(params, callback)
Esegue un'autorizzazione OAuth 2.0 una tantum. A seconda dei parametri utilizzati, si aprirà un popup nel 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 dispone della 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
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 il completamento della richiesta (con successo 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à maggiori 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 la procedura di consenso. Si è verificato un 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 |
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:
|
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. Questa è suscettibile di modifiche da parte dei client, quindi assicurati di verificare la proprietà del dominio ospitato dell'utente restituito. |
login_hint |
string |
L'indirizzo email, o ID utente, 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 precedentemente concessi 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 impedito l'utilizzo della libreria di piattaforma e devono invece utilizzare la più recente 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 |
Codice di autorizzazione concesso. Presente solo se code è stato specificato in
response_type .
|
scope |
string |
Gli ambiti concessi nel token di accesso. Presente solo se permission o
token è stato specificato in response_type .
|
expires_in |
number |
Il numero di secondi che mancano alla scadenza del token di accesso. Presente solo se permission
o token è stato specificato 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 è stato specificato in response_type .
|
expires_at |
number |
Il timestamp di scadenza del token di accesso. Presente solo se permission
o token è stato specificato in response_type .
|
error |
string |
Se la richiesta non è andata a buon fine, questo contiene il codice di errore. |
error_subtype |
string |
Quando la richiesta non è andata a buon fine, questo contenuto può contenere informazioni aggiuntive rispetto al codice di errore restituito. |