Referência da API HTML Fazer login com o Google

Esta página de referência descreve a API Sign In With Google HTML data attributes. É possível usar a API para mostrar o comando "One Tap" ou o botão "Fazer login com o Google" nas suas páginas da Web.

Elemento com ID "g_id_onload"

Você pode colocar atributos de dados do Fazer login com o Google em qualquer elemento visível ou invisível, como <div> e <span>. O único requisito é que o ID do elemento seja definido como g_id_onload. Não coloque esse ID em vários elementos.

Atributos de dados

A tabela a seguir lista os atributos de dados com as respectivas descrições:

Tipos de atributo

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

data-client_id

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

data-auto_prompt

Esse atributo determina se o anúncio de um toque será exibido ou não. O valor padrão é true. O Google One Tap não é exibido quando esse valor é false. Consulte a tabela abaixo para mais informações:

data-auto_select

Esse atributo determina se um token de ID será retornado automaticamente, sem interação do usuário, se apenas uma sessão do Google tiver aprovado seu app. O valor padrão é false. Consulte a tabela a seguir para mais informações:

data-login_uri

Esse atributo é o URI do endpoint de login.

O valor precisa corresponder exatamente a um dos URIs de redirecionamento autorizados para o cliente OAuth 2.0, que você configurou no Console de APIs, e precisa obedecer às nossas regras de validação do URI de redirecionamento.

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

A resposta da credencial do token de ID é postada no endpoint de login quando nenhuma função de callback é definida e um usuário clica nos botões "Fazer login com o Google" ou "Um toque" ou quando o login automático ocorre.

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.

Veja 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

data-callback

Esse atributo é o nome da função JavaScript que processa o token de ID retornado. Consulte a tabela a seguir para mais informações:

Um dos atributos data-login_uri e data-callback pode ser usado. Ele depende das seguintes configurações de componente e modo de UX:

• O atributo data-login_uri é necessário para o modo de UX redirect do botão Fazer login com o Google, que ignora o atributo data-callback.

• Um desses dois atributos precisa ser definido para o Google OneTap e o modo de UX popup do botão de login do Google. Se ambos forem definidos, o atributo data-callback terá precedência mais alta.

A API HTML não oferece suporte a funções JavaScript em um namespace. Em vez disso, use uma função global do JavaScript sem um namespace. Por exemplo, use mylibCallback em vez de mylib.callback.

data-native_login_uri

Esse atributo é o URL do endpoint do gerenciador de credenciais de senha. Se você definir o atributo data-native_login_uri ou o atributo data-native_callback, a biblioteca JavaScript vai voltar para o gerenciador de credenciais nativo quando não houver uma sessão do Google. Não é possível definir os atributos data-native_callback e data-native_login_uri. Consulte a tabela a seguir para mais informações:

callback_nativo_de_dados

Esse atributo é o nome da função JavaScript que processa a credencial de senha retornada do gerenciador de credenciais nativo do navegador. Se você definir o atributo data-native_login_uri ou o atributo data-native_callback, a biblioteca JavaScript vai usar o gerenciador de credenciais nativo quando não houver uma sessão do Google. Não é possível definir data-native_callback e data-native_login_uri. Confira mais informações na tabela a seguir:

A API HTML não oferece suporte a funções JavaScript em um namespace. Em vez disso, use uma função global do JavaScript sem um namespace. Por exemplo, use mylibCallback em vez de mylib.callback.

data-native_id_param

Ao enviar a credencial de senha para o endpoint do gerenciador de credenciais de senha, é possível especificar o nome do parâmetro para o campo credential.id. O nome padrão é email. Consulte a tabela a seguir para mais informações:

data-native_password_param

Ao enviar a credencial de senha para o endpoint do gerenciador de credenciais de senha, é possível especificar o nome do parâmetro para o valor credential.password. O nome padrão é password. Confira mais informações na tabela a seguir:

data-cancel_on_tap_outside

Esse atributo define se a solicitação do One Tap será cancelada ou não se o usuário clicar fora do comando. O valor padrão é true. Para desativar, defina o valor como false. Consulte a tabela a seguir para mais informações:

data-prompt_parent_id

Esse atributo define o ID do DOM do elemento do contêiner. Se ela não estiver definida, a solicitação de um toque será exibida no canto superior direito da janela. Consulte a tabela abaixo para mais informações:

data-skip_prompt_cookie

Esse atributo pula o recurso Um toque se o cookie especificado tiver um valor não vazio. Consulte a tabela abaixo para mais informações:

data-nonce

Esse atributo é 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.

data-context

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

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

data-moment_callback

Esse atributo é o nome da função do listener de notificação de status da interface do prompt. Para mais informações, consulte o tipo de dados PromptMomentNotification.

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

As funções JavaScript em um namespace não são compatíveis com a API HTML. Em vez disso, use uma função global do JavaScript sem um namespace. Por exemplo, use mylibCallback em vez de mylib.callback.

