Riferimento API JavaScript di Sign in with Google

Questa pagina di riferimento descrive l'API JavaScript Accedi con Google, utilizzata per visualizzare il pulsante Accedi con Google o il prompt One Tap sulle pagine web.

Metodo: google.accounts.id.initialize

Il metodo google.accounts.id.initialize inizializza il client Accedi con Google in base all'oggetto di configurazione. Vedi il seguente esempio di codice del metodo:

google.accounts.id.initialize(IdConfiguration)

Il seguente esempio di codice implementa il metodo google.accounts.id.initialize con una funzione onload:

<script>
  window.onload = function () {
    google.accounts.id.initialize({
      client_id: 'YOUR_GOOGLE_CLIENT_ID',
      callback: handleCredentialResponse
    });
    google.accounts.id.prompt();
  };
</script>

Il metodo google.accounts.id.initialize crea un'istanza client di Accedi con Google che può essere utilizzata implicitamente da tutti i moduli nella stessa pagina web.

• Devi chiamare il metodo google.accounts.id.initialize una sola volta anche se utilizzi più moduli (come One Tap, pulsante personalizzato, revoca, ecc.) nella stessa pagina web.
• Se chiami il metodo google.accounts.id.initialize più volte, vengono ricordate e utilizzate solo le configurazioni dell'ultima chiamata.

In realtà, reimposti le configurazioni ogni volta che chiami il metodo google.accounts.id.initialize e tutti i metodi successivi nella stessa pagina web utilizzano immediatamente le nuove configurazioni.

Tipo di dati: IdConfiguration

La tabella seguente elenca i campi e le descrizioni del tipo di dati IdConfiguration:

client_id

Questo campo è l'ID client della tua applicazione, che viene trovato e creato nella console Google Cloud. Per ulteriori informazioni, consulta la tabella seguente:

color_scheme

Questo campo è la combinazione di colori applicata al prompt One Tap. Per ulteriori informazioni, consulta la tabella seguente:

La tabella seguente elenca le combinazioni di colori disponibili e le relative descrizioni.

auto_select

Questo campo determina se un token ID viene restituito automaticamente senza alcuna interazione dell'utente quando è presente una sola sessione Google che ha approvato la tua app in precedenza. Il valore predefinito è false. Per ulteriori informazioni, consulta la tabella seguente:

callback

Questo campo è la funzione JavaScript che gestisce il token ID restituito dal prompt One Tap o dalla finestra popup. Questo attributo è obbligatorio se viene utilizzata la modalità UX di Google One Tap o del pulsante Accedi con Google popup. Per ulteriori informazioni, consulta la tabella seguente:

login_uri

Questo attributo è l'URI dell'endpoint di accesso.

Il valore deve corrispondere esattamente a uno degli URI di reindirizzamento autorizzati per il client OAuth 2.0, che hai configurato in Google Cloud Console e deve essere conforme alle nostre regole di convalida dell'URI di reindirizzamento.

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

La risposta delle credenziali del token ID viene pubblicata nell'endpoint di accesso quando un utente fa clic sul pulsante Accedi con Google e viene utilizzata la modalità UX di reindirizzamento.

Per ulteriori informazioni, consulta la tabella seguente:

Il tuo endpoint di accesso deve gestire le richieste POST contenenti un parametro credential con un valore del token ID nel corpo.

native_callback

Questo campo è il nome della funzione JavaScript che gestisce la credenziale password restituita dal gestore delle credenziali integrato del browser. Per ulteriori informazioni, consulta la tabella seguente:

cancel_on_tap_outside

Questo campo indica se annullare o meno la richiesta One Tap se un utente fa clic al di fuori del prompt. Il valore predefinito è true. Puoi disabilitarlo se imposti il valore su false. Per ulteriori informazioni, consulta la tabella seguente:

prompt_parent_id

Questo attributo imposta l'ID DOM dell'elemento contenitore. Se non è impostato, il prompt One Tap viene visualizzato nell'angolo in alto a destra della finestra. Per ulteriori informazioni, consulta la tabella seguente:

nonce

Questo campo è una stringa casuale utilizzata dal token ID per impedire 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 vincoli di dimensione HTTP di singoli browser e server.

essential_claims

Questo campo è una stringa utilizzata per richiedere l'inclusione di rivendicazioni aggiuntive nel token ID restituito da Google. Per un elenco completo delle rivendicazioni accettate da Google, consulta Rivendicazioni supportate.

