Guide d'intégration du SDK Web
Compatibilité
| Élément | Description |
|---|---|
| Compatibilité | IE9+, Chrome, Firefox, Safari, Opera, navigateurs mobiles courants, WebView intégré sur iOS et Android |
Formes de vérification
["slide","icon","nine","match"]
Formes actuellement prises en charge :
| Nom | Description |
|---|---|
| slide | Puzzle coulissant |
| icon | Clic séquentiel sur des icônes |
| nine | Grille de neuf |
| match | Jeu de match-3 |
Démarrage rapide
Importation
Fichier gt4.js
Fourni par EngageLab
L'importation de gt4.js montera globalement la fonction d'initialisation initGeetest.
<script src="https://captcha-stat.engagelab.com/www/gt4.js"></script>
Initialiser le Captcha
💡 Astuce
Avant l'initialisation, vous devez obtenir un ID de vérification depuis le serveur. Voir les paramètres de configuration pour plus de détails.
Utilisez la fonction initGeetest pour obtenir l'instance du captcha. Le premier paramètre de cette fonction correspond aux paramètres de configuration du captcha, et le second paramètre est la fonction de rappel après l'initialisation.
var config = {
captchaId: 'xxxx', // ID de vérification
apiServers: ['https://captcha-api.engagelab.com'], // Liste des adresses des serveurs de vérification, doit être configurée selon les besoins
staticServers: ['https://captcha-stat.engagelab.com/www/js'] // Liste des adresses des serveurs de ressources statiques, doit être configurée selon les besoins
}
/**
* @desc Rappel après l'initialisation terminée
* @param { Object } gt Instance du captcha
*/
var callback = function(gt) {
// Gérer les opérations métier en fonction de l'instance du captcha, comme déclencher la fenêtre du captcha, écouter les événements de vérification réussie...
}
initGeetest(config, callback)
Déclencher la fenêtre Captcha
💡 Astuce
Associé au paramètre de configuration
product, il existe deux façons de déclencher la fenêtre du captcha :
- Cliquez sur le bouton intégré fourni pour déclencher. (la valeur de
productn'est pasbind) - Appelez la méthode
showCaptchade l'instance du captcha. (la valeur deproductestbind)
<div id="captch_wrap" class="captch-wrap"></div>
var config = {
captchaId: 'xxxx', // ID de vérification
apiServers: ['https://captcha-api.engagelab.com'], // Liste des adresses des serveurs de vérification, doit être configurée selon les besoins
staticServers: ['https://captcha-stat.engagelab.com/www/js'], // Liste des adresses des serveurs de ressources statiques, doit être configurée selon les besoins
product: 'bind' // Scénario 2
}
/**
* @desc Rappel après l'initialisation terminée
* @param { Object } gt Instance du captcha
*/
var callback = function(gt) {
gt.onReady(function() {
// Scénario 1 : Utiliser le bouton intégré fourni par EngageLab pour déclencher la fenêtre du captcha
// Ajouter le bouton intégré à la zone spécifiée
gt.appendTo("#captch_wrap")
// Scénario 2 : Déclenchement personnalisé de la fenêtre du captcha
// Appeler la méthode showCaptcha de l'instance lors d'un événement spécifique
// Par exemple, déclencher immédiatement après que le captcha soit prêt
gt.showCaptcha()
})
}
initGeetest(config, callback)
Obtenir le résultat de la vérification
/**
* @desc Rappel après l'initialisation terminée
* @param { Object } gt Instance du captcha
*/
var callback = function(gt) {
// Déclencher la fenêtre du captcha...
// Écouter les résultats de la vérification
gt.onSuccess(function(res) {
console.log(res)
})
}
initGeetest({...}, callback)
Paramètres de configuration
Paramètres de configuration
| Paramètre | Type | Description | Valeur par défaut |
|---|---|---|---|
| captchaId | string | ID de vérification, obtenu depuis le back-office EngageLab | Obligatoire |
| product | string | Mode d'affichage de la fenêtre captcha, valeurs possibles : float, popup, bind | float |
| language | string | La priorité est donnée à la valeur transmise, puis à la langue du navigateur. Si aucune ne correspond, la valeur par défaut est utilisée | zh |
| protocol | string | Protocole réseau | // |
| apiServers | array | Adresse du service de requête de vérification (hors protocole), doit être configurée comme ['https://captcha-api.engagelab.com'] | - |
| staticServers | array | Adresse du service de ressources statiques requises pour la vérification (hors protocole), doit être configurée comme ['https://captcha-stat.engagelab.com/www/js'] | - |
| post | boolean | Si true, la méthode de requête est ajax ; sinon, c'est jsonp | false |
| showSuccessTip | boolean | Contrôle la fenêtre de notification de succès lorsque le produit est bind | true |
| riskType | string | Spécifie les formes de vérification comme coulissant, clic, etc. (uniquement effectif si le mode de vérification du système back-end est défini sur mode fusion de risque) | - |
| timeout | number | Délai d'expiration des requêtes de vérification | 30000 |
| offlineCb | function | Fonction personnalisée de gestion hors ligne | - |
| onError | function | Capture d'erreur avant l'initialisation du captcha | - |
| mask | Object | Configuration du masque de la fenêtre captcha | |
| nativeButton | Object | Configuration liée au bouton intégré | |
| toolbar | Array | Configuration de la barre d'outils | |
| clientType | string | Type de client, valeur possible : web | |
| width | string | Définit la largeur de la fenêtre captcha. Largeur max : 340px (la hauteur est adaptative, le ratio est d'environ | 340px |
| zoom | number | Valeur de zoom pour scénarios spéciaux, non limitée par la valeur max (valeur fixe à 1 pour Firefox) | 1 |
Configuration de l'objet Mask
| Paramètre | Type | Description | Valeur par défaut |
|---|---|---|---|
| backgroundColor | string | Valeur de couleur valide | - |
| outside | boolean | Fermer le captcha en cliquant en dehors de la zone captcha | - |
Configuration de l'objet NativeButton
| Paramètre | Type | Description | Valeur par défaut |
|---|---|---|---|
| width | string | Largeur du bouton de déclenchement intégré | - |
| height | string | Hauteur du bouton de déclenchement intégré | - |
Configuration du tableau Toolbar
initGeetest({..., toolbar: ['close', 'refresh']}, function() {...})
Configuration de la langue
initGeetest({..., language: 'zh'}, function() {...})
| Valeur valide | Type | Description |
|---|---|---|
| close | string | Bouton de fermeture de la fenêtre captcha |
| refresh | string | Bouton de rafraîchissement de la fenêtre captcha |
Langues (18 types)
| Valeur optionnelle | Langue |
|---|---|
| ara | Arabe |
| deu | Allemand |
| eng | Anglais |
| fra | Français |
| ind | Indonésien |
| jpn | Japonais |
| kor | Coréen |
| msa | Malais |
| pon | Portugais brésilien |
| por | Portugais européen |
| rus | Russe |
| spa | Espagnol |
| tha | Thaï |
| udm | Ouïghour |
| vie | Vietnamien |
| zh | Chinois simplifié |
| zho-hk | Chinois traditionnel (Hong Kong) |
| zho-tw | Chinois traditionnel (Taïwan) |
Mode hors ligne de vérification comportementale
Le mode hors ligne est mis en place pour gérer les situations extrêmes, garantissant que les processus anormaux de vérification captcha n'affectent pas les processus métier normaux.
Le mode hors ligne survient principalement lorsque le serveur principal du site ne peut pas se connecter au serveur de vérification, entraînant des délais d'attente et d'autres problèmes.
En mode hors ligne, tous les processus de vérification contournent le serveur de vérification. L'intégrateur doit ajouter une logique de vérification ou prévoir un plan de dégradation produit.

Lorsque le serveur de vérification passe en mode hors ligne,
Le processus côté client reste inchangé, et le déclenchement du captcha sera immédiatement validé, entrant dans onSuccess.
Le système métier envoie une vérification secondaire au système captcha, et en cas de délai d'attente, il est confirmé comme étant hors ligne.
initGeetest({...}, function(gt) {
...
gt.onSuccess(function(res) {
console.log(res) // Exemple de résultat de vérification réussi
{
captcha_id: "59bbe0f128f0624fdd185a6a2207aa54",
captcha_output: "X000Q5p.....i-SFRyH1",
client_type: "web",
gen_time: "1648204854",
lot_number: "200e2e58e1d3a6906e08cc9ff5c6e0b5",
offline: true,
pass_token: "e000b4dc372c1397976f7b8f12d66ea8d5c993ab2db5810258e835429f6fa4ae"
}
// Soumettre au système métier...
})
})

