Riferimento all'API HTML Accedi con Google

Questa pagina di riferimento descrive l'API degli attributi di dati HTML di Accedi con Google. Puoi utilizzare l'API per visualizzare la richiesta One Tap o il pulsante Accedi con Google nelle tue pagine web.

Elemento con ID "g_id_onload"

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

Attributi dei dati

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

Tipi di attributi

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

data-client_id

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

prompt_dati_auto

Questo attributo determina se mostrare o meno One tap. Il valore predefinito è true. Il tocco di Google One non viene visualizzato quando questo valore è false. Per ulteriori informazioni, consulta la tabella riportata di seguito:

data-auto_select

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

data-login_uri

Questo attributo è l'URI del tuo endpoint di accesso.

Il valore deve corrispondere esattamente a uno degli URI di reindirizzamento autorizzati per il client OAuth 2.0 che hai configurato nella Console API e deve essere conforme alle nostre regole di convalida degli URI di reindirizzamento.

Questo attributo può essere omesso se la pagina corrente è la tua pagina di accesso, nel qual caso la credenziale viene pubblicata in questa pagina per impostazione predefinita.

La risposta della credenziale 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 eseguito l'accesso automatico.

Per ulteriori informazioni, consulta la tabella seguente:

L'endpoint di accesso deve gestire le richieste POST contenenti 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

data-callback

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

Potrebbe essere utilizzato uno degli attributi data-login_uri e data-callback. Dipende dalle seguenti configurazioni del componente e della modalità UX:

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

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

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

data-native_login_uri

Questo attributo è l'URL dell'endpoint del gestore delle credenziali delle password. Se imposti l'attributo data-native_login_uri o l'attributo data-native_callback, la libreria JavaScript utilizza di nuovo il gestore delle credenziali nativo in assenza di una sessione Google. Non puoi impostare entrambi gli attributi data-native_callback e data-native_login_uri. Per ulteriori informazioni, consulta la tabella seguente:

data-native_callback

Questo attributo è il nome della funzione JavaScript che gestisce la credenziale della password restituita dal gestore delle credenziali nativo del browser. Se imposti l'attributo data-native_login_uri o l'attributo data-native_callback, la libreria JavaScript ricorre al gestore delle credenziali nativo quando non è presente una sessione Google. Non puoi impostare sia data-native_callback che data-native_login_uri. Per ulteriori informazioni, consulta la tabella seguente:

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

data-native_id_param

Quando invii la credenziale 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 tabella seguente:

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 riportata di seguito:

data-cancel_on_tap_outside

Questo attributo imposta 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 saperne di più, consulta la tabella seguente:

data-prompt_parent_id

Questo attributo imposta l'ID DOM dell'elemento contenitore. Se non è impostata, la richiesta di un solo tocco viene visualizzata nell'angolo in alto a destra della finestra. Per ulteriori informazioni, consulta la tabella riportata di seguito:

data-skip_prompt_cookie

Questo attributo ignora One Tap se il valore del cookie specificato non è vuoto. Per ulteriori informazioni, consulta la tabella riportata di seguito:

data-nonce

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

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

data-context

Questo attributo modifica il testo del titolo e dei messaggi visualizzati nel prompt One Tap. Per saperne di più, consulta la tabella seguente:

Nella tabella seguente sono elencati tutti i contesti disponibili e le relative descrizioni:

callback_data-moment

Questo attributo è il nome della funzione dell'ascoltatore della notifica dello stato dell'interfaccia utente della richiesta. Per saperne di più, consulta il tipo di dati PromptMomentNotification.

Per saperne di più, consulta la tabella seguente:

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

data-state_cookie_domain

Se devi mostrare One Tap in un dominio principale e nei relativi sottodomini, passa il dominio principale a questo attributo in modo da utilizzare un unico cookie con stato condiviso. Per ulteriori informazioni, consulta la tabella seguente:

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 One Tap. Per ulteriori informazioni, consulta la tabella riportata di seguito:

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

data-allowed_parent_origin

Le origini che possono incorporare l'iframe intermedio. One Tap viene eseguito in modalità iframe intermedia se è presente questo attributo. Per ulteriori informazioni, consulta la tabella riportata di seguito:

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