Per ulteriori informazioni, consulta la tabella seguente:

context

Questo campo modifica il testo del titolo e dei messaggi visualizzati nel prompt One Tap, senza alcun effetto per i browser ITP. Il valore predefinito è signin.

Per ulteriori informazioni, consulta la tabella seguente:

La tabella seguente elenca tutti i contesti disponibili e le relative descrizioni:

state_cookie_domain

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

ux_mode

Utilizza questo campo per impostare il flusso dell'esperienza utente utilizzato dal pulsante Accedi con Google. Il valore predefinito è popup. Questo attributo non ha alcun impatto sull'esperienza utente One Tap. Per ulteriori informazioni, consulta la tabella seguente:

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

allowed_parent_origin

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

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

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 presente 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 perché "https://.example.com" corrisponde a example.com e a tutti i relativi sottodomini. Utilizza 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, quindi "*.example.com" è considerato non valido.

Se il valore del campo allowed_parent_origin non è valido, l'inizializzazione di One Tap della modalità iframe intermedia non andrà a buon fine e si interromperà.

intermediate_iframe_close_callback

Esegue l'override del 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 intermediate_iframe_close_callback ha effetto solo nella modalità iframe intermedio e influisce solo sull'iframe intermedio, anziché sull'iframe One Tap. L'interfaccia utente One Tap viene rimossa prima dell'invocazione del callback.

itp_support

Questo campo determina se l' esperienza utente One Tap aggiornata deve essere attivata sui browser che supportano Intelligent Tracking Prevention (ITP). Il valore predefinito è false. Per ulteriori informazioni, consulta la tabella seguente:

login_hint

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

Per maggiori informazioni, consulta il campo login_hint nella documentazione di OpenID Connect.

hd

Quando un utente ha più account e deve accedere solo con il proprio account Workspace, utilizza questo parametro per fornire un suggerimento sul nome di dominio a Google. 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 il campo hd nella documentazione di OpenID Connect.

use_fedcm_for_prompt

Consenti al browser di controllare i prompt di accesso degli utenti e di mediare il flusso di accesso tra il tuo sito web e Google. Il valore predefinito è false. Per saperne di più, consulta la pagina Eseguire la migrazione a FedCM.

use_fedcm_for_button

Questo campo determina se l'esperienza utente del pulsante FedCM deve essere utilizzata su Chrome (M125+ per computer e M128+ per Android). Il valore predefinito è false. Per ulteriori informazioni, consulta la tabella seguente:

button_auto_select

Questo campo determina se attivare l'opzione Selezione automatica per il flusso del pulsante FedCM. Se attivata, gli utenti di ritorno con una sessione Google attiva accederanno automaticamente, ignorando la richiesta di selezione dell'account. Il valore predefinito è false. Devi attivare esplicitamente l'accesso automatico con pulsante durante l'avvio dell'attivazione. Per ulteriori informazioni, consulta la tabella seguente:

Metodo: google.accounts.id.prompt

Il metodo google.accounts.id.prompt mostra la richiesta One Tap o il gestore delle credenziali integrato nel browser dopo l'invocazione del metodo initialize(). Vedi il seguente esempio di codice del metodo:

 google.accounts.id.prompt(/**
 @type{(function(!PromptMomentNotification):void)=} */ momentListener)

Normalmente, il metodo prompt() viene chiamato al caricamento della pagina. A causa dello stato della sessione e delle impostazioni utente sul lato Google, l'interfaccia utente del prompt One Tap potrebbe non essere visualizzata. Per ricevere notifiche sullo stato dell'interfaccia utente in momenti diversi, passa una funzione per ricevere notifiche sullo stato dell'interfaccia utente.

Le notifiche vengono inviate nei seguenti momenti:

• Momento di visualizzazione:si verifica dopo la chiamata al metodo prompt(). La notifica contiene un valore booleano che indica se l'interfaccia utente viene visualizzata o meno.

• Momento ignorato:si verifica quando il prompt One Tap viene chiuso da un annullamento automatico, un annullamento manuale o quando Google non riesce a emettere una credenziale, ad esempio quando la sessione selezionata ha eseguito la disconnessione da Google.

  In questi casi, ti consigliamo di passare ai provider di identità successivi, se presenti.

• Momento ignorato:si verifica quando Google recupera correttamente una credenziale o un utente vuole interrompere il flusso di recupero delle credenziali. Ad esempio, quando l'utente inizia a inserire il nome utente e la password nella finestra di dialogo di accesso, puoi chiamare il metodo google.accounts.id.cancel() per chiudere la richiesta One Tap e attivare un momento di chiusura.

