La API de JavaScript de reCAPTCHA proporciona los métodos y los parámetros de configuración que te permiten renderizar y administrar widgets de reCAPTCHA en páginas web con una clave de sitio.
Métodos de la API de JavaScript de reCAPTCHA
En esta sección, se describen 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): numberParámetros de método
| Parámetro | Descripción |
|---|---|
| container | El elemento HTML para renderizar el widget reCAPTCHA. Especifica el ID del contenedor (cadena) o el elemento del DOM en sí. |
| parameters |
Es un objeto que contiene parámetros como pares clave=valor, por ejemplo,
Consulta Atributos y parámetros para obtener detalles sobre cada parámetro configurable. |
Valor que se muestra
Devuelve el ID del widget recién creado.
grecaptcha.enterprise.reset
Restablece el widget de reCAPTCHA.
Sintaxis
grecaptcha.enterprise.reset(widget_id: number): voidParámetros
| Parámetro | Descripción |
|---|---|
| widget_id | Es opcional. Es el ID del widget que se devuelve desde grecaptcha.enterprise.render(). Si no se especifica, se establece de forma predeterminada en el ID del primer widget que se creó.
|
Valor que se muestra
No muestra un valor.
grecaptcha.enterprise.execute
Invoca de manera programática la verificación de reCAPTCHA.
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 | Es opcional. Es el ID del widget que se devuelve desde grecaptcha.enterprise.render().
Si no se especifica, se establece de forma predeterminada en el ID del primer widget que se creó. |
| sitekey |
Especifica la clave de sitio de reCAPTCHA que se protegerá. |
| action | Es 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.
Por ejemplo: |
Valor que se muestra
Si se ejecuta de forma correcta, 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): voidParámetros
| Parámetro | Descripción |
|---|---|
| callback | Es la función a la que se debe llamar cuando la biblioteca de reCAPTCHA termina de cargarse. |
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): stringParámetros
| Parámetro | Descripción |
|---|---|
| widget_id | Es opcional. Es el ID del widget que se devuelve desde grecaptcha.enterprise.render(). Si
no se especifica, se establece de forma predeterminada en 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 creado por 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, los parámetros
que usa grecaptcha.enterprise.render() y los atributos del
widget de g-recaptcha.
Parámetros de recursos JavaScript (enterprise.js)
En la siguiente tabla, se enumeran 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 Renderiza el widget de reCAPTCHA en el frontend.
| Parámetro | Valor | Descripción |
|---|---|---|
onload |
callback | Es opcional. Es el nombre de la función de devolución de llamada que se ejecutará después de que se hayan cargado todas las dependencias. |
render
|
onload |
Es opcional y es el valor predeterminado. Renderiza el widget en la primera etiqueta |
explicit
|
Es opcional. No renderiza el widget automáticamente. Debes llamar a |
|
| 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. |
|
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 de 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 |
Es opcional. Cambiar la posición de la insignia de reCAPTCHA inline te permite posicionarlo con CSS. |
data-action |
action |
Es opcional. Secuencia de comandos que describe la acción actual. | ||
data-theme |
theme |
dark, light |
light |
Es opcional. El tema de color del widget. |
data-size |
size |
compact, normal |
normal |
Es opcional. El tamaño del widget. |
data-tabindex |
tabindex |
Número 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 | Es 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 | Es 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 | Es 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. |