Referência da API Sign In with Google para JavaScript

Esta página de referência descreve a API Sign-In JavaScript. Você pode usar essa API para mostrar a solicitação de um toque ou o botão "Fazer login com o Google" nas suas páginas da Web.

Método: google.accounts.id.initialize

O método google.accounts.id.initialize inicializa o cliente do recurso "Fazer login com o Google" com base no objeto de configuração. Confira este exemplo de código do método:

google.accounts.id.initialize(IdConfiguration)

O exemplo de código abaixo implementa o método google.accounts.id.initialize com uma função onload:

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

O método google.accounts.id.initialize cria uma instância de cliente do recurso Fazer login com o Google que pode ser usado implicitamente por todos os módulos na mesma página da Web.

• Você só precisa chamar o método google.accounts.id.initialize uma vez, mesmo se usar vários módulos (como o One Tap, o botão personalizado, a revogação etc.) na mesma página da Web.
• Se você chamar o método google.accounts.id.initialize várias vezes, somente as configurações na última chamada serão lembradas e usadas.

Na verdade, você redefine as configurações sempre que chama o método google.accounts.id.initialize, e todos os métodos subsequentes na mesma página da Web usam as novas configurações imediatamente.

Tipo de dados: IdConfiguration

A tabela a seguir lista os campos e as descrições do tipo de dados IdConfiguration:

client_id

Esse campo é o ID do cliente do seu aplicativo, que é encontrado e criado no console do Google Cloud. Consulte a tabela a seguir para mais informações:

auto_select

Esse campo determina se um token de ID é retornado automaticamente sem nenhuma interação do usuário quando há apenas uma sessão do Google que aprovou seu app antes. O valor padrão é false. Confira mais informações na tabela a seguir:

callback

Esse campo é a função JavaScript que processa o token de ID retornado do comando "One Tap" ou da janela pop-up. Esse atributo é obrigatório se o modo de UX popup do botão "Fazer login com o Google" ou do Google One Tap for usado. Consulte a tabela abaixo para mais informações:

login_uri

Esse atributo é o URI do endpoint de login.

O valor precisa corresponder exatamente a um dos URIs de redirecionamento autorizados do cliente OAuth 2.0, que você configurou no console do Google Cloud e precisa estar em conformidade com nossas Regras de validação de URI de redirecionamento.

Esse atributo pode ser omitido se a página atual for a de login. Nesse caso, a credencial será postada nessa página por padrão.

A resposta da credencial do token de ID é postada no endpoint de login quando um usuário clicar no botão "Fazer login com o Google" e o modo de UX de redirecionamento for usado.

Consulte a tabela a seguir para mais informações:

O endpoint de login precisa processar solicitações POST que contenham uma chave credential com um valor de token de ID no corpo.

Confira a seguir um exemplo de solicitação para o endpoint de login:

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

credential=ID_TOKEN

native_callback

Esse campo é o nome da função JavaScript que processa a credencial de senha retornada pelo gerenciador de credenciais nativo do navegador. Consulte a tabela abaixo para mais informações:

cancel_on_tap_outside

Esse campo define se a solicitação do One Tap será cancelada ou não se um usuário clicar fora do comando. O valor padrão é true. É possível desativar esse recurso definindo o valor como false. Consulte a tabela a seguir para mais informações:

prompt_parent_id

Esse atributo define o ID DOM do elemento do contêiner. Se não estiver definido, o comando "Um toque" vai aparecer no canto superior direito da janela. Consulte a tabela abaixo para mais informações:

valor de uso único

Esse campo é uma string aleatória usada pelo token de ID para evitar ataques de repetição. Consulte a tabela a seguir para mais informações:

O valor de uso único é limitado ao tamanho máximo do JWT compatível com seu ambiente e às restrições de tamanho HTTP do navegador e do servidor individuais.

contexto

Esse campo muda o texto do título e das mensagens no comando de um toque. Consulte a tabela abaixo para mais informações:

A tabela a seguir lista todos os contextos disponíveis e as respectivas descrições:

state_cookie_domain

Se você precisar mostrar o recurso Um toque no domínio pai e nos subdomínios, transmita o domínio pai para esse campo para que um único cookie de estado compartilhado seja usado. Consulte a tabela abaixo para mais informações:

ux_mode

Use esse campo para definir o fluxo de UX usado pelo botão "Fazer login com o Google". O valor padrão é popup. Esse atributo não tem impacto na UX da OneTap. Consulte a tabela abaixo para mais informações:

A tabela a seguir lista os modos de UX disponíveis e as respectivas descrições.

allowed_parent_origin