Il seguente esempio di codice implementa il momento saltato:

<script>
  window.onload = function () {
    google.accounts.id.initialize(...);
    google.accounts.id.prompt((notification) => {
      if (notification.isNotDisplayed() || notification.isSkippedMoment()) {
        // continue with another identity provider.
      }
    });
  };
</script>

Tipo di dati: PromptMomentNotification

La tabella seguente elenca i metodi e le descrizioni del tipo di dati PromptMomentNotification:

Tipo di dati: CredentialResponse

Quando viene richiamata la funzione callback, viene passato come parametro un oggetto CredentialResponse. La tabella seguente elenca i campi contenuti nell'oggetto di risposta delle credenziali:

credenziale

Questo campo è il token ID come stringa di token web JSON (JWT) con codifica base64.

Quando viene decodificato, il JWT è simile al 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 Google Workspace email address
  "auth_time": 1748875426,
  "amr": ["mfa", "pwd", "tel"],
  "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": "Elisa",
  "family_name": "Beckett",
  "iat": 1596474000, // Unix timestamp of the assertion creation time
  "exp": 1596477600, // Unix timestamp of the assertion expiration time
  "jti": "abc161803398874def"
}

Il campo sub è un identificatore univoco globale per l'Account Google. Utilizza il campo sub come identificatore dell'utente, in quanto è univoco tra tutti gli Account Google e non viene mai riutilizzato.

Utilizzando i campi email, email_verified e hd puoi determinare se Google ospita ed è autorevole per un indirizzo email. Nei casi in cui Google è 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 un Account Google senza utilizzare Gmail o Google Workspace. Quando email non contiene un suffisso @gmail.com e hd è assente, Google non è autorevole e per verificare l'utente sono consigliati la password o altri metodi di verifica. email_verfied può anche essere vero, in quanto 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.

Il campo exp mostra la 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 ha eseguito la disconnessione. La tua app è responsabile della gestione delle sessioni dei tuoi utenti.

select_by

La tabella seguente elenca i valori possibili per il campo select_by. Il tipo di pulsante utilizzato insieme allo stato della sessione e dello 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 senza contatto.

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

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

  • ha premuto il pulsante Conferma per dare 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 campo viene definito solo quando l'utente fa clic su un pulsante Accedi con Google per accedere e viene specificato l'attributo state del pulsante su cui è stato fatto clic. Il valore di questo campo è lo stesso specificato nell'attributo state del pulsante.

Poiché è possibile eseguire il rendering di più pulsanti Accedi con Google sulla stessa pagina, puoi assegnare a ogni pulsante una stringa univoca. Pertanto, puoi utilizzare questo campo state per identificare il pulsante su cui l'utente ha fatto clic per accedere.

Metodo: google.accounts.id.renderButton

Il metodo google.accounts.id.renderButton esegue il rendering di un pulsante Accedi con Google nelle tue pagine web.

Vedi il seguente esempio di codice del metodo:

google.accounts.id.renderButton(
      /** @type{!HTMLElement} */ parent,
      /** @type{!GsiButtonConfiguration} */ options
    )

Tipo di dati: GsiButtonConfiguration

La tabella seguente elenca i campi e le descrizioni del tipo di dati GsiButtonConfiguration:

Tipi di attributo

Le sezioni seguenti contengono dettagli su ciascun tipo di attributo ed un esempio.

tipo

Il tipo di pulsante. Il valore predefinito è standard.

Per ulteriori informazioni, consulta la tabella seguente:

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

Tipo
standard
icon

tema

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

dimensioni

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

testo

Il testo del pulsante. Il valore predefinito è signin_with. Non ci sono differenze visive per il testo dei pulsanti con icone che hanno attributi 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 tutti i testi dei pulsanti disponibili e le relative descrizioni:

Testo
signin_with
signup_with
continue_with
signin

forma

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:

Forma
rectangular
pill
circle
square

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

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

Per ulteriori informazioni, consulta la tabella seguente:

lingua

Facoltativo. Visualizza il testo del pulsante utilizzando le impostazioni internazionali specificate, altrimenti utilizza per impostazione predefinita le impostazioni dell'Account Google o del browser degli utenti. Aggiungi il parametro hl e il codice lingua alla direttiva src durante il caricamento della libreria, ad esempio: gsi/client?hl=<iso-639-code>.

