Aviso: esses dados são fornecidos de acordo com a Política de dados do usuário do Google . Revise e cumpra a política. Não fazer isso pode resultar na suspensão do projeto ou da conta.

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

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.

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:
Um botão padrão com um 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 preenchido em azul:
Um botão padrão com um plano de fundo azul Um botão com um plano de fundo azul Um botão personalizado com fundo azul
filled_black O tema do botão cheio de preto:
Um botão padrão com um 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 deles.

Tamanho
large Um botão grande:
Um botão grande padrão 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 pequeno botão 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 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":
Um botão padrão chamado &quot;#39;Fazer login com o Google&#39; Um botão de ícone sem texto visível
signup_with O texto do botão é "Inscreva-se no Google":
Um botão padrão chamado &quot;#39;Inscrever-se com o Google&#39; Um botão de ícone sem texto visível
continue_with O texto do botão é "Continue with Google" (Continuar com o Google):
Um botão padrão chamado &quot;#39;Continuar com o Google&#39; Um botão de ícone sem texto visível
signin O texto do botão é "Fazer login":
Um botão padrão chamado &quot;#39;Fazer login&#39; Um botão de ícone sem texto visível

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.
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 for usado para o tipo de botão icon, ele será igual a circle.
Um botão padrão em forma 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 for usado para o tipo de botão standard, ele será igual a pill.
Um botão circular padrão Um botão de ícone circular Um botão circular circular
square Botão quadrado. Se for usado para o tipo de botão standard, ele será igual a rectangular.
Um botão quadrado padrão Um botão com ícone quadrado Um botão quadrado personalizado

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:
Um botão padrão com o logotipo G à esquerda
center Alinha o centro do logotipo do Google:
Um botão padrão com o logotipo G no centro

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": "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 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.