As origens que podem incorporar o iframe intermediário. O recurso "Um toque" é executado no modo intermediário do iframe se esse campo estiver presente. Consulte a tabela abaixo para mais informações:

A tabela a seguir lista os tipos de valor compatíveis e as descrições deles.

Os prefixos de curinga também são aceitos. Por exemplo, "https://*.example.com" corresponde a example.com e seus subdomínios em todos os níveis (por exemplo, news.example.com, login.news.example.com). Coisas a serem consideradas ao usar caracteres curinga:

• As strings de padrão não podem ser compostas apenas por um curinga e um domínio de nível superior. Por exemplo, https://.com e https://.co.uk são inválidos. Conforme mencionado acima, "https://.example.com" corresponde a example.com e aos subdomínios dele. Também é possível usar uma matriz para representar dois domínios diferentes. Por exemplo, ["https://example1.com", "https://.example2.com"] corresponde aos domínios example1.com, example2.com e aos subdomínios de example2.com.
• Os domínios com caracteres curinga precisam começar com um esquema https:// seguro. Portanto, "*.example.com" é considerado inválido.

Se o valor do campo allowed_parent_origin for inválido, a inicialização do modo de iframe intermediário do One Tap vai falhar e ser interrompida.

intermediate_iframe_close_callback

Substitui o comportamento padrão do iframe intermediário quando os usuários fecham manualmente o One Tap tocando no botão "X" na interface do One Tap. O comportamento padrão é remover imediatamente o iframe intermediário do DOM.

O campo intermediate_iframe_close_callback só entra em vigor no modo intermediário do iframe. Além disso, afeta apenas o iframe intermediário, e não o iframe de um toque. A interface de um toque é removida antes que o callback seja invocado.

itp_support

Esse campo determina se a UX de um toque atualizada precisa ser ativada em navegadores compatíveis com o Intelligent Tracking Prevention (ITP). O valor padrão é false. Confira mais informações na tabela a seguir:

login_hint

Se o aplicativo souber com antecedência qual usuário precisa fazer login, ele poderá fornecer uma sugestão de login para o Google. Se for bem-sucedido, a seleção de conta será ignorada. Os valores aceitos são: um endereço de e-mail ou um valor de campo sub de token de ID.

Para mais informações, consulte o campo login_hint na documentação do OpenID Connect.

hd

Quando um usuário tem várias contas e só precisa fazer login na conta do Workspace, use essa informação para fornecer uma sugestão de nome de domínio ao Google. Se for bem-sucedido, as contas de usuário exibidas durante a seleção de conta serão limitadas ao domínio fornecido. Um valor curinga: * oferece apenas contas do Workspace ao usuário e exclui contas pessoais (user@gmail.com) durante a seleção.

Para mais informações, consulte o campo hd na documentação do OpenID Connect.

use_fedcm_for_prompt

Permita que o navegador controle os comandos de login do usuário e mediar o fluxo de login entre seu site e o Google. O padrão é "false". Consulte a página Migrar para o FedCM para mais informações.

enable_redirect_uri_validation

Ative o fluxo de redirecionamento do botão que obedece às regras de validação do URI de redirecionamento.

Método: google.accounts.id.prompt

O método google.accounts.id.prompt mostra o comando de um toque ou o gerenciador de credenciais nativo do navegador depois que o método initialize() é invocado. Confira o exemplo de código do método abaixo:

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

Normalmente, o método prompt() é chamado no carregamento da página. Devido ao status da sessão e às configurações do usuário no Google, a interface do comando de um toque pode não ser exibida. Para receber notificações sobre o status da interface para momentos diferentes, transmita uma função para receber notificações de status da interface.

As notificações são acionadas nos seguintes momentos:

• Momento de exibição:ocorre depois que o método prompt() é chamado. A notificação contém um valor booleano para indicar se a interface é exibida ou não.

• Momento ignorado:ocorre quando o comando do One Tap é fechado por um cancelamento automático ou manual ou quando o Google não consegue emitir uma credencial, por exemplo, quando a sessão selecionada faz logout do Google.

  Nesses casos, recomendamos que você continue com os próximos provedores de identidade, se houver.

• Momento de dispensa:ocorre quando o Google recupera uma credencial ou quando um usuário quer interromper o fluxo de recuperação de credenciais. Por exemplo, quando o usuário começa a inserir o nome de usuário e a senha na caixa de diálogo de login, você pode chamar o método google.accounts.id.cancel() para fechar o comando de um toque e acionar um momento dispensado.

O exemplo de código a seguir implementa o momento pulado:

<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 de dados: PromptMomentNotification

