Extension CaptchaAI : notifications overlay et masquage du statut résolu

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 traite pas de l'automatisation de sites tiers ni de la neutralisation de protections anti-bot.

Les notifications overlay de l'extension CaptchaAI signalent, sur la page, l'état d'un défi CAPTCHA : détecté, en cours de résolution, puis résolu. Le masquage automatique du statut résolu fait disparaître cet indicateur une fois le token injecté. Bien réglés, ces deux paramètres font de l'extension un maillon stable de votre workflow navigateur.

Ce que font les notifications overlay et le masquage automatique

• Notifications overlay : elles affichent l'état du défi sur la page, un repère utile en session interactive quand vous vérifiez que l'extension prend le relais.
• Masquage automatique : il efface cet indicateur dès l'injection du token, pour éviter qu'un badge « résolu » ne recouvre un champ ou ne fausse une capture d'écran de test.
• En pratique : activez les notifications pendant la mise au point, puis laissez le masquage agir une fois le workflow stabilisé.

Configurer l'extension CaptchaAI comme un workflow reproductible

Traitez l'extension comme un maillon reproductible, pas comme un clic ponctuel : elle paraît triviale en test, puis casse à la première exécution sans surveillance. Quatre éléments la gardent stable : l'état du compte, le profil de navigateur, le gestionnaire de CAPTCHA et le comportement après résolution.

Conservez votre clé CaptchaAI dans un coffre (Vault, AWS Secrets Manager) ou un secret de CI, jamais en clair dans le code. Réutilisez un profil de navigateur dédié et versionné : cookies, état de connexion et réglages de l'extension y restent cohérents.

Workflow recommandé étape par étape

1. Capturez uniquement les paramètres attendus par le solveur : sitekey, URL de la page, action éventuelle et proxy optionnel. Stocker davantage crée de fausses pistes de débogage.
2. Envoyez la tâche à https://ocr.captchaai.com/in.php avec json=1. Traitez tout statut différent de 1 comme une erreur et journalisez la réponse.
3. Interrogez le résultat sur https://ocr.captchaai.com/res.php : attendez 15 s, puis toutes les 5 s, avec un plafond de 120 s par tâche.
4. 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 cookie jar. Les sessions dépareillées sont la première cause de rejet.
5. Suivez la latence, les retries et l'acceptation en aval : réussite du solveur et réussite du workflow sont deux métriques distinctes.

Exemple de code : vérifier le solde

Placez un contrôle de solde en amont de vos jobs planifiés : un solde nul détecté tôt évite une vague d'échecs ERROR_ZERO_BALANCE.

import os
import requests

API_KEY = os.environ['CAPTCHAAI_KEY']

def get_balance() -> float:
    resp = requests.post(
        'https://api.captchaai.com/getBalance',
        json={'clientKey': API_KEY},
        timeout=15,
    )
    resp.raise_for_status()
    return float(resp.json().get('balance', 0))

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 chaque identifiant à votre traçage distribué (OpenTelemetry), en minimisant les données personnelles conformément à vos obligations RGPD. Surveillez en priorité :

• la latence de première résolution ;
• le taux de réussite par famille de CAPTCHA ;
• l'écart entre résolution réussie et acceptation en aval.

Dépannage

FAQ

Comment activer ou désactiver les notifications overlay de l'extension ?

Ouvrez les réglages de l'extension CaptchaAI et basculez l'option de notifications overlay. Activez-la pour suivre l'état de résolution pendant la mise au point, puis désactivez-la — ou laissez le masquage agir — une fois le workflow stabilisé.

Le masquage automatique du statut résolu ralentit-il la résolution ?

Non. Le masquage n'agit que sur l'affichage : il efface l'indicateur « résolu » après l'injection du token. La détection, l'appel à l'API et l'injection restent identiques, indicateur visible ou non.

Que faire en cas d'erreur transitoire de l'API ?

Appliquez un retry avec backoff exponentiel borné (par exemple trois tentatives, délai doublé, plafond à 30 s) et tracez chaque échec avec son identifiant de tâche. Si l'erreur persiste, vérifiez le réseau (DNS, certificats) et les quotas liés à votre clé.

Guides connexes

• Démarrage rapide CaptchaAI
• QA CAPTCHA en environnement autorisé
• Tester l'endpoint API sur vos formulaires
• Résolution CAPTCHA dans votre CI
• Résoudre reCAPTCHA v2 via l'API

Passez d'un clic ponctuel à un workflow navigateur fiable et mesurable. Créez votre compte CaptchaAI.