Configuration
Il existe deux manières de configurer hCaptcha. La première consiste à transmettre les paramètres de requête lors du chargement de la ressource javascript hCaptcha. À l'aide des paramètres de requête, vous pouvez spécifier une fonction de rappel personnalisée, différer le rendu ou forcer une localisation spécifique.
| Paramètre | Valeur | Descriptif |
|---|---|---|
| onload | <function name> | Facultatif. Le nom de votre fonction de rappel personnalisée à appeler une fois l'API hCaptcha chargée. Doit être défini avant le chargement de l'API. |
| render | explicite | en charge | Facultatif. S'il faut ou non restituer le widget automatiquement. La valeur par défaut est onload, qui restituera automatiquement les widgets dans les conteneurs hcaptcha div. |
| hl | <language code> | Facultatif. Force une localisation spécifique. Par défaut, hCaptcha détecte automatiquement les paramètres régionaux de l'utilisateur. Voir codes de langue. Peut également être utilisé via la méthode render . |
| récapitulationcompat | sur | désactivé | Facultatif. S'il faut ou non insérer le hook de compatibilité window.grecaptcha. La valeur par défaut est activée. |
Les paramètres de requête sont définis sous forme de paires key=value suivant un ? après le nom du script. Par exemple, pour rendre explicitement les captchas en français, votre balise de script devrait ressembler à ceci :
<script src="https://js.hcaptcha.com/1/api.js?hl=fr" async defer></script>
Plusieurs paramètres de requête sont séparés par& .
src="https://js.hcaptcha.com/1/api.js?hl=es&onload=myFunction&render=explicit"
async
defer
.ready()Étant donné que hCaptcha ne déclenche pas le chargement tant que la configuration n'est pas terminée, il n'est pas nécessaire d'attendre via une méthode .ready() . Déclenchez simplement tout changement de code ou d'état dont vous avez besoin via le chargement, et lorsqu'il se déclenchera, hCaptcha sera déjà prêt pour une interaction programmatique ultérieure.
Configuration du conteneur hCaptcha
La deuxième façon de configurer hCaptcha consiste à définir des attributs personnalisés sur le conteneur hCaptcha <div> . Vous devez déjà le faire avec data-sitekey , mais il existe une poignée d'autres attributs facultatifs qui permettent plus de personnalisation.
| Attribute | Value | Descriptif |
|---|---|---|
| data-sitekey | <your sitekey> | Requis. Votre clé de site API publique. |
| data-theme | light | dark | Facultatif. Définissez le thème de couleur du widget. La valeur par défaut est claire. |
| data-size | normal | compact | Facultatif. Définissez la taille du widget. Par défaut, c'est normal. |
| data-tabindex | <integer> | Facultatif. Définissez le tabindex du widget et du popup. Le cas échéant, peut rendre la navigation plus intuitive sur votre site. La valeur par défaut est 0. |
| data-callback | <function name> | Facultatif. Appelé lorsque l'utilisateur soumet une réponse réussie. Le jetonh-captcha-response est transmis à votre rappel. |
| data-expired-callback | <function name> | Facultatif. Appelé lorsque la réponse du mot de passe expire et que l’utilisateur doit revérifier. |
| data-chalexpired-callback | <function name> | Facultatif. Appelé lorsque l'affichage d'un défi par l'utilisateur expire sans réponse. |
| data-open-callback | <function name> | Facultatif. Appelé lorsque l'affichage utilisateur d'un défi commence. |
| data-close-callback | <function name> | Facultatif. Appelé lorsque l'utilisateur rejette un défi. |
| data-error-callback | <function name> | Facultatif. Appelé lorsque hCaptcha rencontre une erreur et ne peut pas continuer. Si vous spécifiez un rappel d'erreur, vous devez informer l'utilisateur qu'il doit réessayer. Veuillez consulter la section ci-dessous contenant les codes d'erreur possibles. |
Outre le 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>
Tous ces attributs peuvent également être utilisés comme paramètres lors du rendu explicite avec hcaptcha.render() comme décrit ci-dessous. Le nom du paramètre est l'attribut dans le tableau ci-dessus, mais sans le préfixe des données. Par exemple, data-tabindex est tabindex lorsqu'il est passé dans .render() .
<script type="text/javascript">
hcaptcha.render('captcha-1', {
sitekey: 'your_site_key',
theme: 'dark',
'error-callback': 'onError',
});
</script>
API JavaScript
L'API hCaptcha expose l'objet hcaptcha qui possède des méthodes que vous pourriez trouver utiles pour personnaliser le comportement de hCaptcha.
hcaptcha.render(conteneur, paramètres)
Rend le widget hCaptcha à l'intérieur de l'élément DOM du conteneur. Renvoie un widgetID unique pour le widget.
containerL'ID de chaîne du conteneur ou de l'élément DOM du conteneur.paramsUn 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.
widgetIDID unique facultatif pour un widget. La valeur par défaut est le premier widget créé.
hcaptcha.getResponse(widgetID)
Obtient la réponse du widget hCaptcha avec widgetID.
widgetIDID unique facultatif pour un widget. La valeur par défaut est le premier widget créé.
hcaptcha.getRespKey(widgetID)
Obtient l'ID de réponse pour le widget hCaptcha avec widgetID.
widgetIDID unique facultatif pour un widget. La valeur par défaut est le premier widget créé.
hcaptcha.execute(widgetID)
Déclenche le workflow hCaptcha par programme. Généralement utilisé en mode invisible où le conteneur cible est un div plutôt qu'un bouton.
widgetIDID unique facultatif pour un widget. La valeur par défaut est le premier widget créé.
Mode asynchrone
Facultativement, vous pouvez transmettre { async: true } à hcaptcha.execute() afin d'obtenir une promesse en retour.
- Une fois le défi réussi, il sera résolu avec un objet contenant le jeton et la clé de réponse.
- En cas d'erreur, il sera rejeté avec un code d'erreur approprié (voir la section ci-dessous).
- Il ne vous informera pas des jetons expirés, car la promesse aura déjà été résolue avec le jeton dans ce scénario.
- Pour gérer ce cas, vous devrez toujours spécifier le 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 comme argument à la fonction « error-callback » ou comme données de rejet à l'exécution asynchrone.
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 au error-callback car il existe d'autres rappels (par exemple close-callback ) définis pour ces scénarios.
Dans le tableau ci-dessous, chaque code d'erreur est répertorié, ainsi que les détails permettant de l'interpréter et toute action suggérée.
Si vous utilisez hCaptcha dans un modèle 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 compter sur le nôtre), alors veuillez vous assurer que votre code suit le comportement attendu par décrit par l’Action lors de l’interprétation d’une erreur.
| Code d'erreur | Description | Action |
|---|---|---|
rate-limited | L'utilisateur a envoyé trop de requêtes | - |
network-error | Il y a des problèmes de connexion réseau (ex : hors ligne) | hCaptcha va automatiquement réessayer plusieurs fois avant d'abandonner. |
invalid-data | Les données invalides ne sont pas acceptées par les points de terminaison | - |
challenge-error | Une erreur s'est produite lors de la configuration du défi | L'utilisateur devra peut-être cocher la case ou, si invisible, appeler execute() par programmation pour relancer le défi. |
challenge-closed* | L'utilisateur a fermé le défi | - |
challenge-expired* | 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'ID fourni | Vérifiez que le captcha rendu correspond bien à l'ID stocké. Chaque client hCaptcha rendu contient un nouvel ID. |
internal-error | Le client hCaptcha a rencontré une erreur interne | L'utilisateur devra peut-être cocher la case ou, si invisible, appeler execute() par programmation pour relancer le défi. |
*sont levées uniquement dans le cas d'un execute() asynchrone
Rendre explicitement hCaptcha
Dans l'implémentation par défaut, les widgets hCaptcha seront automatiquement rendus et insérés dans votre page Web. Cependant, vous pouvez également différer le rendu en spécifiant une fonction de rappel onload personnalisée dans laquelle vous restituez vous-même le widget.
Pour spécifier une fonction de rappel onload personnalisée, 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 la clé de votre site pour restituer explicitement le widget.
<script type="text/javascript">
var yourFunction = function () {
console.log('hCaptcha is ready.');
var widgetID = hcaptcha.render('captcha-1', { sitekey: 'your_site_key' });
};
</script>
Themes
Vous pouvez appliquer un thème sombre au widget hCaptcha en définissant l'attribut data-theme du conteneur hCaptcha sur dark.
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 passés en argument à la fonction error-callback ou comme données de rejet à l'exécution asynchrone.
Veuillez noter que les appels .execute() asynchrones peuvent rejeter la promesse avec des codes d'erreur supplémentaires (par exemple challenge-closed) qui ne sont pas transmis à error-callback, car il existe d'autres callbacks (par exemple close-callback) définis pour ces scénarios.
Dans le tableau ci-dessous, chaque code d'erreur est répertorié, ainsi que des détails pour l'interpréter et toute action suggérée.
Si vous utilisez hCaptcha dans un modèle entièrement programmatique ("invisible", c'est-à-dire sans case à cocher, avec .execute() appelé par vos fonctions et des erreurs rendues dans votre code plutôt que de compter sur le nôtre) alors assurez-vous 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 |
|---|---|---|
| rate-limited | L'utilisateur a envoyé trop de requêtes | - |
| network-error | Il y a des problèmes de connexion réseau (ex : hors ligne) | hCaptcha va automatiquement réessayer plusieurs fois avant d'abandonner. |
| invalid-data | Les données invalides ne sont pas acceptées par les points de terminaison | - |
| challenge-error | Une erreur s'est produite lors de la configuration du défi | L'utilisateur devra peut-être cocher la case ou, si invisible, appeler execute() par programmation pour relancer le défi. |
| challenge-closed* | L'utilisateur a fermé le défi | - |
| challenge-expired* | 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'ID fourni | Vérifiez que le captcha rendu correspond bien à l'ID stocké. Chaque client hCaptcha rendu contient un nouvel ID. |
| internal-error | Le client hCaptcha a rencontré une erreur interne | L'utilisateur devra peut-être cocher la case ou, si invisible, appeler execute() par programmation pour relancer le défi. |
*sont levées uniquement dans le cas d'un execute() asynchrone
Voici la traduction en français :
Rendu explicite de hCaptcha
Dans l'implémentation par défaut, les widgets hCaptcha seront automatiquement rendus et insérés dans votre page web. Cependant, vous pouvez également différer le rendu en spécifiant une fonction de callback onload personnalisée dans laquelle vous rendez vous-même le widget.
Pour spécifier une fonction de callback onload personnalisée, vous devez passer 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 doit ressembler à ceci (remplacez yourFunction par le nom de votre fonction) :
<script
src="https://hcaptcha.com/1/api.js?onload=yourFunction&render=explicit"
async defer>
</script>
Dans la fonction de callback yourFunction, vous pouvez appeler hcaptcha.render() pour insérer le widget hCaptcha où vous le souhaitez dans le DOM.
Le rendu explicite vous donne un contrôle total sur le moment et l'endroit où le widget hCaptcha est inséré dans la page. Cela peut être utile si vous devez insérer le widget de manière dynamique ou conditionnelle.
Themes
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 donner au widget un encombrement réduit. Définissez l'attribut data-size du conteneur hCaptcha sur compact.
<div class="h-captcha" data-sitekey="your_site_key" data-size="compact"></div>