Riferimento API HTML per l'accesso con Google

Questa pagina di riferimento descrive l'API per i dati HTML di Accedi con Google. Puoi usare l'API per visualizzare il prompt One Tap o il pulsante Accedi con Google sulle tue pagine web.

Elemento con ID "g_id_onload".

Puoi inserire gli attributi dei dati di Accedi con Google in tutti gli elementi visibili o invisibili, come <div> e <span>. L'unico requisito è che l'ID elemento sia impostato su g_id_onload. Non inserire questo ID in più elementi.

Attributi dei dati

La seguente tabella elenca gli attributi dei dati con le relative descrizioni:

Attributo
data-client_id	L'ID client della tua applicazione
data-auto_prompt	Tocca Google One.
data-auto_select	Attiva la selezione automatica su Google One Tap.
data-login_uri	L'URL del tuo endpoint di accesso
data-callback	Nome della funzione di gestione del token ID JavaScript
data-native_login_uri	L'URL del tuo endpoint di gestione delle credenziali della password
data-native_callback	Nome della funzione di gestione delle credenziali della password JavaScript
data-native_id_param	Il nome del parametro per il valore credential.id
data-native_password_param	Il nome del parametro per il valore credential.password
data-cancel_on_tap_outside	Consente di stabilire se annullare la richiesta se l'utente fa clic al di fuori della richiesta.
data-prompt_parent_id	L'ID DOM dell'elemento container per la richiesta One Tap
data-skip_prompt_cookie	Salta One Tap se il cookie specificato ha un valore non vuoto.
data-nonce	Una stringa casuale per i token ID
data-context	Il titolo e le parole nel prompt di One Tap
data-moment_callback	Il nome della funzione del listener di notifiche di stato dell'interfaccia utente del prompt
data-state_cookie_domain	Se devi chiamare One Tap nel dominio principale e nei relativi sottodomini, passa il dominio principale a questo attributo in modo che venga utilizzato un singolo cookie condiviso.
data-ux_mode	Flusso UX del pulsante Accedi con Google
data-allowed_parent_origin	Le origini autorizzate a incorporare l'iframe intermedio. Se è presente questo attributo, verrà eseguito One Tap in modalità iframe intermedia.
data-intermediate_iframe_close_callback	Esegue l'override del comportamento predefinito dell'iframe intermedio quando gli utenti chiudono manualmente One Tap.
data-itp_support	Abilita l'upgrade dell'esperienza utente di One Tap sui browser ITP.

Tipi di attributi

Le seguenti sezioni contengono i dettagli di ciascun attributo e un esempio.

data-client_id

Questo attributo è l'ID client della tua app, che puoi trovare e creare nella Google Developers Console. Per ulteriori informazioni, consulta la seguente tabella:

Tipo	Obbligatorio	Esempio
string	Sì	data-client_id="CLIENT_ID.apps.googleusercontent.com"

data-auto_prompt

Questo attributo determina se visualizzare o meno One Tap. Il valore predefinito è true. Google One non verrà visualizzato quando questo valore è false. Per ulteriori informazioni, consulta la tabella seguente:

Tipo	Obbligatorio	Esempio
boolean	Facoltativo	data-auto_prompt="true"

data-auto_select

Questo attributo determina se restituire o meno automaticamente un token ID, senza alcuna interazione dell'utente, se solo una sessione Google ha approvato la tua app. Il valore predefinito è false. Per ulteriori informazioni, consulta la seguente tabella:

Tipo	Obbligatorio	Esempio
boolean	Facoltativo	data-auto_select="true"

data-login_uri

Questo attributo è l'URI del tuo endpoint di accesso. Può essere omesso se la pagina corrente è la tua pagina di accesso, nel qual caso le credenziali vengono pubblicate in questa pagina per impostazione predefinita.

La risposta delle credenziali del token ID viene pubblicata nell'endpoint di accesso quando non è definita alcuna funzione di callback e un utente fa clic sui pulsanti Accedi con Google o One Tap oppure viene eseguita la firma automatica.

Per ulteriori informazioni, consulta la seguente tabella:

