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 los 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 se establezca 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 su extremo de acceso
data-callback 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ña
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 de él.
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 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 las notificaciones de estado de la IU del mensaje
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 usar una sola cookie compartida.
data-ux_mode Flujo de UX del botón Acceder con Google
data-allowed_parent_origin Los orígenes permitidos para incorporar el iframe intermedio. Si se muestra este atributo, se ejecutará One Tap en el modo de iframe intermedio.
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 el 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 se crea en Google Developers Console. Consulta la siguiente tabla para obtener más información:

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

solicitud-de-datos-automático

Este atributo determina si se muestra 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 Obligatoria Ejemplo
boolean Opcional data-auto_prompt="true"

datos-selección automática

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 Obligatoria Ejemplo
boolean Opcional data-auto_select="true"

datos-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 credencial del token de ID se publica en el extremo de acceso cuando no se define una función de devolución de llamada y un usuario hace clic en los botones Acceder con Google o One Tap, o se realiza la firma automática.

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 manejar 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 Obligatoria Ejemplo
string Es obligatorio si no se configura data-login_uri. data-callback="handleToken"

Se pueden 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 redirect del botón de Acceso con Google, que ignora el atributo data-callback.

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

Las funciones de JavaScript dentro de un espacio de nombres no son compatibles con la API de HTML. 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 el atributo data-native_login_uri o el atributo data-native_callback, la biblioteca de JavaScript recurre al administrador de credenciales nativo cuando no hay una sesión de Google. No puedes establecer los atributos data-native_callback ni data-native_login_uri. Consulta la siguiente tabla para obtener más información:

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

devolución de llamada nativa de datos

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

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

Las funciones de JavaScript dentro de un espacio de nombres no son compatibles con la API de HTML. 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_de_datos_nativo

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 Obligatoria 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 Obligatoria Ejemplo
URL Opcional data-native_password_param="pwd"

datos-cancelar_al_presionar_fuera

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, establece el valor en false. Consulta la siguiente tabla para obtener más información:

Tipo Obligatoria 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 está configurado, se muestra el mensaje de One Tap en la esquina superior derecha de la ventana. Consulta la siguiente tabla para obtener más información:

Tipo Obligatoria 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 Obligatoria 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 repetición. Consulta la siguiente tabla para obtener más información:

Tipo Obligatoria 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 individual del navegador y del servidor HTTP.

contexto de 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 Obligatoria 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 con Google"
use "Usar con Google"

devolución de llamada de data-moment

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

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

Las funciones de JavaScript dentro de un espacio de nombres no son compatibles con la API de HTML. 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 Obligatoria 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 afecta la UX de One Tap. Consulta la siguiente tabla para obtener más información:

Tipo Obligatoria 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 UX de acceso en una ventana emergente.
redirect Realiza el flujo de UX de acceso mediante el redireccionamiento de página completa.

data-allowed_parent_origin

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

Tipo Obligatoria 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 valor
string Un URI de dominio único. "https://example.com"
string array Una lista de URI de dominios separados por comas. "https://noticias.example.com,https://local.example.com"

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 prefijos de 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 patrones 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 señaló anteriormente, "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 comodín deben comenzar con un esquema https:// seguro. "*.example.com" se considerará no válido.

datos-intermediate_iframe_close_callback

Anula el comportamiento predeterminado de iframe intermedio cuando los usuarios cierran One Tap de forma manual 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 intermedio de iframe. Y solo tiene impacto en el iframe intermedio, en lugar del iframe One Tap. Se quita la IU de One Tap antes de invocar la devolución de llamada.

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

Las funciones de JavaScript dentro de un espacio de nombres no son compatibles con la API de HTML. 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 Obligatoria Ejemplo
boolean Opcional data-itp_support="true"

Elemento con clase "g_id_signin"

Si agregas g_id_signin al atributo class de un elemento, este se procesará 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 mediante 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 establecido en este atributo.
data-click_listener Si se configura, se llamará a esta función cuando se haga clic en el botón Acceder con Google.

Tipos de atributos

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

tipo de datos

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

Tipo Obligatoria 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 Obligatoria Ejemplo
string Opcional data-theme="filled_blue"

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

Tema
outline El tema de botón estándar:
Un botón estándar con fondo blanco Botón de ícono con fondo blanco Un botón personalizado con un fondo blanco
filled_blue El tema de botón lleno de azul:
Un botón estándar con fondo azul Botón de ícono con fondo azul Un botón personalizado con un fondo azul
filled_black El tema de botón negro:
Un botón estándar con fondo negro Un botón de ícono con fondo negro Un botón personalizado con 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 Obligatoria Ejemplo
string Opcional data-size="small"

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

Tamaño
large Un botón grande:
Un botón estándar grande Botón de ícono grande Un botón grande y personalizado
medium Un botón mediano:
Un botón mediano estándar Botón de ícono mediano
small Botón pequeño:
Un botón pequeño Botón de ícono pequeño

datos-texto

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 es cuando se lee el texto para la accesibilidad de la pantalla.

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

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

La siguiente tabla enumera los textos de botón disponibles y sus descripciones:

Texto
signin_with El texto del botón es "Acceder con Google":
Un botón estándar con la etiqueta &quot;Acceder con Google&quot; Un botón de ícono sin texto visible
signup_with El texto del botón es "Registrarse 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 "Continue with Google":
Un botón estándar con la etiqueta &quot;Continuar con Google&quot; Un botón de ícono sin texto visible
signin El texto del botón es "Acceder":
Un botón estándar con la etiqueta “Acceder” Un botón de ícono sin texto visible

forma de datos

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

Tipo Obligatoria 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 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 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 Botón de ícono circular Un botón circular personalizado
square El botón cuadrado Si se usa para el tipo de botón standard, es lo mismo que rectangular.
Un botón estándar cuadrado Botón de ícono cuadrado Un botón cuadrado personalizado

datos-logo_alineación

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 Obligatoria Ejemplo
string Opcional data-logo_alignment="center"

En la siguiente tabla, se enumeran las alineaciones disponibles y sus descripciones:

alineación_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 Alinea el centro con 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 Obligatoria Ejemplo
string Opcional data-width=400

configuración regional de datos

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

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

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

click_listener

Puedes definir una función de JavaScript para que se llame cuando se haga clic en el botón Acceder con Google mediante el 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...")
  }

En el ejemplo anterior, el mensaje Acceder con el botón de Google... se registrará en la consola cuando se haga clic en el botón Acceder.

Integración del servidor

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

El extremo del controlador de tokens de ID

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

La solicitud POST HTTP 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 Google emite.
Parámetro de solicitud select_by Cómo se selecciona la credencial.

Cuando se decodifique, el token de ID se verá 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 valores posibles para el campo select_by. El tipo de botón que se usa junto con la sesión y el estado de consentimiento se utilizan para establecer el valor,

  • El usuario presionó el botón 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, haz lo siguiente:

    • presionar el botón Confirmar para otorgar su consentimiento a fin de compartir credenciales; o
    • habían otorgado su consentimiento con anterioridad y usaron Seleccionar 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 su consentimiento para compartir credenciales.
user Un usuario con una sesión existente que ya había otorgado su consentimiento presionó el botón de One Tap "Continuar como" para compartir credenciales.
user_1tap Un usuario con una sesión existente presionó el botón de One Tap "Continuar como" para otorgar el consentimiento y compartir las credenciales. Solo se aplica a Chrome v75 y versiones posteriores.
user_2tap Un usuario sin sesión existente presionó el botón “Continuar como” de One Tap para seleccionar una cuenta y, luego, presionó el botón Confirmar en una ventana emergente para otorgar el consentimiento y compartir las credenciales. Se aplica a navegadores que no están basados en Chromium.
btn Un usuario con una sesión existente que ya había otorgado su consentimiento presionaba el botón Acceder con Google y seleccionaba una Cuenta de Google en “Elegir una cuenta” para compartir las credenciales.
btn_confirm Un usuario con una sesión existente presionó el botón Acceder con Google y, luego, el botón Confirmar para otorgar el consentimiento y compartir las credenciales.
btn_add_session Un usuario sin sesión existente que ya había otorgado su consentimiento presionó el botón Acceder con Google para seleccionar una Cuenta de Google y compartir sus credenciales.
btn_confirm_add_session Un usuario que no tenía una sesión existente primero presionó el botón Acceder con Google para seleccionar una Cuenta de Google y, luego, presionó el botón Confirmar para compartir sus credenciales.

Extremo del controlador de credenciales de contraseña

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

La solicitud POST HTTP 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.