Construire un rank tracker SEO qui gère les CAPTCHA

Périmètre sûr : Ce guide s'applique exclusivement à vos propres applications, 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.

Un rank tracker qui croise un défi CAPTCHA ne renvoie pas une erreur : il renvoie une position fausse. La gestion des CAPTCHA se conçoit donc dès l'architecture, pas après le premier rapport incohérent. Voici où placer la résolution, comment injecter le token CaptchaAI dans la bonne session et quoi mesurer.

Ce qu'un défi CAPTCHA casse dans un suivi de positions

Trois symptômes reviennent. La page de vérification est enregistrée comme une page de résultats, et le parseur en tire une position aberrante. Des exécutions s'arrêtent en silence et laissent des trous dans la série. Et les moyennes bougent sans qu'aucun classement ne bouge.

Architecture : où placer la résolution dans le pipeline

Le découpage qui tient dans la durée est classique : un planificateur produit les tâches, une file les distribue, des workers collectent, une base stocke les positions. La résolution appartient au worker, jamais au parseur.

Le worker détecte le défi, appelle CaptchaAI en HTTPS, récupère le token et l'injecte dans la même session : même navigateur, même client HTTP, mêmes cookies. Un token appliqué ailleurs est la première cause de rejet. Tracez chaque étape avec un identifiant de tâche unique.

Le trajet d'une mesure, du planificateur à la base :

1. Le planificateur émet une tâche par couple mot-clé / marché, avec son identifiant.
2. Le worker charge la page et teste la présence du défi avant tout parsing.
3. S'il y a défi, il envoie les paramètres attendus (sitekey, URL de page) à l'API CaptchaAI.
4. Il interroge le résultat, réinjecte le token dans la session d'origine et recharge la page.
5. Le parseur ne s'exécute que sur une page de résultats validée ; sinon la mesure est marquée « rejetée », jamais écrite à zéro.

L'étape 5 est celle que les équipes sautent. Écrire une position par défaut plutôt que rien pollue l'historique, et une moyenne mensuelle ne s'en remet pas.

Scénario : un suivi multi-marchés francophones

Prenons un tracker qui suit les mêmes mots-clés en France, en Belgique, en Suisse et au Québec. Les workers tournent chez OVHcloud ou Scaleway, dans une région proche des cibles, pour ne pas attribuer à un CAPTCHA ce qui n'est qu'une latence réseau. Une file par marché évite qu'un incident bloque les autres.

Côté conformité, restez sobre : conservez l'URL, la position, l'horodatage et l'identifiant de tâche, et vérifiez vos obligations RGPD avant d'archiver des pages. Les types rencontrés ici sont pris en charge : reCAPTCHA v2 et v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3, CAPTCHA image et texte.

Configurer la clé API et les secrets

La clé CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager) ou dans un secret CI, jamais dans le dépôt : le déploiement la monte en variable d'environnement au runtime. Ajoutez une alerte sur le solde : un tracker planifié échoue la nuit.

Exemple de code

Extrait de votre suite de tests : création d'une tâche Turnstile.

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;
}

Métriques et journalisation à instrumenter

Quatre signaux suffisent : durée d'obtention du token, code retour HTTP, identifiant de tâche, profondeur de la file. Ajoutez la distinction que beaucoup d'équipes oublient : le taux de réussite de la résolution et le taux d'acceptation en aval sont deux métriques distinctes, et l'écart entre les deux trahit un problème de session. Séparez les journaux par environnement.

Les seuils ci-dessous sont des repères d'exploitation observés sur des collectes planifiées ; ils varient selon l'environnement, le volume et le moment de la journée.

Rattachez ces séries à votre traçage distribué (OpenTelemetry, par exemple) : un identifiant unique doit suffire à rejouer une mesure de bout en bout.

Dépannage

Liste de contrôle avant mise en production

• Périmètre limité à vos applications ou à des sources autorisées.
• Clé CaptchaAI dans un coffre ou un secret CI, jamais dans le code source.
• Token injecté dans la session qui a déclenché le défi.
• Durées d'appel et codes retour tracés à chaque exécution.
• Retry borné et idempotent : trois tentatives, backoff exponentiel, plafond fixe.
• Alerte sur l'écart entre résolution réussie et acceptation du token.

FAQ

Les défis CAPTCHA faussent-ils vraiment mes données de positions ?

Oui, et silencieusement : la réponse est valide au sens HTTP, mais son contenu est une page de vérification. Ajoutez une assertion structurelle avant l'enregistrement — sélecteurs absents, mesure rejetée.

Combien de threads prévoir pour un tracker planifié ?

CaptchaAI facture au thread simultané, résolutions illimitées par thread : un thread = un défi en cours. Démarrez avec BASIC ($15/mois, 5 threads), puis passez à STANDARD ($30/mois, 15 threads) ou ADVANCE ($90/mois, 50 threads) quand la file attend plus qu'elle ne travaille.

CaptchaAI prend-il en charge hCaptcha sur ce type de collecte ?

Non — hCaptcha n'est pas pris en charge, FunCaptcha (Arkose Labs) non plus, et GeeTest v4 est annoncé comme à venir. CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta) sont en bêta uniquement : prévoyez un fallback.

Que faire quand un token est refusé après résolution ?

Vérifiez l'appariement de session (cookies, en-têtes, navigateur), puis la fraîcheur du token, puis l'URL de page et le sitekey face au HTML servi. Ce triplet explique la plupart des rejets.

Guides connexes

• Démarrage rapide CaptchaAI
• QA CAPTCHA en environnements autorisés
• Tester l'endpoint API sur vos formulaires
• Intégration CAPTCHA en CI
• Résoudre reCAPTCHA v2 via API

Une collecte qui ne s'arrête pas au premier défi. – Obtenez votre clé CaptchaAI.