Tipo	Facoltativo	Esempio
URL	Il valore predefinito è l'URI della pagina corrente o il valore specificato. Ignorata quando data-ux_mode="popup" e data-callback sono impostati.	data-login_uri="https://www.example.com/login"

L'endpoint di accesso deve gestire le richieste POST che contengono una chiave credential con un valore del token ID nel corpo.

Di seguito è riportato un esempio di richiesta all'endpoint di accesso:

POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

credential=ID_TOKEN

richiamata

Questo attributo è il nome della funzione JavaScript che gestisce il token ID restituito. Per ulteriori informazioni, consulta la seguente tabella:

Tipo	Obbligatorio	Esempio
string	Obbligatorio se data-login_uri non è impostato.	data-callback="handleToken"

È possibile utilizzare uno degli attributi data-login_uri e data-callback. Dipende dalle seguenti configurazioni dei componenti e della modalità UX:

• L'attributo data-login_uri è obbligatorio per il pulsante Accedi con Google redirect Modalità UX, che ignora l'attributo data-callback.

• Uno di questi due attributi deve essere impostato per Google One Tap e il pulsante Accedi con Google modalità UX popup. Se entrambi sono impostati, l'attributo data-callback ha una precedenza maggiore.

Le funzioni JavaScript all'interno di uno spazio dei nomi non sono supportate dall'API HTML. Utilizza invece una funzione JavaScript globale senza uno spazio dei nomi. Ad esempio, utilizza mylibCallback invece di mylib.callback.

data-native_login_uri

Questo attributo è l'URL dell'endpoint di gestione delle credenziali della password. Se imposti l'attributo data-native_login_uri o l'attributo data-native_callback, la libreria JavaScript torna al gestore di credenziali nativo quando non c'è una sessione Google. Non puoi impostare entrambi gli attributi data-native_callback e data-native_login_uri. Per ulteriori informazioni, consulta la tabella seguente:

Tipo	Obbligatorio	Esempio
string	Facoltativo	data-login_uri="https://www.example.com/password_login"

data-native_callback

Questo attributo è il nome della funzione JavaScript che gestisce le credenziali password restituite dal gestore credenziali nativo del browser. Se imposti l'attributo data-native_login_uri o l'attributo data-native_callback, la libreria JavaScript torna al gestore di credenziali nativo quando non c'è una sessione Google. Non puoi impostare sia data-native_callback sia data-native_login_uri. Per informazioni aggiuntive, consulta la tabella seguente:

Tipo	Obbligatorio	Esempio
string	Facoltativo	data-native_callback="handlePasswordCredential"

Le funzioni JavaScript all'interno di uno spazio dei nomi non sono supportate dall'API HTML. Utilizza invece una funzione JavaScript globale senza uno spazio dei nomi. Ad esempio, utilizza mylibCallback invece di mylib.callback.

data-native_id_param

Quando invii le credenziali della password all'endpoint del gestore delle credenziali della password, puoi specificare il nome del parametro per il campo credential.id. Il nome predefinito è email. Per ulteriori informazioni, consulta la seguente tabella:

Tipo	Obbligatorio	Esempio
URL	Facoltativo	data-native_id_param="user_id"

data-native_password_param

Quando invii le credenziali della password all'endpoint del gestore delle credenziali della password, puoi specificare il nome del parametro per il valore credential.password. Il nome predefinito è password. Per ulteriori informazioni, consulta la tabella seguente:

Tipo	Obbligatorio	Esempio
URL	Facoltativo	data-native_password_param="pwd"

data-cancel_on_tap_outside

Questo attributo consente di specificare se annullare o meno la richiesta One Tap se l'utente fa clic all'esterno della richiesta. Il valore predefinito è true. Per disattivarlo, imposta il valore su false. Per ulteriori informazioni, consulta la seguente tabella:

Tipo	Obbligatorio	Esempio
boolean	Facoltativo	data-cancel_on_tap_outside="false"

data-prompt_parent_id

Questo attributo imposta l'ID DOM dell'elemento container. Se non è impostata, viene visualizzata la richiesta One Tap nell'angolo in alto a destra della finestra. Per ulteriori informazioni, consulta la tabella seguente:

Tipo	Obbligatorio	Esempio
string	Facoltativo	data-prompt_parent_id="parent_id"

data-skip_prompt_cookie

Questo attributo ignora One Tap se il cookie specificato ha un valore non vuoto. Per ulteriori informazioni, consulta la tabella seguente:

Tipo	Obbligatorio	Esempio
string	Facoltativo	data-skip_prompt_cookie="SID"

data-nonce

Questo attributo è una stringa casuale utilizzata dal token ID per impedire attacchi di replica. Per ulteriori informazioni, consulta la seguente tabella:

Tipo	Obbligatorio	Esempio
string	Facoltativo	data-nonce="biaqbm70g23"

La lunghezza dei valori nonce è limitata alla dimensione massima JWT supportata dal tuo ambiente e ai limiti delle dimensioni HTTP dei singoli browser e server.

contesto-dati

Questo attributo modifica il testo del titolo e dei messaggi mostrati nella richiesta di One Tap. Per ulteriori informazioni, consulta la seguente tabella:

Tipo	Obbligatorio	Esempio
string	Facoltativo	data-context="use"

La tabella riportata di seguito elenca i contesti disponibili e le relative descrizioni:

Context
signin	"Accedi con Google"
signup	"Registrati con Google"
use	"Usa con Google"

data-moment_callback

Questo attributo è il nome della funzione dell'elenco di notifiche dello stato dell'interfaccia utente del prompt. Per ulteriori informazioni, consulta il tipo di dati PromptMomentNotification. Per ulteriori informazioni, consulta la seguente tabella:

Tipo	Obbligatorio	Esempio
string	Facoltativo	data-moment_callback="logMomentNotification"

Le funzioni JavaScript all'interno di uno spazio dei nomi non sono supportate dall'API HTML. Utilizza invece una funzione JavaScript globale senza uno spazio dei nomi. Ad esempio, utilizza mylibCallback invece di mylib.callback.

data-state_cookie_domain

Se devi visualizzare One Tap in un dominio principale e nei relativi sottodomini, passa il dominio principale a questo attributo in modo che venga utilizzato un singolo cookie di stato condiviso. Per ulteriori informazioni, consulta la seguente tabella:

Tipo	Obbligatorio	Esempio
string	Facoltativo	data-state_cookie_domain="example.com"

data-ux_mode

Questo attributo imposta il flusso UX utilizzato dal pulsante Accedi con Google. Il valore predefinito è popup. Questo attributo non influisce sull'esperienza utente con un tocco. Per ulteriori informazioni, consulta la tabella seguente:

Tipo	Obbligatorio	Esempio
string	Facoltativo	data-ux_mode="redirect"

La seguente tabella elenca le modalità UX disponibili e le relative descrizioni.

Modalità UX
popup	Esegue il flusso UX di accesso in una finestra popup.
redirect	Esegue il flusso UX di accesso con un reindirizzamento a pagina intera.

data-allowed_parent_origin

Le origini autorizzate a incorporare l'iframe intermedio. Se è presente questo attributo, verrà eseguito One Tap in modalità iframe intermedia. Per ulteriori informazioni, consulta la tabella seguente:

Tipo	Obbligatorio	Esempio
stringa o array di stringhe	Facoltativo	data-allowed_parent_origin="https://example.com"

La seguente tabella elenca i tipi di valori supportati e le relative descrizioni.

Tipi di valore
string	Un unico URI di dominio.	"https://example.com"
string array	Un elenco di URI di dominio separati da virgole.	"https://news.example.com,https://local.example.com"

Se il valore dell'attributo data-allowed_parent_origin non è valido, l'inizializzazione di One Tap della modalità iframe intermedio non riesce e si interrompe.

Sono supportati anche i prefissi con caratteri jolly. Ad esempio, "https://*.example.com" corrisponderà a example.com e ai suoi sottodomini a tutti i livelli (ad esempio news.example.com, login.news.example.com). Tieni presente che:

• Le stringhe di pattern non possono essere composte solo da un carattere jolly e da un dominio di primo livello. Ad esempio, https://*.com e https://*.co.uk non sono validi. Come indicato sopra, "https://*.example.com" corrisponderà a example.com e ai relativi sottodomini. Puoi utilizzare anche un elenco separato da virgole per rappresentare due domini diversi. Ad esempio, "https://example1.com,https://*.example2.com" corrisponderà ai domini example1.com, example2.com e ai sottodomini di example2.com
• I domini con caratteri jolly devono iniziare con uno schema https:// sicuro. "*.example.com" verrà considerato non valido.

data-intermediate_iframe_close_callback

Sostituisce il comportamento predefinito dell'iframe intermedio quando gli utenti chiudono manualmente One Tap toccando il pulsante 'X' nell'interfaccia utente di One Tap. Il comportamento predefinito prevede la rimozione immediata dell'iframe intermedio dal DOM.

Il campo data-intermediate_iframe_close_callback ha effetto solo in modalità iframe intermedio. Ha un impatto solo sull'iframe intermedio, anziché sull'iframe One Tap. La UI di One Tap viene rimossa prima che venga richiamato il callback.

Tipo	Obbligatorio	Esempio
funzione	Facoltativo	data-intermediate_iframe_close_callback="logBeforeClose"

Le funzioni JavaScript all'interno di uno spazio dei nomi non sono supportate dall'API HTML. Utilizza invece una funzione JavaScript globale senza uno spazio dei nomi. Ad esempio, utilizza mylibCallback invece di mylib.callback.

data-itp_support

Questo campo determina se l'upgrade dell'esperienza utente di One Tap deve essere abilitato sui browser che supportano la prevenzione del tracciamento intelligente (ITP). Il valore predefinito è false. Per ulteriori informazioni, consulta la seguente tabella:

Tipo	Obbligatorio	Esempio
boolean	Facoltativo	data-itp_support="true"

Elemento con classe "g_id_signin"

Se aggiungi g_id_signin a un attributo class di un elemento, l'elemento viene visualizzato come pulsante Accedi con Google.

Nella stessa pagina puoi visualizzare più pulsanti Accedi con Google. Ogni pulsante può avere le proprie impostazioni visive. Le impostazioni sono definite dai seguenti attributi dei dati.

Attributi dei dati visivi

La seguente tabella elenca gli attributi dei dati visivi e le relative descrizioni:

Attributo
data-type	Il tipo di pulsante: icona o pulsante standard.
data-theme	Il tema del pulsante. ad esempio, riempimento_blu o riempimento_nero.
data-size	Le dimensioni del pulsante. ad esempio, Small o Large.
data-text	Il testo del pulsante. Ad esempio, "Accedi con Google" o "Registrati con Google".
data-shape	La forma del pulsante. ad esempio rettangolare o circolare.
data-logo_alignment	Allineamento del logo di Google: a sinistra o al centro.
data-width	La larghezza del pulsante, in pixel.
data-locale	Il testo del pulsante viene visualizzato nella lingua impostata in questo attributo.

Tipi di attributi

Le seguenti sezioni contengono i dettagli di ciascun attributo e un esempio.

tipo di dati

Il tipo di pulsante. Il valore predefinito è standard. Per informazioni aggiuntive, consulta la tabella seguente:

Tipo	Obbligatorio	Esempio
string	Sì	data-type="icon"

La seguente tabella elenca i tipi di pulsanti disponibili e le relative descrizioni:

Tipo
standard	Un pulsante con testo o informazioni personalizzate:
icon	Pulsante con icona senza testo:

tema dei dati

Il tema del pulsante. Il valore predefinito è outline. Per informazioni aggiuntive, consulta la tabella seguente:

Tipo	Obbligatorio	Esempio
string	Facoltativo	data-theme="filled_blue"

La seguente tabella elenca i temi disponibili e le relative descrizioni:

Tema
outline	Il tema del pulsante standard:
filled_blue	Il tema del pulsante blu:
filled_black	Il tema del pulsante nero:

dimensione-dati

