Referência da API HTML para Login com o Google

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Esta página de referência descreve a API de atributos de dados HTML do recurso Fazer login com o Google. Você pode usar a API para exibir a solicitação "Um toque" ou o botão "Fazer login com o Google" nas suas páginas da Web.

Elemento com o ID "g_id_onload"

É possível 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 e as respectivas descrições:

Atributo
data-client_id ID do cliente do seu aplicativo
data-auto_prompt Mostrar o toque do Google One.
data-auto_select Ativa a seleção automática no Google One Tap.
data-login_uri O URL do endpoint de login
data-callback O nome da função do gerenciador de tokens de ID JavaScript
data-native_login_uri O URL do endpoint do gerenciador de credenciais de senha
data-native_callback O nome da função do gerenciador de credenciais de senha do JavaScript
data-native_id_param O nome do parâmetro do valor credential.id
data-native_password_param O nome do parâmetro do valor credential.password
data-cancel_on_tap_outside Controla se o usuário deve cancelar o pedido se clicar fora dele.
data-prompt_parent_id O ID do DOM do elemento do contêiner de solicitação com um toque
data-skip_prompt_cookie Pula um toque se o cookie especificado tiver um valor não vazio.
data-nonce Uma string aleatória para tokens de ID
data-context Título e palavras na solicitação de um toque
data-moment_callback O nome da função do listener de notificações do status da IU do prompt.
data-state_cookie_domain Se você precisar chamar o recurso "Um toque" no domínio pai e nos subdomínios dele, passe o domínio pai para esse atributo para que um único cookie compartilhado seja usado.
data-ux_mode Fluxo de UX do botão "Fazer login com o Google"
data-allowed_parent_origin As origens que têm permissão para incorporar o iframe intermediário. Um toque vai ser executado no modo iframe intermediário se esse atributo estiver presente.
data-intermediate_iframe_close_callback Substitui o comportamento padrão do iframe intermediário quando os usuários fecham manualmente um toque.
data-itp_support Permite fazer upgrade da UX de um toque em navegadores ITP.

Tipos de atributo

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

ID do cliente de dados

Esse atributo é o ID do cliente do app, que é encontrado e criado no Google Developers Console. Veja mais informações na tabela a seguir:

Tipo Obrigatório Exemplo
string Sim data-client_id="CLIENT_ID.apps.googleusercontent.com"

solicitação automática de dados

Esse atributo determina se é necessário exibir um toque. O valor padrão é true. O toque do Google One não será exibido quando esse valor for false. Consulte a tabela a seguir para mais informações:

Tipo Obrigatório Exemplo
boolean Opcional data-auto_prompt="true"

seleção automática de dados

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

Tipo Obrigatório Exemplo
boolean Opcional data-auto_select="true"

data-login_uri

Esse atributo é o URI do endpoint de login. Pode ser omitido se a página atual for a de login. Nesse caso, a credencial é postada nesta página por padrão.

A resposta da credencial do token de ID é postada no seu 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 ocorre um login automático.

Veja mais informações na tabela a seguir:

Tipo Opcional Exemplo
URL O padrão é o URI da página atual ou o valor especificado.
Ignorado quando data-ux_mode="popup" e data-callback são definidos.		 data-login_uri="https://www.example.com/login"

O endpoint de login precisa processar solicitações POST contendo 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 gerencia o token de ID retornado. Veja mais informações na tabela a seguir:

Tipo Obrigatório Exemplo
string Obrigatório, se data-login_uri não estiver definido. data-callback="handleToken"

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

  • O atributo data-login_uri é obrigatório para o botão "Fazer login com o Google" no modo UX redirect, que ignora o atributo data-callback.

  • Um desses dois atributos precisa ser definido para o Google One Tap e para o modo UX de botão popup do Login do Google. Se ambos forem definidos, o atributo data-callback terá uma precedência maior.

As funções JavaScript em um namespace não são compatíveis com a API HTML. Em vez disso, use uma função JavaScript global 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 data-native_callback, a biblioteca JavaScript usará o gerenciador de credenciais nativo quando não houver uma sessão do Google. Você não tem permissão para definir os atributos data-native_callback e data-native_login_uri. Veja mais informações na tabela a seguir:

Tipo Obrigatório Exemplo
string Opcional data-login_uri="https://www.example.com/password_login"

data-native_callback

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 data-native_callback, a biblioteca JavaScript usará o gerenciador de credenciais nativo quando não houver uma sessão do Google. Você não tem permissão para definir data-native_callback e data-native_login_uri. Consulte a tabela a seguir para mais informações:

Tipo Obrigatório Exemplo
string Opcional data-native_callback="handlePasswordCredential"

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

data-native_id_param

Ao enviar a credencial de senha ao endpoint do gerenciador, você pode especificar o nome do parâmetro do campo credential.id. O nome padrão é email. Veja mais informações na tabela a seguir:

Tipo Obrigatório Exemplo
URL Opcional data-native_id_param="user_id"

data-native_password_param

Ao enviar a credencial de senha ao endpoint do gerenciador, você pode especificar o nome do parâmetro do valor credential.password. O nome padrão é password. Consulte a tabela a seguir para mais informações:

Tipo Obrigatório Exemplo
URL Opcional data-native_password_param="pwd"

data-cancel_on_tap_Outside

Esse atributo define se a solicitação de um toque será cancelada ou não se o usuário clicar fora da solicitação. O valor padrão é true. Para desativá-lo, defina o valor como false. Veja mais informações na tabela a seguir:

Tipo Obrigatório Exemplo
boolean Opcional data-cancel_on_tap_outside="false"

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 a seguir para mais informações:

Tipo Obrigatório Exemplo
string Opcional data-prompt_parent_id="parent_id"

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

Tipo Obrigatório Exemplo
string Opcional data-skip_prompt_cookie="SID"

valor de uso único de dados

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

Tipo Obrigatório Exemplo
string Opcional data-nonce="biaqbm70g23"

O tamanho do valor de uso único é limitado ao tamanho máximo de JWT aceito pelo seu ambiente e às restrições de tamanho HTTP de navegadores e servidores individuais.

contexto de dados

Esse atributo muda o texto do título e as mensagens mostradas na solicitação de um toque. Veja mais informações na tabela a seguir:

Tipo Obrigatório Exemplo
string Opcional data-context="use"

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

Contexto
signin "Fazer login com o Google"
signup "Assine com o Google"
use "Usar com o Google"

data-moment_callback

Esse atributo é o nome da função do listener de notificações de status da IU da solicitação. Para mais informações, consulte o tipo de dados PromptMomentNotification. Veja mais informações na tabela a seguir:

Tipo Obrigatório Exemplo
string Opcional data-moment_callback="logMomentNotification"

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

Se você precisar exibir um toque em um domínio pai e nos subdomínios dele, transmita o domínio pai para esse atributo para que um único cookie de estado compartilhado seja usado. Veja mais informações na tabela a seguir:

Tipo Obrigatório Exemplo
string Opcional data-state_cookie_domain="example.com"

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 de um toque. Consulte a tabela a seguir para mais informações:

Tipo Obrigatório Exemplo
string Opcional data-ux_mode="redirect"

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

Modo de UX
popup Executa o fluxo de UX de login em uma janela pop-up.
redirect Executa o fluxo de UX de login por um redirecionamento de página completo.

data-allowed_parent_origin

As origens que têm permissão para incorporar o iframe intermediário. Um toque é executado no modo de iframe intermediário se esse atributo estiver presente. Veja mais informações na tabela a seguir:

Tipo Obrigatório Exemplo
string ou matriz de string Opcional data-allowed_parent_origin="https://example.com"

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

Tipos de valor
string Um URI de domínio único. "https://example.com"
string array Uma lista de URIs de domínio separados por vírgula. "https://news.example.com,https://local.example.com"

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 curinga também são compatíveis. Por exemplo, "https://*.example.com" corresponderá a example.com e aos subdomínios dele em todos os níveis (por exemplo, news.example.com, login.news.example.com). Considere o seguinte ao usar caracteres curinga:

  • As strings de padrão não podem ser compostas apenas por um caractere curinga e por 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" corresponderá a example.com e aos subdomínios dele. Você também pode usar uma lista separada por vírgulas para representar dois domínios diferentes. Por exemplo, "https://example1.com,https://*.example2.com" corresponderá aos domínios example1.com, example2.com e subdomínios de example2.com
  • Os domínios curinga precisam começar com um esquema https:// seguro. "*.example.com" será considerado inválido.

data-intermediate_iframe_close_callback

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

O campo data-intermediate_iframe_close_callback entra em vigor somente no modo de iframe intermediário. E isso afeta apenas o iframe intermediário, e não o iframe com um toque. A IU com um toque é removida antes da invocação do callback.

Tipo Obrigatório Exemplo
função Opcional data-intermediate_iframe_close_callback="logBeforeClose"

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

suporte a data-itp_

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

Tipo Obrigatório Exemplo
boolean Opcional data-itp_support="true"

Elemento com a classe "g_id_signin"

Se você adicionar g_id_signin ao atributo class de um elemento, ele será renderizado como um botão "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 as próprias configurações visuais. As configurações são definidas pelos atributos de dados a seguir.

Atributos de dados visuais

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

Atributo
data-type O tipo de botão: ícone ou botão padrão.
data-theme O tema do botão. Por exemplo, fill_blue oufilled_black.
data-size O tamanho do botão. Por exemplo, pequeno ou grande.
data-text O texto do botão. Por exemplo, "Fazer login com o Google" ou "Fazer login com o Google".
data-shape O formato do botão. Por exemplo, retangular ou circular.
data-logo_alignment Alinhamento do logotipo do Google: à esquerda ou no centro
data-width A largura do botão, em pixels.
data-locale O texto do botão é renderizado no idioma definido nesse atributo.
data-click_listener Se definida, essa função será chamada quando o usuário clicar no botão "Fazer login com o Google".

Tipos de atributo

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

tipo de dados

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

Tipo Obrigatório Exemplo
string Sim data-type="icon"

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

Tipo
standard Um botão com texto ou informações personalizadas:
icon Um botão de ícone sem texto:

data-theme

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

Tipo Obrigatório Exemplo
string Opcional data-theme="filled_blue"

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

Tema
outline Tema do botão padrão:
Um botão padrão com fundo branco Um botão com um plano de fundo branco Um botão personalizado com fundo branco
filled_blue O tema do botão azul:
Um botão padrão com fundo azul Um botão de ícone com um plano de fundo azul Um botão personalizado com fundo azul
filled_black O tema do botão preto:
Um botão padrão com fundo preto Um botão com um plano de fundo preto Um botão personalizado com fundo preto

data-size

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

Tipo Obrigatório Exemplo
string Opcional data-size="small"

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

Tamanho
large Um botão grande:
Um botão padrão grande Um botão grande de ícone Um botão grande e personalizado
medium Um botão de tamanho médio:
Um botão padrão médio Um botão de ícone médio
small Um botão pequeno:
Um botão pequeno Um botão pequeno de ícone

texto de dados

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

Veja mais informações na tabela a seguir:

Tipo Obrigatório Exemplo
string Opcional data-text="signup_with"

A tabela a seguir lista os textos dos botões disponíveis e as descrições:

Texto
signin_with O texto do botão é "Fazer login com o Google":
Um botão padrão chamado &quot;Fazer login com o Google&quot;. Um botão de ícone sem texto visível
signup_with O texto do botão é "Assine com o Google":
Um botão padrão chamado &quot;Inscrever-se no Google&quot; Um botão de ícone sem texto visível
continue_with O texto do botão é "Continue with Google":
Um botão padrão chamado &quot;Continuar com o Google&quot; Um botão de ícone sem texto visível
signin O texto do botão é "Fazer login":
Um botão padrão chamado &quot;Fazer login&quot; Um botão de ícone sem texto visível

formato de dados

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

Tipo Obrigatório Exemplo
string Opcional data-shape="rectangular"

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

Forma
rectangular O botão em formato retangular. Se usado para o tipo de botão icon, é o mesmo que square.
Um botão padrão retangular Um botão de ícone retangular Um botão personalizado retangular
pill O botão em forma de pílula. Se usado para o tipo de botão icon, é o mesmo que circle.
Um botão padrão em formato de pílula Um botão de ícone em forma de pílula Um botão personalizado em forma de pílula
circle O botão em forma de círculo. Se usado para o tipo de botão standard, é o mesmo que pill.
Um botão circular padrão Um botão de ícone circular Um botão circular personalizado
square O botão em formato quadrado. Se usado para o tipo de botão standard, é o mesmo que rectangular.
Um botão quadrado padrão Um botão de ícone quadrado Um botão quadrado personalizado

alinhamento_dados-logotipo

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

Tipo Obrigatório Exemplo
string Opcional data-logo_alignment="center"

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

alinhamento_logotipo
left Alinhamento à esquerda do logotipo do Google:
Um botão padrão com o logotipo G à esquerda
center Alinhar o logotipo do Google ao centro:
Um botão padrão com o logotipo G no centro

largura dos dados

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

Veja mais informações na tabela a seguir:

Tipo Obrigatório Exemplo
string Opcional data-width=400

localidade de dados

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

Veja mais informações na tabela a seguir:

Tipo Obrigatório Exemplo
string Opcional data-locale="zh_CN"

listener de cliques

É possível definir uma função JavaScript que será chamada quando o botão "Fazer login com o Google" for 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...")
  }

No exemplo acima, a mensagem Botão "Fazer login com o Google" foi clicado... será registrada no console quando você clicar no botão "Fazer login com o Google".

Integração no servidor

Os 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 do token de ID processa o token de código. Com base no status da conta correspondente, você pode fazer o login do usuário e direcioná-lo para uma página de inscrição ou direcioná-lo a uma página de vinculação de contas para mais informações.

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

Formato Nome Descrição
Cookie g_csrf_token Uma string aleatória que muda a cada solicitação com o endpoint do gerenciador.
Parâmetro de solicitação g_csrf_token Uma string que é igual ao valor do cookie anterior, g_csrf_token.
Parâmetro de solicitação credential O token de ID que o Google emite.
Parâmetro de solicitação select_by Como a credencial é selecionada.

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

A tabela a seguir lista os possíveis valores do campo select_by. O tipo de botão usado junto 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 existente 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 de token de ID com seu app, o usuário pode

    • tiver pressionado o botão "Confirmar" para autorizar a ação de compartilhar credenciais; ou
    • já havia dado consentimento e usado a opção "Selecionar uma conta" para escolher uma Conta do Google.

O valor desse campo é definido como um destes tipos,

Valor Descrição
auto Login automático de um usuário com uma sessão que já havia concedido consentimento para compartilhar credenciais.
user Um usuário com uma sessão que já deu consentimento pressionou o botão "Continuar como" com um toque para compartilhar as credenciais.
user_1tap Um usuário com uma sessão existente pressionou o botão "Continuar como" com um toque para conceder consentimento e compartilhar credenciais. Aplicável apenas ao Chrome v75 e posterior.
user_2tap Um usuário sem uma sessão existente pressionou o botão "Continuar como" com um toque para selecionar uma conta e depois clicou no botão "Confirmar" em uma janela pop-up para conceder consentimento e compartilhar credenciais. Aplicável a navegadores não baseados no Chromium.
btn Um usuário com uma sessão que já concedeu consentimento pressionou o botão "Fazer login com o Google" e selecionou uma Conta do Google em "Escolher uma conta" para compartilhar credenciais.
btn_confirm Um usuário com uma sessão existente pressionou o botão "Fazer login com o Google" e o botão "Confirmar" para conceder consentimento e compartilhar credenciais.
btn_add_session Um usuário sem uma sessão que já concedeu consentimento pressionou o botão Fazer login com o Google para selecionar uma Conta do Google e compartilhar credenciais.
btn_confirm_add_session Um usuário sem uma sessão existente pressionou primeiro o botão "Fazer login com o Google" para selecionar uma Conta do Google e, em seguida, o botão "Confirmar" para autorizar e compartilhar credenciais.

Endpoint do gerenciador de credenciais da senha

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

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

Formato Nome Descrição
Cookie g_csrf_token Uma string aleatória que muda a cada solicitação com o endpoint do gerenciador.
Parâmetro de solicitação g_csrf_token Uma string que é igual ao valor do cookie anterior, g_csrf_token.
Parâmetro de solicitação email Esse token de ID é emitido pelo Google.
Parâmetro de solicitação password Como a credencial é selecionada.