Se il valore dell'attributo data-allowed_parent_origin non è valido, l'inizializzazione One Tap della modalità iframe intermedia non andrà a buon fine e verrà interrotta.

Sono supportati anche i prefissi con caratteri jolly. Ad esempio, "https://*.example.com" corrisponde a example.com e ai relativi sottodomini a tutti i livelli (ad es.news.example.com, login.news.example.com). Aspetti da tenere presenti quando utilizzi i caratteri jolly:

• 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" corrisponde a example.com e ai suoi sottodomini. Puoi anche utilizzare un elenco separato da virgole per rappresentare due domini diversi. Ad esempio, "https://example1.com,https://*.example2.com" corrisponde ai domini example1.com, example2.com e ai sottodomini di example2.com
• I domini jolly devono iniziare con uno schema https:// sicuro, pertanto "*.example.com" è 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 viene applicato solo in modalità iframe intermedia. e incide solo sull'iframe intermedio, anziché all'iframe One Tap. L'UI di One Tap viene rimossa prima dell'attivazione del callback.

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

assistenza_data-itp

Questo campo determina se l' UX One Tap di cui è stato eseguito l'upgrade deve essere attivato sui browser che supportano la Prevenzione antitracciamento intelligente (ITP). Il valore predefinito è false. Per ulteriori informazioni, consulta la tabella riportata di seguito:

data-login_hint

Se la tua applicazione sa in anticipo quale utente deve aver eseguito l'accesso, può fornire un suggerimento per l'accesso a Google. In caso di esito positivo, la selezione dell'account viene saltata. I valori accettati sono: un indirizzo email o un campo sub di token ID.

Per saperne di più, consulta la documentazione di OpenID Connect per login_hint.

data-hd

Quando un utente ha più account e deve accedere solo con il suo account Workspace, utilizza questa opzione per fornire a Google un suggerimento per il nome di dominio. In caso di esito positivo, gli account utente visualizzati durante la selezione dell'account sono limitati al dominio fornito. Un valore jolly: * offre all'utente solo account Workspace ed esclude gli account consumer (user@gmail.com) durante la selezione dell'account.

Per saperne di più, consulta la documentazione di OpenID Connect per hd.

data-use_fedcm_for_prompt

Consenti al browser di controllare le richieste di accesso dell'utente e mediare il flusso di accesso tra il tuo sito web e Google. Il valore predefinito è false. Per ulteriori informazioni, consulta la pagina Eseguire la migrazione a FedCM.

data-enable_redirect_uri_validation

Attiva il flusso di reindirizzamento dei pulsanti conforme alle regole di convalida degli URI di reindirizzamento.

Elemento con classe "g_id_signin"

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

Puoi visualizzare più pulsanti Accedi con Google nella stessa pagina. Ogni pulsante può avere le proprie impostazioni di visualizzazione. Le impostazioni sono definite dai seguenti attributi dei dati.

Attributi dei dati visivi

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

Tipi di attributi

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

tipo di dati

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

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

Tipo
standard
icon

data-theme

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

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

Tema
outline
filled_blue
filled_black

dimensione-dati

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

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

Dimensioni
large
medium
small

data-text

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

Per ulteriori informazioni, consulta la tabella seguente:

La tabella seguente elenca i testi dei pulsanti disponibili e le relative descrizioni:

Testo
signin_with
signup_with
continue_with
signin

data-shape

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

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

Shape
rectangular
pill
circle
square

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:

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

logo_alignment
left
center

larghezza-dati

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

Per ulteriori informazioni, consulta la tabella seguente:

data-locale

(Facoltativo) Mostra il testo del pulsante utilizzando le impostazioni internazionali specificate, altrimenti viene utilizzato il valore predefinito dell'Account Google o del browser dell'utente. Aggiungi il parametro hl e il codice lingua alla direttiva src quando carichi la libreria, ad esempio: gsi/client?hl=<iso-639-code>.

Se non viene configurato, vengono utilizzate le impostazioni internazionali predefinite del browser o la preferenza dell'utente della sessione Google. Pertanto, utenti diversi potrebbero vedere versioni diverse dei pulsanti localizzati e, eventualmente, con dimensioni diverse.

Per ulteriori informazioni, consulta la tabella seguente:

data-click_listener

Puoi definire una funzione JavaScript da chiamare quando viene fatto clic sul pulsante Accedi con Google utilizzando l'attributo data-click_listener.

  <script>
    function onClickHandler(){
      console.log("Sign in with Google button clicked...")
    }
  </script>
  .....
  <div class="g_id_signin"
      data-size="large"
      data-theme="outline"
      data-click_listener="onClickHandler">
  </div>

In questo esempio, il messaggio È stato fatto clic sul pulsante Accedi con Google… viene registrato nella console quando viene fatto clic sul pulsante Accedi con Google.

stato-dati

Facoltativo: poiché è possibile visualizzare più pulsanti Accedi con Google nella stessa pagina, puoi assegnare a ciascun pulsante una stringa univoca. La stessa stringa viene restituita insieme al token ID, in modo da poter identificare il pulsante su cui l'utente ha fatto clic per accedere.

Per ulteriori informazioni, consulta la tabella seguente:

Integrazione lato server

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

L'endpoint del gestore di token ID

L'endpoint del gestore di token ID elabora il token ID. In base allo stato dell'account corrispondente, puoi eseguire l'accesso dell'utente e indirizzarlo a una pagina di registrazione o a una pagina di collegamento dell'account per ulteriori informazioni.

La richiesta HTTP POST contiene le seguenti informazioni:

qualifica

Dopo la decodifica, il token ID ha il seguente aspetto:

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": "elisa.g.beckett@gmail.com", // 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"
}

Il campo sub è un identificatore univoco a livello globale per l'Account Google. Utilizza solo il campo sub come identificatore per l'utente, in quanto è univoco tra tutti gli Account Google e non viene mai riutilizzato. Non utilizzare l'indirizzo email come identificatore perché un Account Google può avere più indirizzi email in momenti diversi.

Utilizzando i campi email, email_verified e hd, puoi determinare se Google ospita e è autorevole per un indirizzo email. Nei casi in cui Google sia autorevole, viene confermato che l'utente è il proprietario legittimo dell'account.

Casi in cui Google è autorevole:

• email ha un suffisso @gmail.com, si tratta di un account Gmail.
• email_verified è true e hd è impostato, si tratta di un account Google Workspace.

Gli utenti possono registrarsi per gli Account Google senza utilizzare Gmail o Google Workspace. Quando email non contiene un suffisso @gmail.com e hd è assente, Google non è autorevole e ti consigliamo di usare la password o altri metodi di verifica per verificare l'utente. email_verified può essere vero anche perché Google ha inizialmente verificato l'utente al momento della creazione dell'Account Google, ma la proprietà dell'account email di terze parti potrebbe essere cambiata nel frattempo.

Il campo exp mostra la data e l'ora di scadenza per la verifica del token sul lato server. È di un'ora per il token ID ottenuto da Accedi con Google. Devi verificare il token prima della scadenza. Non utilizzare exp per la gestione delle sessioni. Un token ID scaduto non significa che l'utente è disconnesso. La tua app è responsabile della gestione delle sessioni degli utenti.

select_by

La seguente tabella elenca i possibili valori per il campo select_by. Il tipo di pulsante utilizzato insieme allo stato della sessione e del consenso vengono utilizzati per impostare il valore,

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

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

• Prima di condividere le credenziali degli token ID con la tua app, l'utente deve:

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

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

stato

Questo parametro viene definito solo quando l'utente fa clic su un pulsante Accedi con Google per accedere e viene specificato l'attributo data-state del pulsante su cui ha fatto clic. Il valore di questo campo è lo stesso specificato nell'attributo data-state del pulsante.

Poiché è possibile visualizzare più pulsanti Accedi con Google nella stessa pagina, puoi assegnare a ciascun pulsante una stringa univoca. Di conseguenza, puoi utilizzare il parametro state per identificare il pulsante su cui l'utente ha fatto clic per accedere.

Endpoint del gestore delle credenziali della password

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

La richiesta HTTP POST contiene le seguenti informazioni: