Modos de widget Cloudflare Turnstile: gerenciado, não interativo, invisível

Cloudflare Turnstile vem com três modos de widget que controlam como os desafios são apresentados: gerenciado (a Cloudflare decide), não interativo (somente prova de trabalho, nunca mostra a interface do usuário) e invisível (sem contêiner de widget, é executado silenciosamente). O modo determina o que o usuário vê, quanto tempo leva o desafio e se o widget fica visível. Para automação, todos os três modos produzem a mesma saída – um token cf-turnstile-response – mas detectá-los e resolvê-los requer a compreensão das diferenças.

Comparação de modo

Modo gerenciado (padrão)

O modo gerenciado permite que a Cloudflare decida o nível de desafio por visitante. A maioria dos usuários passa de forma invisível. O tráfego suspeito vê uma caixa de seleção. O tráfego altamente suspeito pode enfrentar um desafio mais complexo.

Implementação

<!-- Managed mode (default) -->
<div class="cf-turnstile"
     data-sitekey="0x4AAAAAAAC3DHQhMMQ_Rxrg"
     data-theme="light">
</div>
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>

O que a automação vê

O modo gerenciado se adapta com base nos sinais do solicitante:

Para automação, o modo gerenciado é o mais comum e mais variável. O widget pode ou não estar visível dependendo dos sinais do navegador.

Detecção em HTML

def is_managed_mode(html):
    """Check if Turnstile is using managed mode (default)."""
    # Managed mode is the default — no explicit mode attribute
    has_turnstile = "cf-turnstile" in html
    has_explicit_mode = 'data-appearance="interaction-only"' in html or \
                        'data-appearance="always"' in html or \
                        'appearance: "interaction-only"' in html
    return has_turnstile and not has_explicit_mode

Modo não interativo

O modo não interativo nunca mostra uma caixa de seleção ou elemento interativo. Ele executa um desafio de prova de trabalho em segundo plano e mostra apenas um botão giratório de carregamento. Se o desafio não puder ser concluído de forma não interativa, ele falhará em vez de aumentar.

Implementação

<!-- Non-interactive mode -->
<div class="cf-turnstile"
     data-sitekey="0x4AAAAAAAC3DHQhMMQ_Rxrg"
     data-appearance="interaction-only">
</div>

Ou através da API JavaScript:

turnstile.render('#turnstile-container', {
    sitekey: '0x4AAAAAAAC3DHQhMMQ_Rxrg',
    appearance: 'interaction-only',
    callback: function(token) {
        document.getElementById('cf-turnstile-response').value = token;
    },
});

Comportamento

Page loads → Widget initializes
    ↓
Background proof-of-work runs
    ↓
Success → Token generated (no visible UI)
    OR
Failure → Widget reports error (no fallback to checkbox)

Quando os sites usam não-interativos

• Formulários de comentários e widgets de feedback
• Inscrições em boletins informativos
• Ações de baixo valor onde o atrito deve ser mínimo
• Endpoints de API com proteção no navegador

Modo invisível

O modo invisível é verdadeiramente invisível — nenhum elemento de contêiner aparece na janela de visualização. O widget é executado no carregamento da página (ou gatilho programático) e produz um token sem qualquer indicação visual.

Implementação

<!-- Invisible mode — container is hidden -->
<div id="turnstile-invisible"
     class="cf-turnstile"
     data-sitekey="0x4AAAAAAAC3DHQhMMQ_Rxrg"
     data-size="invisible">
</div>

Ou inteiramente via JavaScript:

// Programmatic invisible Turnstile
turnstile.render('#hidden-container', {
    sitekey: '0x4AAAAAAAC3DHQhMMQ_Rxrg',
    size: 'invisible',
    callback: function(token) {
        // Token ready — submit form automatically
        submitForm(token);
    },
    'error-callback': function() {
        // Challenge failed
        console.error('Invisible Turnstile failed');
    },
});

Desafio de detecção

Cloudflare Turnstile invisível é mais difícil de detectar porque o contêiner não tem dimensões visíveis:

import re

def detect_invisible_turnstile(html):
    """Detect invisible Turnstile on a page."""
    indicators = {
        "script_loaded": "challenges.cloudflare.com/turnstile" in html,
        "size_invisible": 'data-size="invisible"' in html or
                          "size: 'invisible'" in html or
                          'size: "invisible"' in html,
        "api_render_call": "turnstile.render" in html,
        "response_field": "cf-turnstile-response" in html,
    }

    if indicators["script_loaded"] and indicators["size_invisible"]:
        return {"mode": "invisible", "confidence": "high"}
    elif indicators["script_loaded"] and indicators["api_render_call"]:
        return {"mode": "invisible_or_programmatic", "confidence": "medium"}
    elif indicators["response_field"]:
        return {"mode": "turnstile_present", "confidence": "low"}

    return {"mode": "none", "confidence": "high"}

Extraindo sitekey em todos os modos

