Périmètre sûr : Ce guide s'applique exclusivement à vos propres applications et 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 l'évasion d'anti-bot.
Changer d'extension de résolution CAPTCHA se joue sur trois points : le profil de navigateur, la clé API qui l'authentifie, et la reprise du parcours après injection du token. Traitez la bascule comme un workflow reproductible, pas comme une case à cocher : vous éviterez l'essentiel des incidents qui suivent un changement de fournisseur.
Ce qui change dans votre installation
| Élément | Avant | Avec CaptchaAI |
|---|---|---|
| Authentification | Compte de l'extension | Clé API unique, partagée avec vos scripts |
| Facturation | Propre à l'éditeur | Plans par threads, résolutions illimitées |
| Types couverts | À vérifier | reCAPTCHA, Turnstile, GeeTest v3, image/OCR |
| Profil navigateur | Profil par défaut | Profil dédié, reconstruit à chaque run |
Étape 1 : préparer un profil de navigateur dédié
Créez un profil Chrome distinct pour la recette et chargez-y l'extension CaptchaAI. Désactivez l'ancienne avant de la désinstaller : deux extensions actives injectent des tokens concurrents, et le formulaire rejette le plus ancien.
Étape 2 : brancher la clé API et le compte
Stockez la clé du tableau de bord dans un secret d'intégration continue, jamais dans le dépôt. La même clé alimente l'extension et vos scripts Selenium ou Playwright. BASIC ($15/mois, 5 threads) suffit à quelques dizaines de scénarios par jour ; ADVANCE ($90/mois, 50 threads) couvre une campagne nocturne.
Étape 3 : encapsuler l'appel de résolution
Ne dispersez pas les appels dans vos tests. Une fonction unique prend le sitekey et l'URL de la page, renvoie un token, puis trace la durée et le code retour : vous changerez de type de CAPTCHA sans toucher aux tests.
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;
}
Étape 4 : vérifier le token côté backend
Le token doit être validé par votre backend avant toute opération métier, et appliqué dans la session qui a déclenché le défi CAPTCHA : même contexte de navigateur, même client HTTP, même cookie jar. Une session dépareillée est la première cause de rejet, et le piège classique après l'abandon d'une extension qui gérait ce couplage implicitement.
Étape 5 : instrumenter et journaliser
Suivez quatre signaux : temps d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente. Séparez les journaux par environnement, puis appliquez la minimisation RGPD : ni les données du formulaire, ni l'IP du poste de test n'ont leur place dans ces logs.
Scénario : une campagne nocturne côté QA
Quatre ingénieurs QA lancent chaque nuit une campagne Playwright sur une application interne hébergée chez OVHcloud. L'ancienne extension imposait un profil manuel poste par poste ; désormais la clé arrive par la CI, et le taux de réussite bout en bout se suit séparément du taux de résolution. Chaque échec pointe alors vers une cause précise : session mal reprise ou sitekey périmé.
Dépannage
| Problème | Cause probable | Correctif |
|---|---|---|
| Token refusé après résolution | Token injecté dans une autre session | Gardez le contexte du défi jusqu'à l'envoi |
| Deux tokens sur la même page | Ancienne extension active | Désinstallez-la du profil de recette |
| Erreur d'authentification | Espace parasite dans la clé | Recopiez la clé, rechargez le secret CI |
| Appel sans réponse | Pas de timeout client | Plafond par tâche, backoff borné |
Liste de contrôle avant bascule
| Contrôle | Pourquoi | Fait ? |
|---|---|---|
| Périmètre limité à vos applications ou sources autorisées | Cadre l'usage | ☐ |
| Ancienne extension désinstallée, pas seulement désactivée | Évite les tokens concurrents | ☐ |
| Clé dans un secret CI, jamais dans le dépôt | Rotation possible | ☐ |
FAQ
Faut-il désinstaller l'ancienne extension avant d'installer celle de CaptchaAI ?
Oui, au moins dans le profil de test : deux extensions actives se disputent le champ du token et créent des rejets difficiles à diagnostiquer.
L'extension CaptchaAI prend-elle en charge hCaptcha ?
Non — hCaptcha n'est pas pris en charge, pas plus que FunCaptcha (Arkose Labs) ; GeeTest v4 est annoncé à venir. Sont disponibles : reCAPTCHA v2 et v3, Turnstile, GeeTest v3, image/OCR, plus CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta).
Quel plan choisir pour une petite équipe de recette ?
Partez de BASIC ($15/mois, 5 threads) et observez votre parallélisme une semaine. Au-delà de cinq résolutions simultanées, passez à STANDARD ($30/mois, 15 threads) : les résolutions restent illimitées.
Puis-je garder mes scripts existants pendant la migration ?
Oui : l'extension et l'API partagent la même clé. Migrez un scénario représentatif, comparez les journaux avant et après, puis basculez le reste.
Guides connexes
- Démarrage rapide CaptchaAI
- CAPTCHA en environnements autorisés
- Valider l'endpoint API sur vos formulaires
- Résolution CAPTCHA dans votre CI
- Résoudre reCAPTCHA v2 via l'API
Une migration réussie se mesure en journaux comparables. – Obtenez votre clé CaptchaAI.
