Configuration

Il existe deux façons de configurer hCaptcha. La première consiste à transmettre des paramètres de requête lors du chargement de la ressource JavaScript hCaptcha. Grâce à ces paramètres, vous pouvez spécifier une fonction de rappel personnalisée, différer le rendu ou imposer une localisation particulière.

Paramètre	Valeur	Description
chargement	<function name>	Facultatif. Nom de votre fonction de rappel personnalisée à appeler une fois l'API hCaptcha chargée. Doit être définie avant le chargement de l'API.
rendre	explicite	chargement
hl	<language code>	Optionnel. Force une localisation spécifique. Par défaut, hCaptcha détecte automatiquement les paramètres régionaux de l'utilisateur. Voir language codes. Peut également être utilisé via la méthode render.
recaptchacompat	sur | désactivé	Optionnel. Indique si le hook de compatibilité window.grecaptcha doit être inséré. Activé par défaut.

Les paramètres de requête sont définis sous forme de paires key=value faisant suite à un ? après le nom du script. Par exemple, pour afficher explicitement les captchas en français, votre balise script devrait ressembler à ceci :

<script src="https://js.hcaptcha.com/1/api.js?hl=fr" async defer></script>

Les paramètres de requête multiples sont séparés par &.

<script
  src="https://js.hcaptcha.com/1/api.js?hl=es&onload=yourFunction&render=explicit"
  async
  defer
></script>

A note on the reCAPTCHA .ready() method

Comme hCaptcha ne déclenche l'événement onload qu'une fois la configuration terminée, il n'est pas nécessaire d'attendre via la méthode .ready(). Il suffit de déclencher le code ou le changement d'état souhaité via l'événement onload ; hCaptcha sera alors prêt pour toute interaction programmatique ultérieure.

Configuration du conteneur hCaptcha

La seconde méthode de configuration de hCaptcha consiste à définir des attributs personnalisés sur le conteneur hCaptcha <div>. Cette opération est déjà obligatoire pour data-sitekey, mais il existe d'autres attributs optionnels permettant une personnalisation plus poussée.

Attribut	Valeur	Description
clé de site de données	<your sitekey>	Obligatoire. Votre clé de site API publique.
thème de données	lumière | sombre	Facultatif. Définissez le thème de couleur du widget. Par défaut : clair.
taille des données	normale | compact	Facultatif. Définissez la taille du widget. Par défaut : normale.
index de tabulation des données	<integer>	Facultatif. Définissez l'indice de tabulation du widget et de la fenêtre contextuelle. Le cas échéant, cela peut rendre la navigation plus intuitive sur votre site. Valeur par défaut : 0.
rappel de données	<function name>	Facultatif. Appelé lorsque l'utilisateur soumet une réponse réussie. Le jeton h-captcha-response est transmis à votre fonction de rappel.
rappel de données expirées	<function name>	Facultatif. Appelé lorsque la réponse du code d'accès expire et que l'utilisateur doit se revérifier.
rappel data-chalexpired	<function name>	Facultatif. Appelé lorsque l'affichage d'un défi à l'utilisateur expire sans réponse.
rappel d'ouverture de données	<function name>	Facultatif. Appelé lorsque l'affichage d'un défi à l'utilisateur commence.
rappel de fermeture des données	<function name>	Facultatif. Appelé lorsque l'utilisateur refuse un défi.
rappel d'erreur de données	<function name>	Facultatif. Appelée lorsque hCaptcha rencontre une erreur et ne peut pas continuer. Si vous spécifiez une fonction de rappel d'erreur, vous devez informer l'utilisateur qu'il doit réessayer. Veuillez consulter the section below pour connaître les codes d'erreur possibles.
orientation des données	portrait | paysage	Optionnel. Permet de définir la rotation du défi hCaptcha affiché en fonction de l'orientation de l'appareil. Prise en charge officiellement uniquement pour les entreprises.

Outre le jeton data-sitekey requis, vous pouvez ajouter autant ou aussi peu d'attributs de configuration que vous le souhaitez.

