Documentation de référence sur l'API JavaScript pour reCAPTCHA

L'API JavaScript reCAPTCHA fournit les méthodes et les paramètres de configuration qui vous permettent d'afficher et de gérer les widgets reCAPTCHA sur les pages Web à l'aide d'une clé de site.

Méthodes de l'API JavaScript reCAPTCHA

Cette section décrit la syntaxe et les paramètres des méthodes de l'API JavaScript reCAPTCHA.

grecaptcha.enterprise.render

Affiche le conteneur en tant que widget reCAPTCHA et renvoie l'ID du widget nouvellement créé.

Syntaxe

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

Paramètres de la méthode

Paramètre	Description
container	Élément HTML permettant d'afficher le widget reCAPTCHA. Spécifiez l'ID du conteneur (chaîne) ou l'élément DOM lui-même.
parameters	Objet contenant des paramètres sous forme de paires clé=valeur, par exemple {"sitekey": "your_site_key", "action": "login", "theme": "dark"}. Pour en savoir plus sur chaque paramètre configurable, consultez Attributs et paramètres.

Valeur renvoyée

Renvoie l'ID du widget que vous venez de créer.

grecaptcha.enterprise.reset

Réinitialise le widget reCAPTCHA.

Syntaxe

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

Paramètres

Paramètre	Description
widget_id	Facultatif. ID du widget renvoyé par grecaptcha.enterprise.render(). Si aucune valeur n'est spécifiée, l'ID du premier widget créé est utilisé par défaut.

Valeur renvoyée

Ne renvoie aucune valeur.

grecaptcha.enterprise.execute

Appelle la validation reCAPTCHA de manière programmatique.

Syntaxe

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

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

Paramètres

Paramètre	Description
widget_id	Facultatif. ID du widget renvoyé par grecaptcha.enterprise.render(). Si aucune valeur n'est spécifiée, l'ID du premier widget créé est utilisé par défaut. Remarque : À utiliser avec les clés de site de type case à cocher.
sitekey	Spécifiez la clé de site reCAPTCHA à protéger. Remarque : À utiliser avec les clés de site basées sur un score.
action	Objet avec une seule paire clé=valeur, où la valeur de la clé action spécifie le nom de l'action associée à l'élément protégé. Remarque : À utiliser avec les clés de site basées sur un score. Par exemple : {"action": "action_name"}

Valeur renvoyée

Si l'opération réussit, renvoie un objet Promise contenant le jeton.

grecaptcha.enterprise.ready

Exécute votre fonction lorsque la bibliothèque JavaScript reCAPTCHA se charge.

Syntaxe

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

Paramètres

Paramètre	Description
callback	Fonction à appeler lorsque le chargement de la bibliothèque reCAPTCHA est terminé.

Valeur renvoyée

Ne renvoie aucune valeur.

grecaptcha.enterprise.getResponse

Récupère la réponse du widget reCAPTCHA.

Syntaxe

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

Paramètres

Paramètre	Description
widget_id	Facultatif. ID du widget renvoyé par grecaptcha.enterprise.render(). Si aucune valeur n'est spécifiée, l'ID du premier widget créé est utilisé par défaut.

Valeur renvoyée

Récupère la réponse du widget reCAPTCHA. Il peut s'agir d'une chaîne avec le jeton créé par grecaptcha.enterprise.execute() ou d'une chaîne vide si le jeton n'a pas encore été créé.

Configuration

Cette section décrit les paramètres de la ressource JavaScript, les paramètres utilisés par grecaptcha.enterprise.render() et les attributs du widget g-recaptcha.

Paramètres de ressource JavaScript (enterprise.js)

Le tableau suivant liste les paramètres de la ressource JavaScript (enterprise.js) que vous devez inclure lorsque vous utilisez reCAPTCHA.

Pour en savoir plus sur l'utilisation de ces paramètres, consultez les exemples de la section Afficher le widget reCAPTCHA sur l'interface.

Paramètre	Valeur	Description
onload	callback	Facultatif. Nom de votre fonction de rappel à exécuter une fois toutes les dépendances chargées.
render	onload	Facultatif, valeur par défaut. Déclenche l'affichage du widget dans la première balise g-recaptcha qu'il trouve. Remarque : À utiliser avec les clés de site de type case à cocher.
	explicit	Facultatif. Ne s'affiche pas automatiquement. Vous devez appeler grecaptcha.enterprise.render() pour l'afficher de manière programmatique. Remarque : À utiliser avec les clés de site de case à cocher.
	siteKey	Lorsqu'il est utilisé avec des clés de site basées sur un score, ce paramètre est obligatoire. La valeur siteKey spécifie la clé de site basée sur un score associée. Remarque : À utiliser uniquement avec les clés de site basées sur un score. Si vous l'utilisez avec des clés de site de type case à cocher, le script ne se chargera pas.
hl	Voir les codes de langue	Facultatif. Force l'affichage du widget dans une langue spécifique. Si aucune valeur n'est spécifiée, détecte automatiquement la langue de l'utilisateur.

Attributs de tag g-recaptcha et paramètres grecaptcha.enterprise.render()

Le tableau suivant répertorie les attributs de tag g-recaptcha et les paramètres grecaptcha.enterprise.render() correspondants.

Attribut de tag g-recaptcha	Paramètre grecaptcha.enterprise.render()	Valeurs autorisées	Par défaut	Description
data-sitekey	sitekey			Clé reCAPTCHA.
data-badge	badge	bottomright, bottomleft, inline	bottomright	Facultatif. Repositionnez le badge reCAPTCHA. inline vous permet de le positionner avec CSS.
data-action	action			Facultatif. Chaîne décrivant l'action actuelle.
data-theme	theme	dark, light	light	Facultatif. Thème de couleur du widget.
data-size	size	compact, normal	normal	Facultatif. Taille du widget.
data-tabindex	tabindex	Integer	0	Facultatif. Tabindex du widget et du challenge. Si d'autres éléments de votre page utilisent des tabindex, il doit être défini pour faciliter la navigation de l'utilisateur.
data-callback	callback	Chaîne	N/A	Facultatif. Nom de votre fonction de rappel exécutée lorsque l'utilisateur envoie une réponse réussie. Le jeton g-recaptcha-response est transmis à votre rappel.
data-expired-callback	expired-callback	Chaîne	N/A	Facultatif. Nom de votre fonction de rappel exécutée lorsque la réponse reCAPTCHA expire et que l'utilisateur doit à nouveau effectuer la validation.
data-error-callback	error-callback	Chaîne	N/A	Facultatif. Nom de votre fonction de rappel exécutée lorsque reCAPTCHA rencontre une erreur (généralement un problème de connectivité réseau) et ne peut pas poursuivre tant que la connectivité n'est pas rétablie. Le rappel ne reçoit aucun argument contenant des détails sur l'erreur. Si vous spécifiez une fonction ici, vous devez informer l'utilisateur qu'il doit réessayer.