Referencia de la API de HTML para Acceder con Google

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

En esta página de referencia, se describe la API de atributos de datos HTML de Acceder con Google. Puedes usar la API para mostrar el mensaje de One Tap o el botón Acceder con Google en tus páginas web.

Elemento con el ID “g_id_onload”

Puedes colocar los atributos de datos de Acceder con Google en cualquier elemento visible o invisible, como <div> y <span>. El único requisito es que el ID del elemento esté establecido en g_id_onload. No coloques este ID en varios elementos.

Atributos de datos

En la siguiente tabla, se enumeran los atributos de datos con sus descripciones:

Atributo
data-client_id El ID de cliente de tu aplicación
data-auto_prompt Muestra Google One Tap.
data-auto_select Habilita la selección automática en Google One Tap.
data-login_uri La URL de tu extremo de acceso
data-callback El nombre de la función del controlador del token de ID de JavaScript
data-native_login_uri La URL del extremo del controlador de credenciales de contraseñas
data-native_callback Nombre de la función del controlador de credenciales de contraseña de JavaScript
data-native_id_param El nombre del parámetro para el valor credential.id
data-native_password_param El nombre del parámetro para el valor credential.password
data-cancel_on_tap_outside Controla si se cancela el mensaje si el usuario hace clic fuera del mensaje.
data-prompt_parent_id El ID de DOM del elemento del contenedor del mensaje de One Tap
data-skip_prompt_cookie Omite One Tap si la cookie especificada no tiene un valor vacío.
data-nonce Una string aleatoria para los tokens de ID
data-context El título y las palabras del mensaje de One Tap
data-moment_callback El nombre de la función del objeto de escucha de notificaciones del estado de la IU
data-state_cookie_domain Si necesitas llamar a One Tap en el dominio superior y sus subdominios, pasa el dominio superior a este atributo para que se use una sola cookie compartida.
data-ux_mode Flujo de UX del botón de acceso con Google
data-allowed_parent_origin Los orígenes permitidos para incorporar iframe intermedio. Se ejecutará One Tap en el modo intermedio de iframe si se presenta este atributo.
data-intermediate_iframe_close_callback Anula el comportamiento predeterminado de iframe intermedio cuando los usuarios cierran One Tap de forma manual.
data-itp_support Habilita la UX actualizada de One Tap en navegadores ITP.

Tipos de atributos

Las siguientes secciones contienen detalles sobre cada tipo de atributo y un ejemplo.

ID del cliente de datos

Este atributo es el ID de cliente de tu app, que se encuentra y crea en Google Developers Console. Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
string Sí data-client_id="CLIENT_ID.apps.googleusercontent.com"

mensaje_automático

Este atributo determina si se debe mostrar One Tap o no. El valor predeterminado es true. No se mostrará el toque de Google One cuando este valor sea false. Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
boolean Opcional data-auto_prompt="true"

datos-automáticos de selección

Este atributo determina si se debe mostrar o no un token de ID automáticamente, sin ninguna interacción del usuario, si solo una sesión de Google aprobó tu app. El valor predeterminado es false. Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
boolean Opcional data-auto_select="true"

data-login_uri

Este atributo es el URI de tu extremo de acceso. Se puede omitir si la página actual es tu página de acceso, en cuyo caso la credencial se publica en esta página de forma predeterminada.

La respuesta de la credencial del token de ID se publica en tu extremo de acceso cuando no se define una función de devolución de llamada y el usuario hace clic en los botones Acceder con Google o One Tap, o se realiza el acceso automático.

Consulta la siguiente tabla para obtener más información:

Tipo Opcional Ejemplo
URL El valor predeterminado es el URI de la página actual o el valor que especifiques.
Se ignora cuando se configuran data-ux_mode="popup" y data-callback.		 data-login_uri="https://www.example.com/login"

Tu extremo de acceso debe controlar las solicitudes POST que contienen una clave credential con un valor de token de ID en el cuerpo.

La siguiente es una solicitud de ejemplo para tu extremo de acceso:

POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

credential=ID_TOKEN

data-callback

Este atributo es el nombre de la función de JavaScript que controla el token de ID que se muestra. Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
string Obligatorio si no se estableció data-login_uri data-callback="handleToken"