A tabela abaixo lista os métodos e as descrições do tipo de dados PromptMomentNotification:

Tipo de dados: CredentialResponse

Quando a função callback é invocada, um objeto CredentialResponse é transmitido como parâmetro. A tabela a seguir lista os campos contidos no objeto de resposta de credencial:

credencial

Esse campo é o token de ID como uma string JSON Web Token (JWT) codificada em base64.

Quando decodificado, o JWT se parece com o seguinte exemplo:

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": "Elisa",
  "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"
}

O campo sub é um identificador globalmente exclusivo da Conta do Google. Só use o campo sub como identificador do usuário, porque ele é exclusivo entre todas as Contas do Google e nunca é reutilizado. Não use o endereço de e-mail como identificador, porque uma Conta do Google pode ter vários endereços de e-mail em diferentes momentos.

Usando os campos email, email_verified e hd, é possível determinar se o Google hospeda e é autoritativo para um endereço de e-mail. Nos casos em que o Google é oficial, o usuário é confirmado como proprietário legítimo da conta.

Casos em que o Google é a autoridade:

• email tem o sufixo @gmail.com. Esta é uma conta do Gmail.
• email_verified é verdadeiro e hd está definido, essa é uma conta do Google Workspace.

Os usuários podem se registrar para Contas do Google sem usar o Gmail ou o Google Workspace. Quando email não contém um sufixo @gmail.com e hd está ausente, o Google não é autorizado e a senha ou outros métodos de desafio são recomendados para verificar o usuário. email_verfied também pode ser verdadeiro porque o Google verificou inicialmente o usuário quando a Conta do Google foi criada. No entanto, a propriedade da conta de e-mail de terceiros pode ter mudado desde então.

O campo exp mostra o tempo de expiração para verificar o token no lado do servidor. Leva uma hora para o token de ID recebido no recurso Fazer login com o Google. É necessário verificar o token antes do tempo de expiração. Não use exp para gerenciamento de sessões. Um token de ID expirado não significa que o usuário está desconectado. Seu app é responsável pelo gerenciamento da sessão dos usuários.

select_by

A tabela a seguir lista os valores possíveis para o campo select_by. O tipo de botão usado com a sessão e o estado de consentimento são usados para definir o valor.

• O usuário pressionou o botão de um toque ou "Fazer login com o Google" ou usou o processo de login automático sem toque.

• Uma sessão foi encontrada ou o usuário selecionou e fez login em uma Conta do Google para estabelecer uma nova sessão.

• Antes de compartilhar credenciais de token de ID com seu app, o usuário

  • pressionou o botão "Confirmar" para dar consentimento para o compartilhamento de credenciais; ou
  • já tinha dado consentimento e usou o recurso "Selecionar uma conta" para escolher uma Conta do Google.

O valor desse campo é definido como um destes tipos:

estado

Esse campo só é definido quando o usuário clica em um botão "Fazer login com o Google" para fazer login e o atributo state do botão clicado é especificado. O valor desse campo é o mesmo especificado no atributo state do botão.

Como vários botões "Fazer login com o Google" podem ser renderizados na mesma página, é possível atribuir uma string exclusiva a cada um deles. Portanto, é possível usar esse campo state para identificar em qual botão o usuário clicou para fazer login.

Método: google.accounts.id.renderButton

O método google.accounts.id.renderButton renderiza um botão "Fazer login com o Google" nas suas páginas da Web.

Confira o exemplo de código do método abaixo:

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

Tipo de dados: GsiButtonConfiguration

A tabela a seguir lista os campos e as descrições do tipo de dados GsiButtonConfiguration:

Tipos de atributo

As seções a seguir contêm detalhes sobre o tipo de cada atributo e um exemplo.

tipo

O tipo de botão. O valor padrão é standard.

Consulte a tabela a seguir para mais informações:

A tabela a seguir lista os tipos de botão disponíveis e as descrições deles:

Tipo
standard
icon

tema

O tema do botão. O valor padrão é outline. Confira mais informações na tabela a seguir:

A tabela a seguir lista os temas disponíveis e as respectivas descrições:

Tema
outline
filled_blue
filled_black

tamanho

O tamanho do botão. O valor padrão é large. Confira mais informações na tabela a seguir:

A tabela a seguir lista os tamanhos de botão disponíveis e as respectivas descrições:

Tamanho
large
medium
small

texto

O texto do botão. O valor padrão é signin_with. Não há diferenças visuais no texto dos botões de ícone que têm atributos text diferentes. A única exceção é quando o texto é lido para acessibilidade na tela.

