Périmètre sûr : ce guide s'applique uniquement à 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 couvre ni l'automatisation de sites tiers, ni l'évitement des protections anti-bot.
Un contexte persistant Playwright (launchPersistentContext) charge l'extension CaptchaAI une seule fois et réutilise le même profil de navigateur à chaque exécution. Là où chromium.launch() repart d'un profil vierge, le contexte persistant conserve un répertoire de profil sur disque : l'extension, les cookies et l'état du compte survivent d'un lancement à l'autre. L'extension se charge via --disable-extensions-except et --load-extension, et l'intégration reste fiable en CI ou dans un cron.
Le flux de résolution, étape par étape
- Capturez les bons paramètres. Relevez uniquement ce que la famille de CAPTCHA attend : sitekey, URL, action, proxy éventuel.
- Soumettez la tâche à CaptchaAI et journalisez tout statut d'erreur.
- Interrogez le résultat à intervalle régulier, avec un plafond de temps par tâche.
- Injectez le token dans la même session que celle qui a déclenché le défi — une session différente est la première cause de rejet.
- Mesurez latence, retries et acceptation en aval : réussite de résolution et réussite du workflow sont deux métriques distinctes.
Gérer la clé API et les secrets
La clé CaptchaAI ne doit jamais vivre dans le profil du navigateur ni dans le code source. Stockez-la dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou un secret CI, monté en variable d'environnement au runtime. La facturation se fait par thread simultané, pas par résolution : le plan BASIC ($15/mois, 5 threads) suffit à valider un contexte persistant.
Exemple : appeler CaptchaAI côté serveur
L'appel ci-dessous crée une tâche Turnstile depuis votre propre service, la clé étant lue dans l'environnement :
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;
}
Le taskId alimente votre boucle d'interrogation ; le token obtenu est ensuite injecté dans la page ouverte par le contexte persistant.
Observabilité et journalisation
Instrumentez les appels CAPTCHA pour obtenir des métriques exploitables : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente. Séparez les journaux par environnement et corrélez les identifiants à votre traçage distribué (OpenTelemetry), pour rejouer un scénario complet à partir d'un identifiant unique en cas d'incident.
Scénario : un worker planifié chez un hébergeur européen
Prenez un worker planifié sur une instance Scaleway ou OVHcloud en région eu-west : il ouvre un contexte persistant, traverse une étape protégée par un CAPTCHA dans votre propre application, puis enchaîne. Le premier run marche en cinq minutes ; l'enjeu est qu'il tienne à travers les fenêtres de déploiement et les aléas réseau. Si vos journaux capturent des données personnelles, minimisez leur collecte et vérifiez vos obligations RGPD.
Dépannage
| Symptôme | Cause probable | Correctif |
|---|---|---|
| Token refusé après résolution | Injection dans une session différente de celle du défi. | Résolvez et soumettez dans le même contexte de navigateur. |
ERROR_ZERO_BALANCE |
Solde sous le minimum par tâche. | Rechargez le compte et ajoutez une alerte de solde. |
ERROR_WRONG_USER_KEY |
Clé copiée avec un espace ou mauvais compte. | Recopiez la clé depuis le tableau de bord, en secret CI. |
Liste de contrôle avant la mise en production
- Le périmètre reste limité à vos propres applications ou à des sources autorisées.
- L'extension est chargée via
--load-extensionsur un profil persistant dédié. - La clé CaptchaAI vit dans un coffre ou un secret CI, jamais dans le profil ni dans le code.
- La résolution et la soumission du formulaire se déroulent dans la même session.
- Une stratégie de retry idempotent (backoff exponentiel borné) couvre les erreurs transitoires.
FAQ
Pourquoi charger l'extension via un contexte persistant plutôt qu'un contexte classique ?
Parce que le profil est conservé sur disque entre deux exécutions : l'extension, sa configuration et l'état du compte survivent d'un run à l'autre. En CI ou dans un cron, cela évite les échecs intermittents dus à un profil réinitialisé.
Puis-je partager le même profil entre plusieurs workers ?
Non, évitez-le. Un répertoire de profil Chromium n'est pas conçu pour un accès concurrent : deux workers qui y écrivent en même temps provoquent verrous et corruptions. Affectez un profil distinct à chaque worker.
Faut-il lancer le navigateur en mode visible ou headless ?
Les extensions Chromium ne se chargent de façon fiable qu'en mode visible (headless: false). Sur un serveur sans affichage, placez le contexte derrière un affichage virtuel (Xvfb) afin que l'extension CaptchaAI reste active.
Guides connexes
- Le démarrage rapide CaptchaAI
- La QA CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos formulaires
- Intégrer la résolution CAPTCHA en CI
- Résoudre reCAPTCHA v2 via l'API
Adoptez une approche méthodique et reproductible pour vos workflows CAPTCHA. – Obtenez votre clé CaptchaAI.