Se puede usar uno de los atributos data-login_uri y data-callback. Depende de las siguientes configuraciones de componentes y modo de UX:

  • El atributo data-login_uri es obligatorio para el modo de UX del botón de acceso con Google redirect, que ignora el atributo data-callback.

  • Se debe configurar uno de estos dos atributos para Google One Tap y el modo de UX del botón de Acceso con Google popup. Si se configuran ambas, el atributo data-callback tiene una prioridad más alta.

La API de HTML no admite las funciones de JavaScript dentro de un espacio de nombres. En su lugar, usa una función de JavaScript global sin un espacio de nombres. Por ejemplo, usa mylibCallback en lugar de mylib.callback.

data-native_login_uri

Este atributo es la URL del extremo del controlador de credenciales de contraseña. Si configuras los atributos data-native_login_uri o data-native_callback, la biblioteca de JavaScript recurre al administrador de credenciales nativo cuando no hay una sesión de Google. No se pueden configurar los atributos data-native_callback y data-native_login_uri. Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
string Opcional data-login_uri="https://www.example.com/password_login"

devolución de llamada de datos nativos

Este atributo es el nombre de la función de JavaScript que controla la credencial de la contraseña que muestra el administrador de credenciales nativo del navegador. Si configuras los atributos data-native_login_uri o data-native_callback, la biblioteca de JavaScript recurre al administrador de credenciales nativo cuando no hay una sesión de Google. No se pueden establecer data-native_callback ni data-native_login_uri. Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
string Opcional data-native_callback="handlePasswordCredential"

La API de HTML no admite las funciones de JavaScript dentro de un espacio de nombres. En su lugar, usa una función de JavaScript global sin un espacio de nombres. Por ejemplo, usa mylibCallback en lugar de mylib.callback.

id-nativo_datos

Cuando envías la credencial de contraseña al extremo del controlador de credenciales de contraseña, puedes especificar el nombre del parámetro para el campo credential.id. El nombre predeterminado es email. Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
URL Opcional data-native_id_param="user_id"

data-native_password_param

Cuando envías la credencial de contraseña al extremo del controlador de credenciales de contraseña, puedes especificar el nombre del parámetro para el valor credential.password. El nombre predeterminado es password. Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
URL Opcional data-native_password_param="pwd"

data-cancel_on_tap_outside

Este atributo establece si se debe cancelar la solicitud de One Tap si el usuario hace clic fuera del mensaje. El valor predeterminado es true. Para inhabilitarlo, configura el valor como false. Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
boolean Opcional data-cancel_on_tap_outside="false"

data-prompt_parent_id

Este atributo establece el ID del DOM del elemento contenedor. Si no se establece, se mostrará el mensaje de One Tap en la esquina superior derecha de la ventana. Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
string Opcional data-prompt_parent_id="parent_id"

Este atributo omite One Tap si la cookie especificada no tiene un valor vacío. Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
string Opcional data-skip_prompt_cookie="SID"

nonce de datos

Este atributo es una string aleatoria que usa el token de ID para evitar ataques de reproducción. Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
string Opcional data-nonce="biaqbm70g23"

La longitud del nonce se limita al tamaño máximo de JWT compatible con tu entorno, así como a las restricciones de tamaño de HTTP y del servidor individuales.

contexto de los datos

Este atributo cambia el texto del título y los mensajes que se muestran en el mensaje de One Tap. Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
string Opcional data-context="use"

En la siguiente tabla, se enumeran los contextos disponibles y sus descripciones:

Contexto
signin &Acceder con Google
signup &Registrarse en Google
use Uso con Google

datos-momento_devolución de llamada

Este atributo es el nombre de la función del objeto de escucha de las notificaciones de estado de la IU. Para obtener más información, consulta el tipo de datos PromptMomentNotification. Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
string Opcional data-moment_callback="logMomentNotification"

La API de HTML no admite las funciones de JavaScript dentro de un espacio de nombres. En su lugar, usa una función de JavaScript global sin un espacio de nombres. Por ejemplo, usa mylibCallback en lugar de mylib.callback.

Si necesitas mostrar One Tap en un dominio superior y sus subdominios, pasa el dominio superior a este atributo para que se use una sola cookie de estado compartido. Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
string Opcional data-state_cookie_domain="example.com"