<div
  class="h-captcha"
  data-sitekey="your_site_key"
  data-theme="dark"
  data-error-callback="onError"
></div>

info

Tous ces attributs peuvent également servir de paramètres lors du rendu explicite avec hcaptcha.render(), comme décrit ci-dessous. Le nom du paramètre correspond à l'attribut du tableau ci-dessus, sans le préfixe de données. Par exemple, data-tabindex devient tabindex lorsqu'il est transmis à .render().

<script type="text/javascript">
  hcaptcha.render('your_div_id', // string: ID of target div to render into
  {
    sitekey: 'your_site_key',
    theme: 'dark', // (for example)
    'error-callback': 'onError', // (for example) string: name of function
  });
</script>

API JavaScript

L'API hCaptcha expose l'objet hcaptcha qui possède des méthodes pouvant vous être utiles pour personnaliser le comportement de hCaptcha.

hcaptcha.render(conteneur, paramètres)

Affiche le widget hCaptcha à l'intérieur de l'élément DOM conteneur. Renvoie un identifiant unique pour le widget.

• container L'identifiant de chaîne du conteneur ou de l'élément DOM du conteneur.
• params Un objet contenant des paramètres de configuration sous forme de paires clé=valeur. Ex :

  {
     "theme": "dark",
     "size": "compact",
     "sitekey": "your_site_key"
  }

hcaptcha.reset(widgetID)

Réinitialise le widget hCaptcha avec widgetID.

• widgetID Identifiant unique facultatif pour un widget. Par défaut, il s'agit du premier widget créé.

hcaptcha.getResponse(widgetID)

Obtient la réponse du widget hCaptcha avec widgetID.

• widgetID Identifiant unique facultatif pour un widget. Par défaut, il s'agit du premier widget créé.

hcaptcha.getRespKey(widgetID)

Obtient l'ID de réponse du widget hCaptcha avec widgetID.

• widgetID Identifiant unique facultatif pour un widget. Par défaut, il s'agit du premier widget créé.

hcaptcha.execute(widgetID)

Déclenche le processus hCaptcha par programmation. Généralement utilisé en mode invisible, lorsque le conteneur cible est une balise div plutôt qu'un bouton.

• widgetID Identifiant unique facultatif pour un widget. Par défaut, il s'agit du premier widget créé.

Mode asynchrone (Obtenir une promesse)

Vous pouvez éventuellement transmettre { async: true } à hcaptcha.execute() afin d'obtenir une promesse en retour.

• Une fois le défi relevé avec succès, il renverra un objet contenant le jeton et la clé de réponse.
• En cas d'erreur, il rejettera avec un code d'erreur approprié (see section below).
• Il ne vous informera pas des jetons expirés, car la promesse aura déjà été résolue avec le jeton dans ce cas de figure.
  • Pour gérer ce cas, vous devrez tout de même spécifier la fonction de rappel expired-callback.

hcaptcha.execute(widgetID, { async: true })
    .then(({ response, key }) => {
        console.log(response, key);
    })
    .catch(err => {
        console.error(err);
    });

Codes d'erreur

Les codes d'erreur suivants sont transmis en tant qu'argument de chaîne à la fonction error-callback ou en tant que données de rejet à l'exécution asynchrone.

Autrement dit, lorsque vous définissez une fonction de rappel d'erreur :

var onError  = function(err) {
    console.log("error!", err);
};

hcaptcha.render('your_div_id', // string: ID of target div to render into
{
  sitekey: 'your_site_key',
  theme: 'dark', // (for example)
  'error-callback': 'onError', // string: name of function
});

Le résultat de onError serait alors "error! invalid-data" ou l'un des autres codes d'erreur énumérés ci-dessous.

Veuillez noter que les appels asynchrones .execute() peuvent rejeter la promesse avec des codes d'erreur supplémentaires (par exemple challenge-closed) qui ne sont pas transmis à error-callback car d'autres rappels (par exemple close-callback) sont définis pour ces scénarios.

Le tableau ci-dessous répertorie chaque code d'erreur, ainsi que les détails permettant de l'interpréter et les actions suggérées.

