Riferimento all'API JavaScript per reCAPTCHA

L'API JavaScript reCAPTCHA fornisce i metodi e i parametri di configurazione che ti consentono di eseguire il rendering e gestire i widget reCAPTCHA sulle pagine web con una chiave di sito.

Metodi dell'API JavaScript reCAPTCHA

Questa sezione descrive la sintassi e i parametri dei metodi dell'API JavaScript reCAPTCHA.

grecaptcha.enterprise.render

Esegue il rendering del container come widget reCAPTCHA e restituisce l'ID del widget appena creato.

Sintassi

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

Parametri del metodo

Parametro	Descrizione
container	L'elemento HTML per eseguire il rendering del widget reCAPTCHA. Specifica l'ID del contenitore (stringa) o l'elemento DOM stesso.
parameters	Un oggetto contenente parametri come coppie chiave=valore, ad esempio {"sitekey": "your_site_key", "action": "login", "theme": "dark"}. Per informazioni dettagliate su ogni parametro configurabile, consulta Attributi e parametri.

Valore restituito

Restituisce l'ID del widget appena creato.

grecaptcha.enterprise.reset

Reimposta il widget reCAPTCHA.

Sintassi

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

Parametri

Parametro	Descrizione
widget_id	Facoltativo. ID widget restituito da grecaptcha.enterprise.render(). Se non specificato, il valore predefinito è l'ID del primo widget creato.

Valore restituito

Non restituisce un valore.

grecaptcha.enterprise.execute

Richiama la verifica reCAPTCHA in modo programmatico.

Sintassi

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

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

Parametri

Parametro	Descrizione
widget_id	Facoltativo. ID widget restituito da grecaptcha.enterprise.render(). Se non specificato, il valore predefinito è l'ID del primo widget creato. Nota: da utilizzare con le chiavi sito con casella di controllo.
sitekey	Specifica la chiave di sito reCAPTCHA da proteggere. Nota: da utilizzare con le chiavi di sito basate sul punteggio.
action	Un oggetto con una singola coppia chiave=valore, in cui il valore della chiave action specifica il nome dell'azione associata all'elemento protetto. Nota: da utilizzare con le chiavi di sito basate sul punteggio. Ad esempio: {"action": "action_name"}

Valore restituito

In caso di esito positivo, restituisce un oggetto Promise contenente il token.

grecaptcha.enterprise.ready

Esegue la funzione quando viene caricata la libreria JavaScript reCAPTCHA.

Sintassi

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

Parametri

Parametro	Descrizione
callback	La funzione da chiamare al termine del caricamento della libreria reCAPTCHA.

Valore restituito

Non restituisce un valore.

grecaptcha.enterprise.getResponse

Ottiene la risposta per il widget reCAPTCHA.

Sintassi

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

Parametri

Parametro	Descrizione
widget_id	Facoltativo. ID widget restituito da grecaptcha.enterprise.render(). Se non specificato, il valore predefinito è l'ID del primo widget creato.

Valore restituito

Recupera la risposta del widget reCAPTCHA. Può essere una stringa con il token creato da grecaptcha.enterprise.execute() o una stringa vuota se il token non è ancora stato creato.

Configurazione

Questa sezione descrive i parametri delle risorse JavaScript e i parametri utilizzati da grecaptcha.enterprise.render() e gli attributi del widget g-recaptcha.

Parametri della risorsa JavaScript (enterprise.js)

La tabella seguente elenca i parametri della risorsa JavaScript (enterprise.js) che devi includere quando utilizzi reCAPTCHA.

Per ulteriori informazioni sull'utilizzo di questi parametri, consulta gli esempi in Rendering del widget reCAPTCHA sul frontend.

Parametro	Valore	Descrizione
onload	callback	Facoltativo. Il nome della funzione di callback da eseguire dopo il caricamento di tutte le dipendenze.
render	onload	Facoltativo, valore predefinito. Visualizza il widget nel primo tag g-recaptcha che trova. Nota: da utilizzare con le chiavi sito con casella di controllo.
	explicit	Facoltativo. Non esegue automaticamente il rendering del widget. Devi chiamare grecaptcha.enterprise.render() per eseguirne il rendering in modo programmatico. Nota: da utilizzare con le chiavi sito con casella di controllo.
	siteKey	Se utilizzato con chiavi di sito basate sul punteggio, questo parametro non è facoltativo. Il valore siteKey specifica la chiave di sito basata sul punteggio associata. Nota: da utilizzare solo con chiavi di sito basate sul punteggio; se utilizzato con chiavi di sito con casella di controllo, lo script non verrà caricato.
hl	Consulta i codici lingua.	Facoltativo. Forza il rendering del widget in una lingua specifica. Rileva automaticamente la lingua dell'utente se non specificata.

Attributi del tag g-recaptcha e parametri grecaptcha.enterprise.render()

La tabella seguente elenca gli attributi del tag g-recaptcha e i parametri grecaptcha.enterprise.render() corrispondenti.

Attributo del tag g-recaptcha	Parametro grecaptcha.enterprise.render()	Valori consentiti	Predefinito	Descrizione
data-sitekey	sitekey			Chiave reCAPTCHA.
data-badge	badge	bottomright, bottomleft, inline	bottomright	Facoltativo. Riposiziona il badge reCAPTCHA. inline ti consente di posizionarlo con CSS.
data-action	action			Facoltativo. Stringa che descrive l'azione corrente.
data-theme	theme	dark, light	light	Facoltativo. Il tema cromatico del widget.
data-size	size	compact, normal	normal	Facoltativo. Le dimensioni del widget.
data-tabindex	tabindex	Numero intero	0	Facoltativo. Il tabindex del widget e della verifica. Se altri elementi della pagina utilizzano tabindex, questo deve essere impostato in modo da semplificare la navigazione dell'utente.
data-callback	callback	Stringa	N/D	Facoltativo. Il nome della funzione di callback, eseguita quando l'utente invia una risposta corretta. Il token g-recaptcha-response viene passato al callback.
data-expired-callback	expired-callback	Stringa	N/D	Facoltativo. Il nome della funzione di callback, eseguita quando la risposta reCAPTCHA scade e l'utente deve eseguire nuovamente la verifica.
data-error-callback	error-callback	Stringa	N/D	Facoltativo. Il nome della funzione di callback, eseguita quando reCAPTCHA rileva un errore (di solito di connettività di rete) e non può continuare finché la connettività non viene ripristinata. Il callback non riceve argomenti contenenti dettagli sugli errori. Se specifichi una funzione qui, sei responsabile di informare l'utente che deve riprovare.