modo-ux-data

Este atributo establece el flujo de UX que usa el botón Acceder con Google. El valor predeterminado es popup. Este atributo no tiene impacto en la UX de One Tap. Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
string Opcional data-ux_mode="redirect"

En la siguiente tabla, se enumeran los modos de UX disponibles y sus descripciones.

Modo de UX
popup Realiza el flujo de la UX de acceso en una ventana emergente.
redirect Realiza el flujo de la UX de acceso mediante un redireccionamiento de página completa.

data-allowed_parent_origin

Los orígenes permitidos para incorporar iframe intermedio. One Tap se ejecutará en el modo de iframe intermedio si este atributo se presenta. Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
string o arreglo de strings Opcional data-allowed_parent_origin="https://example.com"

En la siguiente tabla, se enumeran los tipos de valores admitidos y sus descripciones.

Tipos de valores
string Un solo URI de dominio. &https://example.com"
string array Una lista de URI de dominio separados por comas. &https://news.example.com,https://local.example.com&&hl=es-419;

Si el valor del atributo data-allowed_parent_origin no es válido, la inicialización de One Tap del modo iframe intermedio fallará y se detendrá.

También se admiten los prefijos comodín. Por ejemplo, "https://*.example.com" coincidirá con example.com y sus subdominios en todos los niveles (p. ej., news.example.com, login.news.example.com). Ten en cuenta lo siguiente cuando uses comodines:

  • Las strings de patrón no pueden estar compuestas solo por un comodín y un dominio de nivel superior. Por ejemplo, https://*.com y https://*.co.uk no son válidos. Como se indicó más arriba, "https://*.example.com" coincidirá con example.com y sus subdominios. También puede usar una lista separada por comas para representar 2 dominios diferentes. Por ejemplo, "https://example1.com,https://*.example2.com" coincidirá con los dominios example1.com, example2.com y subdominios de example2.com.
  • Los dominios con comodines deben comenzar con un esquema https:// seguro. "*.example.com" se considerará no válido.

data-intermediate_iframe_close_callback

Anula el comportamiento predeterminado de iframe intermedio cuando los usuarios cierran manualmente One Tap presionando el botón 'X' en la IU de One Tap. El comportamiento predeterminado es quitar el iframe intermedio del DOM de inmediato.

El campo data-intermediate_iframe_close_callback solo se aplica en el modo iframe intermedio. Además, solo afecta al iframe intermedio, en lugar del iframe de One Tap. Se quita la IU de One Tap antes de invocar la devolución de llamada.

Tipo Obligatorio Ejemplo
función Opcional data-intermediate_iframe_close_callback="logBeforeClose"

La API de HTML no admite las funciones de JavaScript dentro de un espacio de nombres. En su lugar, usa una función de JavaScript global sin un espacio de nombres. Por ejemplo, usa mylibCallback en lugar de mylib.callback.

data-itp_support

Este campo determina si se debe habilitar la UX mejorada de One Tap en los navegadores compatibles con la Prevención de seguimiento inteligente (ITP). El valor predeterminado es false. Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
boolean Opcional data-itp_support="true"

Elemento con clase &g

Si agregas g_id_signin a un atributo class de un elemento, se mostrará como un botón Acceder con Google.

Puedes procesar varios botones de Acceder con Google en la misma página. Cada botón puede tener su propia configuración visual. La configuración se define según los siguientes atributos de datos.

Atributos de datos visuales

En la siguiente tabla, se enumeran los atributos de datos visuales y sus descripciones:

Atributo
data-type El tipo de botón: ícono o botón estándar.
data-theme El tema del botón Por ejemplo, relleno_azul o relleno_negro.
data-size El tamaño del botón. Por ejemplo, pequeño o grande.
data-text El texto del botón. Por ejemplo, "Acceder con Google" o "Registrarse con Google"
data-shape La forma del botón. Por ejemplo, rectangular o circular.
data-logo_alignment Alineación del logotipo de Google: izquierda o central.
data-width El ancho del botón, en píxeles.
data-locale El texto del botón se procesa en el idioma configurado en este atributo.

