Referencia de la API de JavaScript para reCAPTCHA

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

Métodos de la API de reCAPTCHA para JavaScript

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

grecaptcha.enterprise.render

Representa el contenedor como un widget reCAPTCHA y muestra el ID del widget recién creado.

Sintaxis

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

Parámetros del método

Parámetro	Descripción
container	El elemento HTML para renderizar el widget reCAPTCHA. Especifica el ID del contenedor (cadena) o el elemento DOM mismo.
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 detalles sobre cada parámetro configurable.

Valor que se muestra

Muestra 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 que se muestra desde grecaptcha.enterprise.render(). Si no se especifica, el valor predeterminado es el ID del primer widget que se creó.

Valor que se muestra

No muestra un valor.

grecaptcha.enterprise.execute

Invoca la verificación de reCAPTCHA de manera 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 que se muestra desde grecaptcha.enterprise.render(). Si no se especifica, el valor predeterminado es el ID del primer widget que se creó. Nota: Para usar con claves de sitios de casillas de verificación.
sitekey	Especifica la clave del sitio de reCAPTCHA que se protegerá. Nota: Para usar con claves de sitio basadas en puntuaciones.
action	Un objeto con un solo par clave-valor, en el que el valor de la clave action especifica el nombre de la acción asociada con el elemento protegido. Nota: Para usar con claves de sitio basadas en puntuaciones. Por ejemplo: {"action": "action_name"}

Valor que se muestra

Si 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	Es la función a la que se debe llamar cuando finaliza la carga de la biblioteca de reCAPTCHA.

Valor que se muestra

No muestra un valor.

grecaptcha.enterprise.getResponse

Obtiene la respuesta para el widget de reCAPTCHA.

Sintaxis

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

Parámetros

Parámetro	Descripción
widget_id	Opcional. ID del widget que se muestra desde grecaptcha.enterprise.render(). Si no se especifica, el valor predeterminado es el ID del primer widget que se creó.

Valor que se muestra

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

Configuración

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

Parámetros de recursos JavaScript (enterprise.js)

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

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

Parámetro	Valor	Descripción
onload	callback	Opcional. El nombre de tu función de devolución de llamada que se ejecutará después de que se hayan cargado todas las dependencias.
render	onload	Valor predeterminado opcional. Renderiza el widget en la primera etiqueta g-recaptcha que encuentre. Nota: Para usar con claves de sitios de casillas de verificación.
	explicit	Opcional. No renderiza el widget automáticamente. Debes llamar a grecaptcha.enterprise.render() para renderizarlo de manera programática. Nota: Para usar con claves de sitios de casillas de verificación.
	siteKey	Cuando se usa con claves de sitios basadas en la puntuación, este parámetro no es opcional. El valor siteKey especifica la clave de sitio basada en la puntuación asociada. Nota: Se usa solo con claves de sitio basadas en puntuaciones. Si se usa con checkboxes de claves de sitio, no se cargará la secuencia de comandos.
hl	Consulta códigos de lenguajes.	Opcional. Obliga al widget a renderizarse en un lenguaje específico. Detecta automáticamente el lenguaje 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. Cambia la posición de la insignia de reCAPTCHA. inline te permite posicionarlo con CSS.
data-action	action			Opcional. Secuencia de comandos 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 tabindex del widget y el desafío. Si otros elementos en tu página usan tabindex, debe configurarse para facilitar la navegación del usuario.
data-callback	callback	String	N/A	Opcional. El nombre de tu función de devolución de llamada, ejecutada cuando el usuario envía una respuesta exitosa. El token g-recaptcha-response se pasa a tu devolución de llamada.
data-expired-callback	expired-callback	String	N/A	Opcional. El nombre de tu función de devolución de llamada, ejecutada cuando la respuesta reCAPTCHA caduca y el usuario necesita volver a verificar.
data-error-callback	error-callback	String	N/A	Opcional. El nombre de tu función de devolución de llamada, ejecutada cuando reCAPTCHA encuentra un error (generalmente conectividad de red) y no puede continuar hasta que se restablezca la conectividad. La devolución de llamada no recibe ningún argumento que contenga detalles del error. Si especificas una función aquí, eres responsable de informar al usuario que debe volver a intentarlo.