Le dimensioni del pulsante. Il valore predefinito è large. Per informazioni aggiuntive, consulta la tabella seguente:

Tipo	Obbligatorio	Esempio
string	Facoltativo	data-size="small"

La seguente tabella elenca le dimensioni dei pulsanti disponibili e le relative descrizioni.

Dimensioni
large	Un pulsante grande:
medium	Un pulsante di medie dimensioni:
small	Un piccolo pulsante:

testo-dati

Il testo del pulsante. Il valore predefinito è signin_with. Non ci sono differenze visive per il testo dei pulsanti delle icone con attributi data-text diversi. L'unica eccezione riguarda il momento in cui il testo viene letto per l'accessibilità dello schermo.

Per ulteriori informazioni, consulta la seguente tabella:

Tipo	Obbligatorio	Esempio
string	Facoltativo	data-text="signup_with"

Nella tabella seguente sono elencati i testi dei pulsanti disponibili e le relative descrizioni:

Testo
signin_with	Il testo del pulsante è "Accedi con Google":
signup_with	Il testo del pulsante è "Registrati con Google":
continue_with	Il testo del pulsante è "Continua con Google":
signin	Il testo del pulsante è "Accedi":

data-shape

La forma del pulsante. Il valore predefinito è rectangular. Per ulteriori informazioni, consulta la tabella seguente:

Tipo	Obbligatorio	Esempio
string	Facoltativo	data-shape="rectangular"

La seguente tabella elenca le forme di pulsanti disponibili e le relative descrizioni:

Shape
rectangular	Il pulsante rettangolare. Se utilizzato per il tipo di pulsante icon, significa che è uguale a square.
pill	Il pulsante a forma di pillola. Se utilizzato per il tipo di pulsante icon, è uguale a circle.
circle	Il pulsante a forma di cerchio. Se utilizzato per il tipo di pulsante standard, equivale a pill.
square	Il pulsante quadrato. Se utilizzato per il tipo di pulsante standard, equivale a rectangular.

data-logo_alignment

L'allineamento del logo Google. Il valore predefinito è left. Questo attributo si applica solo al tipo di pulsante standard. Per ulteriori informazioni, consulta la tabella seguente:

Tipo	Obbligatorio	Esempio
string	Facoltativo	data-logo_alignment="center"

La seguente tabella elenca gli allineamenti disponibili e le relative descrizioni:

allineamento_logo
left	Allinea a sinistra il logo di Google:
center	Allinea al centro il logo di Google:

larghezza-dati

La larghezza minima del pulsante, in pixel. La larghezza massima disponibile è 400 pixel.

Per ulteriori informazioni, consulta la seguente tabella:

Tipo	Obbligatorio	Esempio
string	Facoltativo	data-width=400

data-locale

Impostazioni internazionali preimpostate del testo del pulsante. Se non è impostato, vengono usate le impostazioni internazionali predefinite del browser o la preferenza dell'utente della sessione Google. Pertanto, utenti diversi potrebbero visualizzare versioni diverse dei pulsanti localizzati e possibilmente con dimensioni diverse.

Per ulteriori informazioni, consulta la seguente tabella:

Tipo	Obbligatorio	Esempio
string	Facoltativo	data-locale="zh_CN"

Integrazione lato server

Gli endpoint lato server devono gestire le seguenti richieste POST HTTP.

L'endpoint del gestore di token ID

L'endpoint del gestore di token ID elabora il token ID. A seconda dello stato dell'account corrispondente, puoi eseguire l'accesso dell'utente e indirizzarlo a una pagina di registrazione oppure a una pagina di collegamento dell'account per ulteriori informazioni.

La richiesta HTTP POST contiene le seguenti informazioni:

Formato	Nome	Description
Cookie	g_csrf_token	Una stringa casuale che cambia con ogni richiesta all'endpoint del gestore.
Parametro di richiesta	g_csrf_token	Una stringa uguale al valore del cookie precedente, g_csrf_token.
Parametro di richiesta	credential	Il token ID emesso da Google.
Parametro di richiesta	select_by	Come vengono selezionate le credenziali.

Quando è decodificato, il token ID si presenta come nel seguente esempio:

header
{
  "alg": "RS256",
  "kid": "f05415b13acb9590f70df862765c655f5a7a019e", // JWT signature
  "typ": "JWT"
}
payload
{
  "iss": "https://accounts.google.com", // The JWT's issuer
  "nbf":  161803398874,
  "aud": "314159265-pi.apps.googleusercontent.com", // Your server's client ID
  "sub": "3141592653589793238", // The unique ID of the user's Google Account
  "hd": "gmail.com", // If present, the host domain of the user's GSuite email address
  "email": "[e-mail]", // The user's email address
  "email_verified": true, // true, if Google has verified the email address
  "azp": "314159265-pi.apps.googleusercontent.com",
  "name": "Elisa Beckett",
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/e2718281828459045235360uler",
  "given_name": "Eliza",
  "family_name": "Beckett",
  "iat": 1596474000, // Unix timestamp of the assertion's creation time
  "exp": 1596477600, // Unix timestamp of the assertion's expiration time
  "jti": "abc161803398874def"
}

Nella tabella seguente sono elencati i valori possibili per il campo select_by. Il tipo di pulsante utilizzato, insieme alla sessione e allo stato del consenso, viene utilizzato per impostare il valore,

• L'utente ha premuto il pulsante One Tap o Accedi con Google oppure ha utilizzato la procedura di accesso automatico touchless.

• È stata trovata una sessione esistente oppure l'utente ha selezionato e eseguito l'accesso a un Account Google per crearne una nuova.

• Prima di condividere le credenziali del token ID con l'app è necessario

  • aver premuto il pulsante Conferma per concedere il consenso alla condivisione delle credenziali; oppure
  • In precedenza ha concesso il consenso e utilizzato Seleziona un account per scegliere un Account Google.

Il valore di questo campo è impostato su uno di questi tipi:

Valore	Description
auto	Accesso automatico di un utente con una sessione esistente che in precedenza ha concesso il consenso per condividere le credenziali.
user	Un utente con una sessione esistente che aveva precedentemente concesso il consenso ha premuto il pulsante One Tap ' Continue as' per condividere le credenziali.
user_1tap	Un utente con una sessione esistente ha premuto il pulsante One Tap 'Continue as' per concedere il consenso e condividere le credenziali. Si applica solo a Chrome v75 e versioni successive.
user_2tap	Un utente senza una sessione esistente ha premuto il pulsante One Tap 'Continua come' per selezionare un account, quindi ha premuto il pulsante Conferma in una finestra popup per concedere il consenso e condividere le credenziali. Applicabile ai browser non basati su Chromium.
btn	Un utente con una sessione esistente che in precedenza ha concesso il consenso ha premuto il pulsante Accedi con Google e selezionato un Account Google da 'Scegliere un account' per condividere le credenziali.
btn_confirm	Un utente con una sessione esistente ha premuto il pulsante Accedi con Google e ha premuto il pulsante Conferma per concedere il consenso e condividere le credenziali.
btn_add_session	Un utente senza una sessione esistente che in precedenza ha concesso il consenso ha premuto il pulsante Accedi con Google per selezionare un Account Google e condividere le credenziali.
btn_confirm_add_session	Un utente senza una sessione esistente ha prima premuto il pulsante Accedi con Google per selezionare un Account Google, quindi ha premuto il pulsante Conferma per acconsentire e condividere le credenziali.

Endpoint del gestore credenziali delle password

L'endpoint del gestore di credenziali della password elabora le credenziali delle password recuperate dal gestore di credenziali nativo.

La richiesta HTTP POST contiene le seguenti informazioni:

Formato	Nome	Description
Cookie	g_csrf_token	Una stringa casuale che cambia con ogni richiesta all'endpoint del gestore.
Parametro di richiesta	g_csrf_token	Una stringa uguale al valore del cookie precedente, g_csrf_token.
Parametro di richiesta	email	Il token ID emesso da Google.
Parametro di richiesta	password	Come vengono selezionate le credenziali.

Nota: puoi modificare i nomi dei parametri email e password con gli attributi dei dati.