Riferimento all'API JavaScript per reCAPTCHA

Questa pagina descrive i metodi dell'API JavaScript di reCAPTCHA e i relativi parametri di configurazione che puoi utilizzare per eseguire il rendering delle pagine web con una chiave reCAPTCHA (chiave di sito).

Metodi dell'API JavaScript reCAPTCHA

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

grecaptcha.enterprise.render

Esegue il rendering del contenitore 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 i parametri sotto forma di coppie chiave=valore, ad esempio {"sitekey": "your_site_key", "action": "login", "theme": "dark"}. Consulta Attributi e parametri per informazioni dettagliate su ciascun parametro configurabile.

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 in modo programmatico la verifica reCAPTCHA.

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, viene utilizzato per impostazione predefinita l'ID del primo widget creato. Nota:da utilizzare con le chiavi dei siti delle caselle di controllo.
sitekey	Specifica la chiave di sito reCAPTCHA da proteggere. Nota:da utilizzare con le chiavi del sito basate su punteggi.
action	Un oggetto con una singola coppia chiave=valore, in cui il valore per la chiave action specifica il nome dell'azione associata all'elemento protetto. Nota:da utilizzare con le chiavi del sito basate su punteggi. 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 al caricamento della libreria JavaScript di 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

Recupera 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 viene specificato, viene utilizzato per impostazione predefinita 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)

Nella tabella seguente sono elencati 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	Valore predefinito facoltativo. Esegue il rendering del widget nel primo tag g-recaptcha trovato. Nota:da utilizzare con le chiavi dei siti delle caselle di controllo.
	explicit	Facoltativo. Non esegue il rendering del widget automaticamente. Devi chiamare grecaptcha.enterprise.render() per visualizzarlo in modo programmatico. Nota: da utilizzare con le chiavi dei siti delle caselle di controllo.
	siteKey	Se utilizzato con le chiavi del sito basate su punteggi, questo parametro non è facoltativo. Il valore siteKey specifica la chiave del 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 relativi parametrigrecaptcha.enterprise.render().

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 a colori del widget.
data-size	size	compact, normal	normal	Facoltativo. Le dimensioni del widget.
data-tabindex	tabindex	Numero intero	0	Facoltativo. L'indice tabulazione del widget e della sfida. Se altri elementi nella pagina utilizzano tabindex, questo deve essere impostato per 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 tuo 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 relativo alla connettività di rete) e non può continuare fino al ripristino della connettività. Il callback non riceve alcun parametro contenente i dettagli dell'errore. Se specifichi una funzione qui, è tua responsabilità informare l'utente che deve riprovare.