Si vous utilisez hCaptcha de manière entièrement programmatique (« mode invisible », c'est-à-dire sans case à cocher, avec .execute() appelé par vos fonctions et les erreurs rendues dans votre code plutôt que de dépendre du nôtre), veuillez vous assurer que votre code suit le comportement attendu décrit par l'Action lors de l'interprétation d'une erreur.

Code d'erreur	Description	Action
débit limité	L'utilisateur a envoyé trop de requêtes	-
erreur réseau	Il existe des problèmes de connexion réseau (par exemple, hors ligne)	hCaptcha réessayera automatiquement plusieurs fois avant de se fermer.
données invalides	Les points de terminaison n'acceptent pas les données invalides	-
challenge-error	Erreur lors de la configuration du défi	L'utilisateur devra peut-être cocher la case ou, si elle est invisible, appeler la fonction execute par programmation pour relancer le défi.
défi clôturé*	L'utilisateur a clôturé le défi	-
défi expiré*	Le délai pour répondre au défi a expiré	-
missing-captcha*	Aucun captcha n'a été trouvé	Vérifiez que hCaptcha a été correctement configuré et qu'un captcha a été rendu.
invalid-captcha-id*	Le captcha n'existe pas pour l'identifiant fourni	Vérifiez que le captcha affiché correspond bien à l'identifiant enregistré. Chaque client hCaptcha utilisé contient un nouvel identifiant.
erreur interne	Le client hCaptcha a rencontré une erreur interne	L'utilisateur devra peut-être cocher la case ou, si elle est invisible, appeler la fonction execute par programmation pour relancer le défi.
Erreur de script	Impossible de charger le SDK JavaScript hCaptcha	L'utilisateur se trouve peut-être derrière un pare-feu bloquant api.js. Remarque : présent uniquement lors de l'utilisation de hcaptcha-loader.

• Les événements * sont déclenchés uniquement en cas d'exécution asynchrone.

Afficher explicitement hCaptcha

Dans la configuration par défaut, les widgets hCaptcha sont automatiquement affichés et insérés dans votre page web. Vous pouvez toutefois différer leur affichage en spécifiant une fonction de rappel personnalisée au chargement de la page, dans laquelle vous afficherez vous-même le widget.

Pour spécifier une fonction de rappel personnalisée au chargement de la page, vous devez transmettre le nom de la fonction en tant que paramètre de requête onload dans la balise JavaScript hCaptcha. De plus, vous devez définir le paramètre de requête render sur explicit. Votre balise de script hCaptcha devrait ressembler à ceci (remplacez yourFunction par le nom de votre fonction) :

<script
  src="https://js.hcaptcha.com/1/api.js?onload=yourFunction&render=explicit"
  async
  defer
></script>

Votre fonction de rappel personnalisée doit être définie avant le chargement du script hCaptcha. Vous pouvez ensuite appeler hcaptcha.render avec l'ID du conteneur et votre clé de site pour afficher explicitement le widget.

info

Les paramètres de requête api.js, comme recaptchacompat=off, sont analysés par Dom.ready. N'appelez pas hcaptcha.render() immédiatement si vous utilisez render=explicit afin d'éviter une initialisation conflictuelle du SDK. Appelez plutôt la fonction de rendu définie dans api.js?onload=yourFunc pour garantir que le SDK est entièrement initialisé.

<script type="text/javascript">
  var yourFunction = function () {
    console.log('hCaptcha is ready.');
    var widgetID = hcaptcha.render('captcha-1', { sitekey: 'your_site_key' });
  };
</script>

Thèmes

Vous pouvez appliquer un thème sombre au widget hCaptcha en définissant l'attribut data-theme du conteneur hCaptcha sur dark.

<div class="h-captcha" data-sitekey="your_site_key" data-theme="dark"></div>

Il existe également une option compacte pour réduire l'encombrement du widget. Définissez l'attribut data-size du conteneur hCaptcha sur compact..

<div class="h-captcha" data-sitekey="your_site_key" data-size="compact"></div>