Consulte a tabela a seguir para mais informações:

A tabela a seguir lista todos os textos de botão disponíveis e as descrições deles:

Texto
signin_with
signup_with
continue_with
signin

forma

A forma do botão. O valor padrão é rectangular. Consulte a tabela a seguir para mais informações:

A tabela a seguir lista as formas de botão disponíveis e as respectivas descrições:

Forma
rectangular
pill
circle
square

logo_alignment

O alinhamento do logotipo do Google. O valor padrão é left. Esse atributo se aplica apenas ao tipo de botão standard. Confira mais informações na tabela a seguir:

A tabela a seguir lista os alinhamentos disponíveis e as descrições deles:

logo_alignment
left
center

largura

A largura mínima do botão, em pixels. A largura máxima é de 400 pixels.

Consulte a tabela a seguir para mais informações:

localidade

Opcional. Mostra o texto do botão usando a localidade especificada. Caso contrário, usa as configurações da Conta do Google ou do navegador do usuário. Adicione o parâmetro hl e o código de idioma à diretiva src ao carregar a biblioteca, por exemplo: gsi/client?hl=<iso-639-code>.

Se não for definido, a localidade padrão do navegador ou a preferência do usuário da sessão do Google serão usadas. Portanto, usuários diferentes podem ver versões diferentes de botões localizados e, possivelmente, com tamanhos diferentes.

Consulte a tabela a seguir para mais informações:

click_listener

É possível definir uma função JavaScript para ser chamada quando o botão "Fazer login com o Google" é clicado usando o atributo 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...")
  }
  

Neste exemplo, a mensagem Botão "Fazer login com o Google" clicado... é registrada no console quando o botão "Fazer login com o Google" é clicado.

estado

Opcional, como vários botões do "Fazer login com o Google" podem ser renderizados na mesma página, é possível atribuir a cada botão uma string exclusiva. A mesma string seria retornada com o token de ID para que você possa identificar qual botão o usuário clicou para fazer login.

Consulte a tabela a seguir para mais informações:

Tipo de dados: credencial

Quando a função native_callback é invocada, um objeto Credential é transmitido como o parâmetro. A tabela a seguir lista os campos contidos no objeto:

Método: google.accounts.id.disableAutoSelect

Quando o usuário sai do site, é necessário chamar o método google.accounts.id.disableAutoSelect para registrar o status nos cookies. Isso evita um loop morto de UX. Confira o snippet de código do método abaixo:

google.accounts.id.disableAutoSelect()

O exemplo de código a seguir implementa o método google.accounts.id.disableAutoSelect com uma função onSignout():

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

Método: google.accounts.id.storeCredential

Esse método é um wrapper para o método store() da API do gerenciador de credenciais nativa do navegador. Portanto, ele só pode ser usado para armazenar uma credencial de senha. Confira o exemplo de código do método abaixo:

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

O exemplo de código a seguir implementa o método google.accounts.id.storeCredential com uma função onSignIn():

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

Método: google.accounts.id.cancel

É possível cancelar o fluxo de um toque se você remover a solicitação do DOM da parte confiável. A operação de cancelamento será ignorada se uma credencial já estiver selecionada. Confira o exemplo de código abaixo do método:

google.accounts.id.cancel()

O exemplo de código abaixo implementa o método google.accounts.id.cancel() com uma função onNextButtonClicked():

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

Callback de carregamento de biblioteca: onGoogleLibraryLoad

É possível registrar um callback onGoogleLibraryLoad. Ele é notificado depois que a biblioteca JavaScript do recurso "Fazer login com o Google" é carregada:

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

Esse callback é apenas um atalho para o callback window.onload. Não há diferenças no comportamento.

O exemplo de código a seguir implementa um callback onGoogleLibraryLoad:

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

Método: google.accounts.id.revoke

O método google.accounts.id.revoke revoga a concessão de OAuth usada para compartilhar o token de ID do usuário especificado. Confira este snippet de código do método: javascript google.accounts.id.revoke(login_hint, callback)

O exemplo de código a seguir mostra como usar o método revoke com um ID.

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

Tipo de dados: RevocationResponse

Quando a função callback é invocada, um objeto RevocationResponse é transmitido como parâmetro. A tabela a seguir lista os campos contidos no objeto de resposta de revogação:

bem-sucedido

Esse campo é um valor booleano definido como verdadeiro se a chamada de método de revogação tiver sido bem-sucedida ou falso em caso de falha.

erro

Esse campo é um valor de string e contém uma mensagem de erro detalhada se a chamada do método de revogação falhar, será indefinido em caso de sucesso.