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 UXredirect
, que ignora o atributodata-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 atributodata-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" |
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 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
.
estado-do_cookie_do_data
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
ehttps://*.co.uk
são inválidos. Conforme mencionado acima,"https://*.example.com"
corresponderá aexample.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íniosexample1.com
,example2.com
e subdomínios deexample2.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:
![]() ![]() ![]() |
filled_blue |
O tema do botão azul:
![]() ![]() ![]() |
filled_black |
O tema do botão 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:
![]() ![]() ![]() |
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 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":
![]() ![]() |
signup_with |
O texto do botão é "Assine com o Google":
![]() ![]() |
continue_with |
O texto do botão é "Continue with Google":
![]() ![]() |
signin |
O texto do botão é "Fazer login":
![]() ![]() |
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 .
![]() ![]() ![]() |
pill |
O botão em forma de pílula. Se usado para o tipo de botão icon ,
é o mesmo que circle .
![]() ![]() ![]() |
circle |
O botão em forma de círculo. Se usado para o tipo de botão standard , é o mesmo que pill .
![]() ![]() ![]() |
square |
O botão em formato quadrado. Se usado para o tipo de botão standard , é o mesmo que rectangular .
![]() ![]() ![]() |
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:
![]() |
center |
Alinhar o logotipo do Google ao 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. |