Périmètre sûr : ce guide s'applique exclusivement à vos propres applications, à vos environnements de QA, de préproduction ou de production, ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni le contournement de protections, ni l'évasion d'anti-bot.
Dans l'extension CaptchaAI, la stabilité de GeeTest v3 tient à quatre réglages : le compte et la clé API, l'isolation du profil de navigateur, la sélection du handler GeeTest v3, et le comportement après la résolution. Traitez l'extension comme un workflow reproductible, pas comme un bouton à cocher, et la plupart des incidents disparaissent.
Ce qui rend GeeTest v3 stable dans l'extension
GeeTest v3 semble trivial dans un carnet de tests, puis casse dès qu'il s'exécute sans surveillance, en CI ou derrière une file d'attente. Ce qu'il vous faut : une latence prévisible, des modes d'échec propres et une configuration lisible en cinq minutes. CaptchaAI prend en charge GeeTest v3 en disponibilité générale, avec une API unique et une facturation par thread.
Les quatre réglages, dans l'ordre
Suivez cet ordre : chaque étape prépare la suivante.
- Compte et clé API. Stockez la clé CaptchaAI dans un coffre ou un secret CI, jamais dans le code, et séparez votre QA de la production.
- Profil de navigateur isolé. Dédiez un profil à l'extension pour éviter que cookies, cache ou autres extensions perturbent le rendu de GeeTest v3.
- Handler GeeTest v3. Sélectionnez-le explicitement plutôt que de vous fier à la détection automatique, et ne capturez que les paramètres attendus : le sitekey, l'URL de la page, le challenge.
- Session post-résolution. Appliquez le token dans la même session que celle qui a déclenché le défi — même contexte de navigateur, même client HTTP, même file de cookies. Une session dépareillée est la première cause de rejet.
Sur une flotte de workers déployée sur OVHcloud ou Scaleway, ce profil dédié se reconstruit à l'identique à chaque déploiement.
Vérifier le token côté backend
Le token retourné doit être vérifié par votre propre backend avant toute opération métier : cette étape empêche qu'une requête soit acceptée sur la base d'un token périmé ou contrefait. Mesurez deux signaux distincts : la réussite de la résolution et l'acceptation en aval.
Exemple : encapsuler l'appel à l'API
Le motif de soumission est identique quel que soit le type : vous changez le type de tâche et gardez la même boucle. Cette fonction envoie une tâche et retourne son identifiant :
import fetch from 'node-fetch';
const API_KEY = process.env.CAPTCHAAI_KEY;
export async function createTurnstileTask(siteKey, pageUrl) {
const res = await fetch('https://api.captchaai.com/createTask', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
clientKey: API_KEY,
task: {
type: 'TurnstileTaskProxyless',
websiteURL: pageUrl,
websiteKey: siteKey,
},
}),
});
const data = await res.json();
return data.taskId;
}
Observabilité et journalisation
Instrumentez chaque appel CAPTCHA : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente. Corrélez les identifiants à votre traçage distribué (par exemple via OpenTelemetry) et, côté RGPD, ne conservez qu'un identifiant de corrélation. La facturation étant par thread — la formule BASIC ($15/mois, 5 threads) suffit à valider un pilote —, surveillez le nombre de threads occupés plutôt que le nombre de résolutions, illimité sur chaque thread.
Dépannage
| Problème | Cause probable | Correctif |
|---|---|---|
| Token refusé après résolution | Token appliqué dans une autre session | Gardez résolution et envoi dans le même contexte de navigateur. |
| Défi GeeTest v3 mal rendu | Profil de navigateur pollué | Repartez d'un profil dédié et vide. |
| Erreur transitoire de l'API | Réseau instable ou pic de charge | Retry idempotent avec backoff exponentiel borné (plafond à 30 s). |
Liste de contrôle avant mise en production
| Contrôle | Réglage attendu |
|---|---|
| Périmètre | Vos propres applications ou des sources autorisées. |
| Profil de navigateur | Dédié à l'extension, handler GeeTest v3 sélectionné. |
| Clé API | Dans un secret CI ou un coffre, jamais dans le code. |
| Traçabilité | Durées d'appel et codes retour tracés à chaque exécution. |
| Session | Token appliqué dans la session qui a déclenché le défi. |
FAQ
L'extension CaptchaAI prend-elle en charge GeeTest v3 ?
Oui. GeeTest v3 est pris en charge en disponibilité générale, à la fois via l'extension et via l'API.
Faut-il isoler le profil de navigateur pour l'extension ?
Oui, c'est fortement recommandé. Un profil dédié évite que des cookies, du cache ou d'autres extensions interfèrent avec le rendu du défi GeeTest v3, et il se reconstruit proprement à chaque exécution en CI.
Pourquoi le token GeeTest v3 est-il refusé après la résolution ?
Le plus souvent, le token a été appliqué dans une session différente de celle qui a déclenché le défi. Conservez la résolution et l'envoi du formulaire dans le même contexte de navigateur ou la même session HTTP.
GeeTest v4 est-il pris en charge ?
Pas encore : la prise en charge de GeeTest v4 est annoncée comme à venir, mais n'est pas disponible. Pour vos intégrations actuelles, ciblez GeeTest v3.
Guides connexes
- Le démarrage rapide CaptchaAI
- La QA CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires
- L'intégration CAPTCHA en continu
- Résoudre reCAPTCHA v2 via l'API
Fiabilisez vos workflows GeeTest v3 avec une approche méthodique et reproductible. – Obtenez votre clé CaptchaAI.