Independentemente do modo, a chave do site é necessária para a resolução. Extraia-o de qualquer modo:

import re

def extract_turnstile_sitekey(html):
    """Extract Turnstile sitekey from page HTML (works for all modes)."""

    # Pattern 1: data-sitekey attribute in HTML
    match = re.search(r'data-sitekey=["\']([0-9x][A-Za-z0-9_-]+)["\']', html)
    if match:
        return match.group(1)

    # Pattern 2: JavaScript render call
    match = re.search(r"sitekey:\s*['\"]([0-9x][A-Za-z0-9_-]+)['\"]", html)
    if match:
        return match.group(1)

    # Pattern 3: Turnstile config object
    match = re.search(r"siteKey['\"]?\s*[:=]\s*['\"]([0-9x][A-Za-z0-9_-]+)['\"]", html)
    if match:
        return match.group(1)

    return None

Resolvendo todos os três modos com CaptchaAI

Todos os três modos Cloudflare Turnstile são resolvidos de forma idêntica com CaptchaAI. O modo não afeta a chamada da API:

Pitão

import requests
import time

API_KEY = "YOUR_API_KEY"

def solve_turnstile(sitekey, page_url):
    """Solve any Turnstile mode — managed, non-interactive, or invisible."""
    submit = requests.post("https://ocr.captchaai.com/in.php", data={
        "key": API_KEY,
        "method": "turnstile",
        "sitekey": sitekey,
        "pageurl": page_url,
        "json": 1,
    })

    task_id = submit.json()["request"]

    for _ in range(60):
        time.sleep(5)
        result = requests.get("https://ocr.captchaai.com/res.php", params={
            "key": API_KEY,
            "action": "get",
            "id": task_id,
            "json": 1,
        }).json()

        if result.get("status") == 1:
            return result["request"]

    raise TimeoutError("Turnstile solve timed out")


# Use with any mode
token = solve_turnstile("0x4AAAAAAAC3DHQhMMQ_Rxrg", "https://staging.example.com/qa-login")
print(f"Token: {token[:50]}...")

Node.js

const axios = require("axios");

const API_KEY = "YOUR_API_KEY";

async function solveTurnstile(sitekey, pageUrl) {
  const submit = await axios.post("https://ocr.captchaai.com/in.php", null, {
    params: {
      key: API_KEY,
      method: "turnstile",
      sitekey,
      pageurl: pageUrl,
      json: 1,
    },
  });

  const taskId = submit.data.request;

  for (let i = 0; i < 60; i++) {
    await new Promise((r) => setTimeout(r, 5000));

    const result = await axios.get("https://ocr.captchaai.com/res.php", {
      params: { key: API_KEY, action: "get", id: taskId, json: 1 },
    });

    if (result.data.status === 1) {
      return result.data.request;
    }
  }

  throw new Error("Turnstile solve timed out");
}

// Same function works for all Turnstile modes
solveTurnstile("0x4AAAAAAAC3DHQhMMQ_Rxrg", "https://staging.example.com/qa-login")
  .then((token) => console.log("Token:", token.substring(0, 50)));

Solução de problemas

Perguntas frequentes

O modo Cloudflare Turnstile afeta a resolução do CaptchaAI?

Não. CaptchaAI usa o mesmo método turnstile para todos os três modos. A chave do site e o URL da página são os únicos parâmetros necessários. O modo não altera o formato do token ou o fluxo de validação.

Como posso saber qual modo um site usa?

Verifique o HTML para atributos data-appearance ou data-size. Se data-size="invisible" estiver presente, é o modo invisível. Se data-appearance="interaction-only" estiver presente, não será interativo. Se nenhum deles estiver definido, será o modo gerenciado (o padrão).

Um site pode alternar modos dinamicamente?

Sim. Alguns sites usam o modo gerenciado por padrão e mudam para não interativo para páginas ou segmentos de usuários específicos. A chave do site geralmente permanece a mesma. Sempre detecte novamente o modo na navegação.

Qual é a diferença na taxa de sucesso entre os modos?

CaptchaAI atinge 100% de taxa de sucesso em todos os modos Cloudflare Turnstile. O modo afeta apenas o comportamento do usuário – o desafio no nível da API é idêntico.

Resumo

Os três modos de widget do Cloudflare Turnstile – gerenciado, não interativo e invisível – controlam a experiência do usuário, mas produzem o mesmo token cf-turnstile-response. Para automação, todos os modos são resolvidos de forma idêntica usandoSolucionador de catraca do CaptchaAIcom taxa de sucesso de 100%. A principal diferença para os desenvolvedores é a detecção: o modo gerenciado mostra HTML visível, enquanto o modo invisível requer uma análise mais profunda da página para encontrar a chave do site.

Artigos relacionados

• Cloudflare Turnstile em staging vs detecção de catraca
• Comparação de Geetest vs Cloudflare Turnstile
• Cloudflare Turnstile 403 Após correção do token