Documentation 6 min read

Stealth Captcha System

Captcha

Published: April 21, 2025

Introdução

O módulo Stealth Captcha System é uma solução robusta e discreta para proteger seu site contra acessos automatizados (bots) e garantir a autenticidade das interações dos usuários. Diferente de outros sistemas de captcha que podem interromper a experiência do usuário, o Stealth Captcha realiza verificações silenciosas e, quando necessário, apresenta desafios de captcha para o usuário, mantendo uma navegação fluida e sem interrupções.

Características Principais

  • Verificação Invisível: Realiza análises em segundo plano para detectar comportamentos suspeitos sem interromper a experiência do usuário.
  • Múltiplos Tipos de Captcha: Suporte para captchas matemáticos, reconhecimento de texto e quebra-cabeças de deslizamento quando necessário.
  • Personalização Avançada: Configurações flexíveis para adaptar o sistema às necessidades específicas do seu site.
  • Compatibilidade Multilíngue: Suporte para vários idiomas, garantindo acessibilidade para usuários de diferentes regiões.
  • Detecção de Bots Avançada: Análise de propriedades e comportamentos do navegador para identificar e bloquear acessos automatizados.
  • Fácil Integração: Implementação simples com apenas algumas linhas de código.
  • Design Responsivo: Interface adaptável a diferentes dispositivos e tamanhos de tela.

Instalação

Para instalar o módulo Stealth Captcha System, siga os passos abaixo:

  • Inclua o Script JavaScript: Adicione o script JavaScript no seu HTML antes do fechamento da tag </body>:
<script src="https://cdn.alphasystem.dev/plugins/stealth-captcha-system/latest/script-min.js"></script>
  • Configure as Callbacks: Defina as funções de callback para os eventos de conclusão e expiração do captcha através do objeto window.StealthCaptchaConfig antes da inclusão do script:
window.StealthCaptchaConfig = {
  onCaptchaComplete: function (token) {
    if (StealthCaptcha.isTokenValid(token)) {
      console.log('CAPTCHA válido:', token);
      alert('O CAPTCHA foi concluído com sucesso!');
    } else {
      console.error('Token inválido ou expirado');
      alert('O CAPTCHA falhou ou expirou. Por favor, tente novamente.');
    }
  },
  onCaptchaExpire: function () {
    console.error('Token de CAPTCHA expirado');
    alert('O CAPTCHA expirou. Por favor, tente novamente.');
  }
};
  • Inicialize o Plugin: Chame a função de inicialização do Stealth Captcha, por exemplo, no evento DOMContentLoaded:
document.addEventListener('DOMContentLoaded', function () {
  StealthCaptcha.init();
});

Configuração

O Stealth Captcha System oferece várias opções de configuração para personalizar seu comportamento e aparência. As configurações padrão podem ser sobrescritas pelo usuário através do objeto window.StealthCaptchaConfig antes da inclusão do script. A seguir, detalhamos as principais opções disponíveis:

  • botScoreThreshold: Define o limite de pontuação para considerar um acesso como bot. Valor padrão: 3.
  • maxCaptchaAttempts: Número máximo de tentativas permitidas antes de bloquear o usuário. Valor padrão: 3.
  • allowedLanguages: Lista de idiomas suportados pelo sistema de captcha. Valores padrão: ['en', 'pt-br', 'es', 'fr', 'de'].
  • captchaTypes: Tipos de captcha disponíveis. Pode incluir 'math', 'textRecognition' e 'sliderPuzzle'. Valores padrão: ['math', 'textRecognition', 'sliderPuzzle'].
  • onCaptchaComplete: Função de callback executada quando o captcha é concluído com sucesso. Recebe o token gerado como parâmetro.
  • onCaptchaExpire: Função de callback executada quando o captcha expira sem ser concluído.

Exemplo de configuração personalizada:

window.StealthCaptchaConfig = {
  botScoreThreshold: 4,
  maxCaptchaAttempts: 5,
  allowedLanguages: ['en', 'es', 'fr'],
  captchaTypes: ['math', 'sliderPuzzle'],
  onCaptchaComplete: function (token) {
    // Lógica personalizada após a conclusão do captcha
  },
  onCaptchaExpire: function () {
    // Lógica personalizada após a expiração do captcha
  }
};

Uso e Integração

Após a instalação e configuração, o Stealth Captcha System estará pronto para uso. A seguir, descrevemos como interagir com o sistema e integrar as validações no fluxo do seu site:

  • Inicialização: O captcha será inicializado quando a função StealthCaptcha.init() for chamada, geralmente no evento DOMContentLoaded.
  • Verificação Invisível: O sistema realiza verificações silenciosas para identificar comportamentos suspeitos.
  • Interação do Usuário: Quando necessário, um modal de captcha será exibido para que o usuário possa completar a verificação.
  • Validação: Após a conclusão do captcha, a função de callback onCaptchaComplete será chamada com o token gerado.
  • Verificação no Servidor: Utilize a função StealthCaptcha.isTokenValid(token) no seu servidor para validar o token recebido.

Exemplo de integração no backend (pseudo-código):

// Supondo que você receba o token via requisição POST
const token = req.body.captchaToken;

if (StealthCaptcha.isTokenValid(token)) {
  // Permitir ação do usuário
} else {
  // Bloquear ação e solicitar novo captcha
}

Referência da API

Funções Disponíveis

  • StealthCaptcha.init(): Inicializa o sistema de captcha. Deve ser chamada após a configuração e quando a página estiver pronta.
  • StealthCaptcha.isTokenValid(token): Valida o token do captcha. Retorna true se o token for válido e não expirado, ou false caso contrário.

Eventos de Callback

  • onCaptchaComplete(token): Executada quando o captcha é concluído com sucesso. Recebe o token gerado como parâmetro.
  • onCaptchaExpire(): Executada quando o captcha expira sem ser concluído.

Propriedades de Configuração

  • botScoreThreshold: Número que define o limite para considerar um acesso como bot. Valor padrão: 3.
  • maxCaptchaAttempts: Número máximo de tentativas de captcha permitidas antes de bloquear o usuário. Valor padrão: 3.
  • allowedLanguages: Array de códigos de idiomas suportados, como 'en', 'pt-br', 'es', 'fr', 'de'. Valor padrão: ['en', 'pt-br', 'es', 'fr', 'de'].
  • captchaTypes: Array de tipos de captcha disponíveis, podendo incluir 'math', 'textRecognition' e 'sliderPuzzle'. Valor padrão: ['math', 'textRecognition', 'sliderPuzzle'].
  • onCaptchaComplete: Função de callback executada quando o captcha é concluído com sucesso.
  • onCaptchaExpire: Função de callback executada quando o captcha expira sem ser concluído.

Resolução de Problemas

Enfrentando problemas com o Stealth Captcha System? Aqui estão algumas soluções para problemas comuns:

  • Captcha Não Aparece: Verifique se o script JavaScript está sendo carregado corretamente e se a função StealthCaptcha.init() está sendo chamada.
  • Funções de Callback Não São Executadas: Assegure-se de que as funções onCaptchaComplete e onCaptchaExpire estão corretamente definidas no objeto window.StealthCaptchaConfig antes da inclusão do script.
  • Tokens Sempre Inválidos: Verifique se a função StealthCaptcha.isTokenValid(token) está implementada corretamente no servidor e que o armazenamento de tokens no sessionStorage está funcionando.
  • Problemas de Estilo: Confirme se não há conflitos de CSS que possam estar afetando a exibição do captcha. Utilize as ferramentas de desenvolvedor do navegador para inspecionar os elementos.
  • Erro de Expiração de Token: Aumente o tempo de expiração do token na configuração ou otimize o processo de validação para reduzir o tempo entre a conclusão do captcha e a verificação no servidor.

Se o problema persistir, consulte a seção de suporte ou entre em contato com a equipe de desenvolvimento para assistência adicional.

Exemplos de Código

Abaixo, alguns exemplos de como integrar e personalizar o Stealth Captcha System:

Exemplo Básico de Integração

<!-- Inclusão do Script do Captcha -->
<script src="https://cdn.alphasystem.dev/plugins/stealth-captcha-system/latest/script-min.js"></script>

<!-- Script de Configuração e Inicialização -->
<script>
  window.StealthCaptchaConfig = {
    onCaptchaComplete: function (token) {
      if (StealthCaptcha.isTokenValid(token)) {
        // Ação após a validação bem-sucedida
        console.log('CAPTCHA validado:', token);
        alert('CAPTCHA concluído com sucesso!');
      } else {
        // Ação em caso de falha na validação
        console.error('Token inválido ou expirado');
        alert('CAPTCHA falhou ou expirou. Por favor, tente novamente.');
      }
    },
    onCaptchaExpire: function () {
      // Ação em caso de expiração do captcha
      console.error('Token de CAPTCHA expirado');
      alert('O CAPTCHA expirou. Por favor, tente novamente.');
    }
  };

  document.addEventListener('DOMContentLoaded', function () {
    StealthCaptcha.init();
  });
</script>

Personalização de Estilos

/* Alterando a cor de fundo do modal do captcha */
.captcha-modal {
  background-color: rgba(0, 0, 0, 0.8);
}

/* Modificando a cor do título */
.captcha-content h2 {
  color: #1e90ff;
  font-size: 24px;
}

Implementação de Callback Personalizado

window.StealthCaptchaConfig = {
  onCaptchaComplete: function (token) {
    fetch('/validate-captcha', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ captchaToken: token })
    })
    .then(response => response.json())
    .then(data => {
      if (data.valid) {
        // Permitir acesso ao conteúdo protegido
        window.location.href = '/conteudo-protegido';
      } else {
        // Notificar o usuário sobre a falha na validação
        alert('CAPTCHA inválido. Por favor, tente novamente.');
      }
    })
    .catch(error => {
      console.error('Erro na validação do CAPTCHA:', error);
      alert('Ocorreu um erro. Por favor, tente novamente mais tarde.');
    });
  },
  onCaptchaExpire: function () {
    alert('O CAPTCHA expirou. Por favor, recarregue a página e tente novamente.');
  }
};