Referência da API JavaScript para reCAPTCHA

Esta página descreve os métodos da API reCAPTCHA JavaScript e os parâmetros de configuração que podem ser usados para renderizar as páginas da Web com uma chave reCAPTCHA (chave de site).

Métodos da API JavaScript do reCAPTCHA

Esta seção descreve a sintaxe e os parâmetros dos métodos da API reCAPTCHA JavaScript.

grecaptcha.enterprise.render

Renderiza o contêiner como um widget reCAPTCHA e retorna o ID do widget recém- criado.

Sintaxe

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

Parâmetros de método

Parâmetro	Descrição
container	O elemento HTML para renderizar o widget reCAPTCHA. Especifique o ID do contêiner (string) ou o próprio elemento DOM.
parameters	Um objeto que contém parâmetros como pares de chave-valor, por exemplo, {"sitekey": "your_site_key", "action": "login", "theme": "dark"}. Consulte Atributos e parâmetros para detalhes sobre cada parâmetro configurável.

Valor de retorno

Retorna o ID do widget recém-criado.

grecaptcha.enterprise.reset

Redefine o widget reCAPTCHA.

Sintaxe

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

Parâmetros

Parâmetro	Descrição
widget_id	Opcional. ID do widget retornado de grecaptcha.enterprise.render(). Se não for especificado, o padrão será o ID do primeiro widget criado.

Valor de retorno

Não retorna um valor.

grecaptcha.enterprise.execute

Invoca programaticamente a verificação reCAPTCHA.

Sintaxe

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

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

Parâmetros

Parâmetro	Descrição
widget_id	Opcional. ID do widget retornado de grecaptcha.enterprise.render(). Se não for especificado, o padrão será o ID do primeiro widget que foi criado. Observação:para uso com chaves de site com caixa de seleção.
sitekey	Especifique a chave de site do reCAPTCHA que será protegida. Observação:para uso com chaves de sites baseadas em pontuação.
action	Um objeto com um único par de chave-valor, em que o valor da chave action especifica o nome da ação associada ao elemento protegido. Observação:para uso com chaves de sites baseadas em pontuação. Por exemplo: {"action": "action_name"}

Valor de retorno

Se for bem-sucedido, ele retornará um objeto Promise contendo o token.

grecaptcha.enterprise.ready

Executa a função quando a biblioteca JavaScript do reCAPTCHA é carregada.

Sintaxe

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

Parâmetros

Parâmetro	Descrição
callback	A função a ser chamada quando a biblioteca reCAPTCHA terminar de carregar.

Valor de retorno

Não retorna um valor.

grecaptcha.enterprise.getResponse

Obtém a resposta para o widget reCAPTCHA.

Sintaxe

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

Parâmetros

Parâmetro	Descrição
widget_id	Opcional. ID do widget retornado de grecaptcha.enterprise.render(). Se não for especificado, o padrão será o ID do primeiro widget criado.

Valor de retorno

Recebe a resposta do widget reCAPTCHA. Pode ser uma string com o token criado por grecaptcha.enterprise.execute() ou uma string vazia se o token ainda não foi criado.

Configuração

Esta seção descreve os parâmetros de recurso JavaScript e os parâmetros usados por grecaptcha.enterprise.render() e os atributos do widget g-recaptcha.

Parâmetros do recurso JavaScript (enterprise.js)

A tabela a seguir lista os parâmetros do recurso JavaScript (enterprise.js) que você precisa incluir ao usar o reCAPTCHA.

Para mais informações sobre como usar esses parâmetros, consulte os exemplos em Como renderizar o widget reCAPTCHA no front-end.

Parâmetro	Valor	Descrição
onload	callback	Opcional. O nome da sua função de callback a ser executada depois que todas as dependências forem carregadas.
render	onload	Valor opcional padrão. Renderiza o widget na primeira tag g-recaptcha encontrada. Observação:para uso com chaves de site com caixa de seleção.
	explicit	Opcional. Não renderiza o widget automaticamente. É necessário chamar grecaptcha.enterprise.render() para renderizá-lo de forma programática. Observação:para uso com chaves de site com caixa de seleção.
	siteKey	Quando usado com chaves de site com base na pontuação, esse parâmetro não é opcional. O valor siteKey especifica a chave do site com base na pontuação associada. Observação:para uso apenas com chaves de site baseadas em pontuação. Se usado com chaves de site com caixa de seleção, o script não será carregado.
hl	Veja códigos de linguagem	Opcional. Força o widget a renderizar em um idioma específico. Detecta automaticamente o idioma do usuário se não for especificado.

Atributos da tag g-recaptcha e parâmetros grecaptcha.enterprise.render()

A tabela a seguir lista os atributos da tag g-recaptcha e os parâmetros grecaptcha.enterprise.render() correspondentes.

Atributo de tag g-recaptcha	Parâmetro grecaptcha.enterprise.render()	Valores permitidos	Padrão	Descrição
data-sitekey	sitekey			Chave reCAPTCHA.
data-badge	badge	bottomright, bottomleft, inline	bottomright	Opcional. Posicione o selo reCAPTCHA novamente. inline permite posicioná-lo com CSS.
data-action	action			Opcional. String que descreve a ação atual.
data-theme	theme	dark, light	light	Opcional. O tema de cores do widget.
data-size	size	compact, normal	normal	Opcional. O tamanho do widget.
data-tabindex	tabindex	Número inteiro	0	Opcional. O índice de tabulação do widget e desafio. Se outros elementos da sua página usarem tabindex, ele deverá ser definido para facilitar a navegação do usuário.
data-callback	callback	String	N/A	Opcional. O nome da sua função de callback, executada quando o usuário envia uma resposta bem-sucedida. O token g-recaptcha-response é passado para seu callback.
data-expired-callback	expired-callback	String	N/A	Opcional. O nome da sua função de callback, executada quando a resposta reCAPTCHA expira e o usuário precisa verificar novamente.
data-error-callback	error-callback	String	N/A	Opcional. O nome da sua função de callback, executada quando o reCAPTCHA encontra um erro (geralmente conectividade de rede) e não pode continuar até que a conectividade seja restaurada. O callback não recebe argumentos que contenham detalhes do erro. Se você especificar uma função aqui, será responsável por informar o usuário que ele deve tentar novamente.