data-state_cookie_domain

Se você precisar mostrar o One Tap em um domínio pai e seus subdomínios, transmita o domínio pai para esse atributo para que um único cookie de estado compartilhado seja usado. Consulte a tabela a seguir para mais informações:

data-ux_mode

Esse atributo define o fluxo de UX usado pelo botão "Fazer login com o Google". O valor padrão é popup. Esse atributo não afeta a UX do One Tap. Consulte a tabela abaixo para mais informações:

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

data-allowed_parent_origin

As origens que podem incorporar o iframe intermediário. Um toque é executado no modo iframe intermediário se esse atributo estiver presente. Consulte a tabela a seguir para mais informações:

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

Se o valor do atributo data-allowed_parent_origin for inválido, a inicialização com um toque do modo iframe intermediário falhará e será interrompida.

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. Como observado acima, "https://*.example.com" corresponde a example.com e seus subdomínios. Também é possível usar uma lista separada por vírgulas para representar dois domínios diferentes. Por exemplo, "https://example1.com,https://*.example2.com" corresponde aos domínios example1.com, example2.com e 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.

data-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 data-intermediate_iframe_close_callback só entra em vigor no modo intermediário de iframe. E isso 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.

A API HTML não oferece suporte a funções JavaScript em um namespace. Em vez disso, use uma função JavaScript global sem namespace. Por exemplo, use mylibCallback em vez de mylib.callback.

data-itp_support

Esse campo determina se a UX do Toque inteligente atualizada precisa ser ativada em navegadores com suporte à prevenção de rastreamento inteligente (ITP, na sigla em inglês). O valor padrão é false. Confira mais informações na tabela a seguir:

data-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 campo sub do token de ID.

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

dados-hd

Quando um usuário tiver várias contas e só precisar fazer login com a conta do Workspace, use esse recurso para fornecer uma dica 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 de consumidor (user@gmail.com) durante a seleção de conta.

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

data-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.

data-enable_redirect_uri_validation

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

Elemento com classe "g_id_signin"

Se você adicionar g_id_signin ao atributo class de um elemento, o elemento será renderizado como um botão do Fazer login com o Google.

Você pode renderizar vários botões "Fazer login com o Google" na mesma página. Cada botão pode ter suas próprias configurações visuais. As configurações são definidas pelos seguintes atributos de dados.

Atributos de dados visuais

A tabela a seguir lista os atributos de dados visuais e as descrições deles:

Tipos de atributo

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

data-type

O tipo de botão. O valor padrão é standard. Confira mais informações na tabela a seguir:

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

Tipo
standard
icon

data-theme

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

data-size

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-dados

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 data-text diferentes. A única exceção é quando o texto é lido para acessibilidade de tela.

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

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

Texto
signin_with
signup_with
continue_with
signin

formato de dados

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 descrições delas:

Forma
rectangular
pill
circle
square

data-logo_alignment

O alinhamento do logotipo do Google. O valor padrão é left. Esse atributo só se aplica 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

data-width

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

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

data-locale

Opcional. Mostre o texto do botão usando a localidade especificada. Caso contrário, o padrão vai ser a Conta do Google ou as configurações 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:

data-click_listener

Você pode definir uma função JavaScript a ser chamada quando o botão "Fazer login com o Google" receber um clique usando o atributo 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>

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 dos dados

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:

Integração no servidor

Seus endpoints do lado do servidor precisam processar as seguintes solicitações HTTP POST.

O endpoint do gerenciador de tokens de ID

O endpoint do gerenciador de tokens de ID processa o token de ID. Com base no status da conta correspondente, você pode fazer login do usuário e direcioná-lo para uma página de inscrição ou para uma página de vinculação de conta para mais informações.

A solicitação HTTP POST contém as seguintes informações:

credencial

Quando decodificado, o token de ID fica parecido com este 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": "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"
}

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.

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

Casos em que o Google é confiável:

• email tem um sufixo @gmail.com, ou seja, é 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_verified 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 prazo de validade para você verificar o token no seu 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ão. Um token de ID expirado não significa que o usuário foi 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 "Um toque" ou "Fazer login com o Google" ou usou o processo de login automático sem toque.

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

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

  • pressionou o botão "Confirmar" para conceder o consentimento de compartilhamento de credenciais; ou
  • já tinha concedido consentimento e usado a opção "Selecionar uma conta" para escolher uma Conta do Google.

O valor desse campo é definido para um destes tipos,

estado

Esse parâmetro só é definido quando o usuário clica em um botão "Fazer login com o Google" para fazer login e o atributo data-state do botão clicado é especificado. O valor desse campo é o mesmo especificado no atributo data-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 parâmetro state para identificar em qual botão o usuário clicou para fazer login.

Endpoint do gerenciador de credenciais de senha

O endpoint do gerenciador de credenciais de senha processa credenciais de senha que o gerenciador de credenciais nativo recupera.

A solicitação HTTP POST contém as seguintes informações: