Referência da API HTML para Login com o Google

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

Elemento com ID "g_id_onload"

É possível colocar atributos de dados do 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 use esse ID em vários elementos.

Atributos de dados

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

Atributo
data-client_id	ID do cliente do seu aplicativo
data-auto_prompt	Mostre o toque do Google One.
data-auto_select	Permite 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 do 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 a solicitação será cancelada se o usuário clicar fora dela.
data-prompt_parent_id	O ID do DOM do elemento do contêiner de solicitação com um toque
data-skip_prompt_cookie	Ignora um toque se o cookie especificado tiver um valor não vazio.
data-nonce	String aleatória de tokens de ID
data-context	O título e as palavras na solicitação com um toque
data-moment_callback	O nome da função do listener de notificação de status da IU do prompt
data-state_cookie_domain	Se você precisar chamar um toque no domínio pai e nos subdomínios dele, transmita 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. O Tap será executado no modo de iframe intermediário se esse atributo estiver presente.
data-intermediate_iframe_close_callback	Modifica o comportamento do iframe intermediário padrão quando os usuários fecham manualmente um toque.
data-itp_support	Ativa a UX de um toque atualizada em navegadores ITP.

Tipos de atributo

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

data-client_id

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

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

data-auto_prompt

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

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

data-auto_select

Este atributo determina se um token de ID será retornado ou não automaticamente, sem 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 sua página de login. Nesse caso, a credencial será postada nesta página por padrão.

A resposta da credencial do ID é publicada no endpoint de login quando nenhuma função de retorno de chamada é definida e um usuário clica nos botões "Fazer login com o Google" ou "Toque com um toque" ou quando a assinatura automática é feita.

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 estão definidos.	data-login_uri="https://www.example.com/login"

Seu 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 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 de componente e modo de UX:

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

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

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 voltará ao 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. Consulte a tabela a seguir para mais informações:

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 gerencia a credencial da 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 para o 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 com um toque não será cancelada 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 não estiver definida, a solicitação 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"

data-skip_prompt_cookie

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. 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 compatível com o ambiente e às restrições individuais de tamanho do navegador e do servidor HTTP.

contexto de dados

Esse atributo altera o texto do título e das mensagens exibidas na solicitação 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 respectivas descrições:

Contexto
signin	"Faça login com o Google"
signup	"Inscreva-se no Google"
use	"Uso com o Google"

data-moment_callback

Esse atributo é o nome da função do listener de notificação de status da IU de 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.

data-state_cookie_domain

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 com 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	Realiza o fluxo de UX de login em uma janela pop-up.
redirect	Realiza o fluxo de UX de login por um redirecionamento de página completa.

data-allowed_parent_origin

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

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 valor compatíveis e as respectivas descrições.

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

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

Prefixos curinga também são aceitos. 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). Observações importantes 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 os subdomínios dele. 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" 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

Modifica o comportamento padrão do iframe intermediário quando os usuários fecham manualmente 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 só entra em vigor no modo intermediário do iframe. E isso afeta apenas o iframe intermediário, em vez do iframe do One Tap. A IU do One Tap é 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.

data-itp_support

Este campo determina se a UX de um toque atualizada precisa estar ativada em navegadores compatíveis com a Prevenção inteligente de rastreamento (ITP, na sigla em inglês). 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 a um atributo class de um elemento, ele será renderizado como um botão do 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 seguintes atributos de dados.

Atributos de dados visuais

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

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 ou fill_black.
data-size	O tamanho do botão. Por exemplo, pequeno ou grande.
data-text	O texto do botão. Por exemplo, "Faça login com o Google" ou "Inscreva-se no Google".
data-shape	É a forma 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.

Tipos de atributo

As seções a seguir contêm detalhes sobre cada tipo de 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	Yes	data-type="icon"

A tabela a seguir lista os tipos de botão disponíveis e as respectivas 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 respectivas descrições:

Tema
outline	Tema padrão do botão:
filled_blue	O tema do botão preenchido em azul:
filled_black	O tema do botão cheio de 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 deles.

Tamanho
large	Um botão grande:
medium	Um botão de tamanho médio:
small	Um botão pequeno:

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 com atributos data-text diferentes. 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 deles:

Texto
signin_with	O texto do botão é "Fazer login com o Google":
signup_with	O texto do botão é "Inscreva-se no Google":
continue_with	O texto do botão é "Continue with Google" (Continuar com o Google):
signin	O texto do botão é "Fazer login":

formato de dados

É a forma do botão. O valor padrão é rectangular. Consulte a tabela a seguir para ver 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 delas:

Formato
rectangular	O botão em formato retangular. Se for usado para o tipo de botão icon, será igual a square.
pill	O botão em forma de pílula. Se for usado para o tipo de botão icon, ele será igual a circle.
circle	O botão em forma de círculo. Se for usado para o tipo de botão standard, ele será igual a pill.
square	Botão quadrado. Se for usado para o tipo de botão standard, ele será igual a rectangular.

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

alinhamento_logotipo
left	Alinhamento à esquerda do logotipo do Google:
center	Alinha o centro do logotipo do Google:

largura de dados

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

Veja mais informações na tabela a seguir:

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

data-locale

A localidade predefinida do texto do botão. Se não estiver definido, será usada a localidade padrão do navegador ou a preferência do usuário da sessão do Google. Portanto, usuários diferentes podem ver versões diferentes 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"

Integração no servidor

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

Endpoint do gerenciador de tokens de ID

O endpoint do gerenciador de tokens de código processa o token de código. Com base no status da conta correspondente, é possível fazer login do usuário e direcioná-lo a uma página de inscrição ou a uma página de vinculação de contas para mais informações.

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

Formatação	Nome	Descrição
Cookie	g_csrf_token	Uma string aleatória que muda a cada solicitação para o endpoint do gerenciador.
Parâmetro de solicitação	g_csrf_token	Uma string igual ao valor de 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": "[e-mail]", // 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 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 "Toque com um clique" 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 credenciais de token de ID com seu app, o usuário pode

  • pressionado o botão "Confirmar" para conceder consentimento para compartilhar credenciais; ou
  • tinha concedido consentimento e usou "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 tinha concedido consentimento para compartilhar credenciais anteriormente.
user	Um usuário com uma sessão existente que já havia consentido pressionou o botão "Toque e continue" para compartilhar credenciais.
user_1tap	Um usuário com uma sessão pressione o botão One Tap 'Continue as' 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 One Tap 'Continue as' para selecionar uma conta e o botão "Confirm" em uma janela pop-up para conceder consentimento e compartilhar credenciais. Aplica-se a navegadores não baseados no Chromium.
btn	Um usuário que já tinha consentido com uma sessão 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 pressionar 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 existente que já tenha consentido 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 o botão "Fazer login com o Google" para selecionar uma Conta do Google e, em seguida, pressionou o botão "Confirmar" para autorizar e compartilhar credenciais.

Endpoint do gerenciador de credenciais de senha

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

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

Formatação	Nome	Descrição
Cookie	g_csrf_token	Uma string aleatória que muda a cada solicitação para 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 código emitido pelo Google.
Parâmetro de solicitação	password	Como a credencial é selecionada.

Observação: é possível alterar os nomes dos parâmetros email e password com os atributos de dados.