Tipos de atributos

Las siguientes secciones contienen detalles sobre cada tipo de atributo y un ejemplo.

tipo de datos

Corresponde al tipo de botón. El valor predeterminado es standard. Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
string Sí data-type="icon"

En la siguiente tabla, se enumeran los tipos de botones disponibles y sus descripciones:

Tipo
standard Un botón con texto o información personalizada:
icon Un botón de ícono sin texto:

data-theme

El tema del botón El valor predeterminado es outline. Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
string Opcional data-theme="filled_blue"

En la siguiente tabla, se enumeran los temas disponibles y sus descripciones:

Tema
outline El tema del botón estándar:
Un botón estándar con un fondo blanco Un botón de ícono con un fondo blanco Un botón personalizado con un fondo blanco
filled_blue El tema del botón con relleno azul:
Un botón estándar con un fondo azul Un botón de ícono con un fondo azul Un botón personalizado con un fondo azul
filled_black El tema del botón con relleno negro:
Un botón estándar con fondo negro Botón de ícono con fondo negro Un botón personalizado con un fondo negro

data-size

El tamaño del botón. El valor predeterminado es large. Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
string Opcional data-size="small"

En la siguiente tabla, se indican los tamaños de botones disponibles y sus descripciones.

Size
large Un botón grande:
Un botón estándar grandeBotón de ícono grandeUn botón grande y personalizado
medium Un botón de tamaño mediano:
Un botón estándar mediano Botón con un ícono mediano
small Un botón pequeño:
Un botón pequeño Un pequeño ícono de botón

texto-datos

El texto del botón. El valor predeterminado es signin_with. No hay diferencias visuales en el texto de los botones de íconos que tienen diferentes atributos data-text. La única excepción ocurre cuando se lee el texto para mejorar la accesibilidad a la pantalla.

Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
string Opcional data-text="signup_with"

En la siguiente tabla, se incluyen los textos de botones disponibles y sus descripciones:

Texto
signin_with El texto del botón es "Acceder con Google":
Un botón estándar etiquetado como &#39;Acceder con Google&#39;Un botón de ícono sin texto visible
signup_with El texto del botón es “Regístrate con Google”:
Un botón estándar etiquetado como &quot;Registrarse con Google&quot; Un botón de ícono sin texto visible
continue_with El texto del botón es "Continuar con Google":
Un botón estándar etiquetado como &#39;Continuar con Google&#39; Un botón de ícono sin texto visible
signin El texto del botón es "Acceder":
Un botón estándar etiquetado como &#39;Acceder&#39; Un botón de ícono sin texto visible

forma de los datos

La forma del botón. El valor predeterminado es rectangular. Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
string Opcional data-shape="rectangular"

En la siguiente tabla, se enumeran las formas de botones disponibles y sus descripciones:

Forma
rectangular El botón de forma rectangular. Si se usa para el tipo de botón icon, es lo mismo que square.
Un botón rectangular estándar Un botón de ícono rectangular Un botón rectangular personalizado
pill El botón con forma de píldora. Si se usa para el tipo de botón icon, es lo mismo que circle.
Un botón estándar con forma de píldora Un botón de ícono con forma de píldora Un botón personalizado con forma de píldora
circle El botón con forma de círculo. Si se usa para el tipo de botón standard, es lo mismo que pill.
Un botón estándar circular Un botón de ícono circular Un botón circular personalizado
square El botón con forma cuadrada Si se usa para el tipo de botón standard, es lo mismo que rectangular.
Un botón estándar cuadrado Un botón de ícono cuadrado Un botón cuadrado personalizado

data-logo_alignment

La alineación del logotipo de Google El valor predeterminado es left. Este atributo solo se aplica al tipo de botón standard. Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
string Opcional data-logo_alignment="center"

En la siguiente tabla, se enumeran los alineamientos disponibles y sus descripciones:

alineación del logotipo
left Alinea a la izquierda el logotipo de Google:
Un botón estándar con el logotipo de la G a la izquierda
center Centrar el logotipo de Google:
Un botón estándar con el logotipo de la G en el centro

ancho de datos

El ancho mínimo del botón (en píxeles). El ancho máximo disponible es de 400 píxeles.

Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
string Opcional data-width=400

