Referencia de la API de JavaScript de reCAPTCHA

En esta página se describen los métodos de la API de JavaScript de reCAPTCHA y sus parámetros de configuración, que puedes usar para renderizar las páginas web con una clave de reCAPTCHA (clave de sitio).

Métodos de la API de JavaScript de reCAPTCHA

En esta sección se describe la sintaxis y los parámetros de los métodos de la API de JavaScript de reCAPTCHA.

grecaptcha.enterprise.render

Renderiza el contenedor como un widget de reCAPTCHA y devuelve el ID del widget recién creado.

Sintaxis

grecaptcha.enterprise.render(container: string | HTMLelement, parameters: Object): number

Parámetros de método

Parámetro	Descripción
container	Elemento HTML para renderizar el widget reCAPTCHA. Especifica el ID del contenedor (cadena) o el elemento DOM.
parameters	Un objeto que contiene parámetros como pares clave=valor. Por ejemplo: {"sitekey": "your_site_key", "action": "login", "theme": "dark"}. Consulta Atributos y parámetros para obtener más información sobre cada parámetro configurable.

Valor devuelto

Devuelve el ID del widget recién creado.

grecaptcha.enterprise.reset

Restablece el widget de reCAPTCHA.

Sintaxis

grecaptcha.enterprise.reset(widget_id: number): void

Parámetros

Parámetro	Descripción
widget_id	Opcional. ID del widget devuelto por grecaptcha.enterprise.render(). Si no se especifica, se usa de forma predeterminada el ID del primer widget que se haya creado.

Valor devuelto

No devuelve ningún valor.

grecaptcha.enterprise.execute

Invoca la verificación reCAPTCHA de forma programática.

Sintaxis

grecaptcha.enterprise.execute(widget_id: number): Promise<string>

grecaptcha.enterprise.execute(sitekey: string, action: Object): Promise<string>

Parámetros

Parámetro	Descripción
widget_id	Opcional. ID del widget devuelto por grecaptcha.enterprise.render(). Si no se especifica, se utiliza de forma predeterminada el ID del primer widget que se haya creado. Nota: Para usar con claves de sitio de casilla.
sitekey	Especifica la clave de sitio de reCAPTCHA que quieres proteger. Nota: Para usar con claves de sitio basadas en puntuación.
action	Un objeto con un solo par clave-valor, donde el valor de la clave action especifica el nombre de la acción asociada al elemento protegido. Nota: Para usar con claves de sitio basadas en puntuación. Por ejemplo: {"action": "action_name"}

Valor devuelto

Si la acción se realiza correctamente, devuelve un objeto Promise que contiene el token.

grecaptcha.enterprise.ready

Ejecuta tu función cuando se carga la biblioteca de JavaScript de reCAPTCHA.

Sintaxis

grecaptcha.enterprise.ready(callback: function): void

Parámetros

Parámetro	Descripción
callback	Función a la que se llama cuando la biblioteca reCAPTCHA termina de cargarse.

Valor devuelto

No devuelve ningún valor.

grecaptcha.enterprise.getResponse

Obtiene la respuesta del widget reCAPTCHA.

Sintaxis

grecaptcha.enterprise.getResponse(widget_id: number): string

Parámetros

Parámetro	Descripción
widget_id	Opcional. ID del widget devuelto por grecaptcha.enterprise.render(). Si no se especifica, se usa de forma predeterminada el ID del primer widget que se haya creado.

Valor devuelto

Obtiene la respuesta del widget reCAPTCHA. Puede ser una cadena con el token creado por grecaptcha.enterprise.execute() o una cadena vacía si el token aún no se ha creado.

Configuración

En esta sección se describen los parámetros de recursos de JavaScript y los parámetros que usan grecaptcha.enterprise.render() y los atributos del widget g-recaptcha.

Parámetros de recursos de JavaScript (enterprise.js)

En la siguiente tabla se indican los parámetros del recurso de JavaScript (enterprise.js) que debes incluir al usar reCAPTCHA.

Para obtener más información sobre el uso de estos parámetros, consulta los ejemplos de Renderizar el widget de reCAPTCHA en el frontend.

Parámetro	Valor	Descripción
onload	callback	Opcional. El nombre de la función de retrollamada que se ejecutará después de que se hayan cargado todas las dependencias.
render	onload	Opcional, valor predeterminado. Coloca el widget en la primera etiqueta g-recaptcha que encuentre. Nota: Para usar con claves de sitio de casilla.
	explicit	Opcional. No renderiza el widget automáticamente. Tienes que llamar a grecaptcha.enterprise.render() para renderizarlo mediante programación. Nota: Para usar con claves de sitio de casilla.
	siteKey	Cuando se usa con claves de sitio basadas en puntuación, este parámetro no es opcional. El valor siteKey especifica la clave de sitio basada en la puntuación asociada. Nota: Solo se puede usar con claves de sitio basadas en puntuación. Si se usa con claves de sitio de casilla de verificación, la secuencia de comandos no se cargará.
hl	Consulta los códigos de idioma.	Opcional. Fuerza al widget a renderizarse en un idioma específico. Detecta automáticamente el idioma del usuario si no se especifica.

Atributos de la etiqueta g-recaptcha y parámetros de grecaptcha.enterprise.render()

En la siguiente tabla se enumeran los atributos de la etiqueta g-recaptcha y los parámetros grecaptcha.enterprise.render() correspondientes.

Atributo de etiqueta g-recaptcha	Parámetro grecaptcha.enterprise.render()	Valores permitidos	Predeterminado	Descripción
data-sitekey	sitekey			Clave de reCAPTCHA.
data-badge	badge	bottomright, bottomleft, inline	bottomright	Opcional. Cambiar la posición de la insignia de reCAPTCHA. inline te permite colocarlo con CSS.
data-action	action			Opcional. Cadena que describe la acción actual.
data-theme	theme	dark, light	light	Opcional. El tema de color del widget.
data-size	size	compact, normal	normal	Opcional. El tamaño del widget.
data-tabindex	tabindex	Entero	0	Opcional. El índice de tabulación del widget y del reto. Si otros elementos de tu página usan tabindex, debe configurarse para que los usuarios puedan navegar más fácilmente.
data-callback	callback	Cadena	N/A	Opcional. El nombre de la función de retrollamada que se ejecuta cuando el usuario envía una respuesta correcta. El token g-recaptcha-response se transfiere a tu retrollamada.
data-expired-callback	expired-callback	Cadena	N/A	Opcional. Nombre de la función de retrollamada que se ejecuta cuando caduca la respuesta de reCAPTCHA y el usuario tiene que volver a verificarla.
data-error-callback	error-callback	Cadena	N/A	Opcional. El nombre de la función de retrollamada que se ejecuta cuando reCAPTCHA detecta un error (normalmente, de conectividad de red) y no puede continuar hasta que se restaura la conectividad. La retrollamada no recibe ningún argumento que contenga detalles del error. Si especificas una función aquí, debes informar al usuario de que debe volver a intentarlo.