Se non è impostata, viene utilizzata la lingua predefinita del browser o la preferenza dell'utente della sessione Google. Pertanto, utenti diversi potrebbero visualizzare versioni diverse dei pulsanti localizzati, possibilmente con dimensioni diverse.

Per ulteriori informazioni, consulta la tabella seguente:

click_listener

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

  google.accounts.id.renderButton(document.getElementById("signinDiv"), {
      theme: 'outline',
      size: 'large',
      click_listener: onClickHandler
    });

  
  function onClickHandler(){
    console.log("Sign in with Google button clicked...")
  }
  

In questo esempio, il messaggio Sign in with Google button clicked... viene registrato nella console quando viene fatto clic sul pulsante Accedi con Google.

stato

Facoltativo: poiché è possibile eseguire il rendering di più pulsanti Accedi con Google nella stessa pagina, puoi assegnare a ogni pulsante una stringa univoca. La stessa stringa verrà 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:

Tipo di dati: credenziali

Quando viene richiamata la funzione native_callback, viene passato un oggetto Credential come parametro. La tabella seguente elenca i campi contenuti nell'oggetto:

Metodo: google.accounts.id.disableAutoSelect

Quando l'utente esce dal tuo sito web, devi chiamare il metodo google.accounts.id.disableAutoSelect per registrare lo stato nei cookie. Ciò impedisce un loop senza fine dell'esperienza utente. Vedi il seguente snippet di codice del metodo:

google.accounts.id.disableAutoSelect()

Il seguente esempio di codice implementa il metodo google.accounts.id.disableAutoSelect con una funzione onSignout():

<script>
  function onSignout() {
    google.accounts.id.disableAutoSelect();
  }
</script>

Metodo: google.accounts.id.storeCredential

Questo metodo è un wrapper per il metodo store() dell'API di gestione delle credenziali integrata del browser. Pertanto, può essere utilizzato solo per memorizzare una credenziale password. Vedi il seguente esempio di codice del metodo:

google.accounts.id.storeCredential(Credential, callback)

Il seguente esempio di codice implementa il metodo google.accounts.id.storeCredential con una funzione onSignIn():

<script>
  function onSignIn() {
    let cred = {id: '...', password: '...'};
    google.accounts.id.storeCredential(cred);
  }
</script>

Metodo: google.accounts.id.cancel

Puoi annullare il flusso One Tap se rimuovi il prompt dal DOM della relying party. L'operazione di annullamento viene ignorata se è già selezionata una credenziale. Vedi il seguente esempio di codice del metodo:

google.accounts.id.cancel()

Il seguente esempio di codice implementa il metodo google.accounts.id.cancel() con una funzione onNextButtonClicked():

<script>
  function onNextButtonClicked() {
    google.accounts.id.cancel();
    showPasswordPage();
  }
</script>

Callback di caricamento della libreria: onGoogleLibraryLoad

Puoi registrare un richiamo per onGoogleLibraryLoad. Viene notificata dopo il caricamento della libreria JavaScript di Accedi con Google:

window.onGoogleLibraryLoad = () => {
    ...
};

Questo callback è solo una scorciatoia per il callback window.onload. Non ci sono differenze nel comportamento.

Il seguente esempio di codice implementa un callback onGoogleLibraryLoad:

<script>
  window.onGoogleLibraryLoad = () => {
   google.accounts.id.initialize({
     ...
   });
   google.accounts.id.prompt();
  };
</script>

Metodo: google.accounts.id.revoke

Il metodo google.accounts.id.revoke revoca l'autorizzazione con OAuth utilizzata per condividere il token ID per l'utente specificato. Vedi il seguente snippet di codice del metodo: javascript google.accounts.id.revoke(login_hint, callback)

Il seguente esempio di codice mostra come utilizzare il metodo revoke con un ID.

  google.accounts.id.revoke('1618033988749895', done => {
    console.log(done.error);
  });

Tipo di dati: RevocationResponse

Quando viene richiamata la funzione callback, viene passato come parametro un oggetto RevocationResponse. La tabella seguente elenca i campi contenuti nell'oggetto risposta di revoca:

riuscito

Questo campo è un valore booleano impostato su true se la chiamata al metodo di revoca è riuscita o su false in caso di errore.

errore

Questo campo è un valore stringa e contiene un messaggio di errore dettagliato se la chiamata al metodo revoke non è andata a buon fine. In caso di esito positivo, non è definito.