configuración regional de datos

Configuración regional predeterminada del texto del botón. Si no se configura, se usa la configuración regional predeterminada del navegador o la preferencia del usuario de la sesión de Google. Por lo tanto, los diferentes usuarios pueden ver distintas versiones de los botones localizados y, posiblemente, con diferentes tamaños.

Consulta la siguiente tabla para obtener más información:

Tipo Obligatorio Ejemplo
string Opcional data-locale="zh_CN"

Integración del servidor

Los extremos del servidor deben controlar las siguientes solicitudes HTTP POST.

El extremo del controlador del token de ID

El extremo del controlador de token de ID procesa el token de ID. Según el estado de la cuenta correspondiente, puedes hacer que el usuario acceda y dirigirlo a una página de registro o dirigirlo a una página de vinculación de cuenta para obtener información adicional.

La solicitud HTTP POST contiene la siguiente información:

Formato Nombre Descripción
Cookie g_csrf_token Una string aleatoria que cambia con cada solicitud al extremo del controlador.
Parámetro de solicitud g_csrf_token Una string que es igual al valor de cookie anterior, g_csrf_token.
Parámetro de solicitud credential El token de ID que emite Google.
Parámetro de solicitud select_by Cómo se selecciona la credencial

Cuando se decodifica, el token de ID luce como el siguiente ejemplo:

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

En la siguiente tabla, se enumeran los posibles valores del campo select_by. El tipo de botón que se usa junto con el estado de la sesión y el consentimiento se usan para establecer el valor

  • El usuario presionó el botón de One Tap o Acceder con Google, o usó el proceso de acceso automático sin contacto.

  • Se encontró una sesión existente o el usuario seleccionó una Cuenta de Google y accedió a ella para establecer una nueva.

  • Antes de compartir las credenciales del token de ID con tu app, el usuario

    • Presiona el botón Confirmar para otorgar su consentimiento y compartir credenciales.
    • ya habían otorgado consentimiento y usaron una cuenta para elegir una Cuenta de Google.

El valor de este campo se establece en uno de estos tipos:

Valor Descripción
auto Acceso automático de un usuario con una sesión existente que ya había otorgado consentimiento para compartir credenciales.
user Un usuario con una sesión existente que ya había otorgado consentimiento presionó el botón de One Tap 'Continue as' para compartir las credenciales.
user_1tap Un usuario con una sesión existente presionó el botón One Tap 'Continue as' para otorgar el consentimiento y compartir las credenciales. Solo se aplica a Chrome 75 y versiones posteriores.
user_2tap Un usuario sin una sesión existente presionó el botón One Tap 'Continue as' para seleccionar una cuenta y, luego, el botón Confirmar en una ventana emergente para otorgar su consentimiento y compartir las credenciales. Se aplica a navegadores que no se basan en Chromium.
btn Un usuario con una sesión existente que ya había otorgado consentimiento presionó el botón Acceder con Google y seleccionó una Cuenta de Google de 'Elegir una cuenta' para compartir las credenciales.
btn_confirm Un usuario con una sesión existente presionó el botón Acceder con Google y el botón Confirmar para otorgar el consentimiento y compartir las credenciales.
btn_add_session Un usuario sin una sesión existente que anteriormente otorgaba su consentimiento presionó el botón Acceder con Google para seleccionar una Cuenta de Google y compartir sus credenciales.
btn_confirm_add_session Primero, un usuario sin una sesión existente presionó el botón Acceder con Google para seleccionar una Cuenta de Google y, luego, el botón Confirmar para dar su consentimiento y compartir las credenciales.

Extremo del controlador de credenciales de contraseñas

El extremo del controlador de credenciales de contraseñas procesa las credenciales de contraseñas que recupera el administrador de credenciales nativo.

La solicitud HTTP POST contiene la siguiente información:

Formato Nombre Descripción
Cookie g_csrf_token Una string aleatoria que cambia con cada solicitud al extremo del controlador.
Parámetro de solicitud g_csrf_token Una string que es igual al valor de cookie anterior, g_csrf_token.
Parámetro de solicitud email Este token de ID que Google emite.
Parámetro de solicitud password Cómo se selecciona la credencial