Riferimento 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 reCAPTCHA JavaScript

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

grecaptcha.enterprise.render

Visualizza il container come widget reCAPTCHA e restituisce l'ID della richiesta widget creato.

Sintassi

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

Parametri metodo

Parametro	Descrizione
container	L'elemento HTML per il rendering del widget reCAPTCHA. Specifica l'ID del contenitore (stringa) o l'elemento DOM stesso.
parameters	Un oggetto che contiene parametri come 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(). In caso contrario specificato, viene utilizzato per impostazione predefinita 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 di sito 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 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

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 e i parametri della risorsa JavaScript utilizzato 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 sono state caricate le dipendenze.
render	onload	Facoltativo, valore predefinito. Esegue il rendering del widget nel primo tag g-recaptcha trovato. Nota: da utilizzare con le chiavi di sito delle caselle di controllo.
	explicit	Facoltativo. Non esegue il rendering del widget automaticamente. Devi chiamare grecaptcha.enterprise.render() per eseguire il rendering in modo programmatico. Nota: da utilizzare con le chiavi dei siti delle caselle di controllo.
	siteKey	Se utilizzato con le chiavi dei siti basate su punteggi, 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	Vedi 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. Il tabindex del widget e della sfida. Se altri elementi nella pagina usa Tabindex, che deve essere impostato per rendere la navigazione utente è più facile.
data-callback	callback	Stringa	N/D	Facoltativo. Il nome della tua 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 argomenti contenenti dettagli dell'errore. Se specifichi una funzione qui, è tua responsabilità informare l'utente che deve riprovare.