Easy Captcha System - Alpha System Plugins

Introdução

O módulo Easy Captcha System é uma solução robusta e fácil de usar para proteger seu site contra acessos automatizados (bots) e garantir a autenticidade das interações dos usuários. Com uma abordagem intuitiva e personalizável, este plugin oferece múltiplos tipos de captchas que podem ser integrados de maneira simples a qualquer página web, aumentando a segurança sem comprometer a experiência do usuário.

Características Principais

Múltiplos Tipos de Captcha: Suporte para captchas matemáticos, reconhecimento de texto e quebra-cabeças de deslizamento.
Personalização: 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 comportamento do usuário 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.

Além das características listadas, o Easy Captcha System implementa medidas de segurança avançadas, como detecção de ferramentas de desenvolvimento e análise heurística para identificar potenciais bots, garantindo uma proteção robusta para o seu site.

Instalação

Para instalar o módulo Easy 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/easy-captcha-system/latest/script-min.js"></script>

Adicione o Elemento Container: Insira um elemento container onde o captcha será renderizado:

<div id="easy-captcha"></div>

Configure as Callbacks: Defina as funções de callback para os eventos de conclusão e expiração do captcha:

window.EasyCaptchaConfig = {
  onCaptchaComplete: function (token) {
    if (isTokenValid(token)) {
      console.log('CAPTCHA válido:', token);
      alert('CAPTCHA concluído com sucesso!');
    } else {
      console.error('CAPTCHA inválido ou expirado');
      alert('CAPTCHA falhou ou expirou. Por favor, tente novamente.');
    }
  },
  onCaptchaExpire: function () {
    console.error('CAPTCHA expirado');
    alert('O CAPTCHA expirou. Por favor, tente novamente.');
  }
};

Nota: Não é necessário instanciar a biblioteca manualmente, pois ela se inicializa automaticamente após a inclusão do script.

Configuração

O Easy 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.EasyCaptchaConfig. A seguir, detalhamos as principais opções disponíveis:

botScoreThreshold: Define o limite de pontuação para considerar um acesso como bot. Padrão: 3.
maxCaptchaAttempts: Número máximo de tentativas permitidas antes de bloquear o usuário. Padrão: 3.
allowedLanguages: Lista de idiomas suportados pelo sistema de captcha. Padrão: ['en', 'pt-br', 'es', 'fr', 'de'].
captchaTypes: Tipos de captcha disponíveis (matemático, reconhecimento de texto, quebra-cabeça de deslizamento). 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.

Exemplo de configuração personalizada:

window.EasyCaptchaConfig = {
  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
  }
};

Observação: As configurações definidas no window.EasyCaptchaConfig são imutáveis após a inicialização da biblioteca.

Uso e Integração

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

Renderização Automática: O captcha será automaticamente renderizado no elemento container especificado.
Interação do Usuário: Ao clicar no widget de captcha, o modal será exibido com o desafio apropriado.
Validação no Cliente: Após a conclusão do captcha, a função de callback onCaptchaComplete será chamada com o token gerado.
Verificação no Servidor: Atualmente, a validação do token é realizada no lado do cliente através da função isTokenValid(token). Para validação no servidor, implemente uma lógica personalizada que verifique a validade do token conforme sua aplicação.

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

// Exemplo de lógica personalizada para validar o token no servidor
function validateCaptchaToken(token) {
  // Implementar a verificação do token conforme a lógica da sua aplicação
  // Por exemplo, consultar um banco de dados ou verificar a assinatura do token
  return true; // ou false dependendo da validação
}

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

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

Referência da API

Funções Disponíveis

isTokenValid(token): Valida o token do captcha no lado do cliente.

Eventos de Callback

onCaptchaComplete(token): Executada quando o captcha é concluído com sucesso. Recebe o token gerado.
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.
maxCaptchaAttempts: Número máximo de tentativas de captcha permitidas.
allowedLanguages: Array de códigos de idiomas suportados.
captchaTypes: Array de tipos de captcha disponíveis.
onCaptchaComplete: Função de callback executada quando o captcha é concluído com sucesso.
onCaptchaExpire: Função de callback executada quando o captcha expira.

Nota: A função isTokenValid(token) deve ser utilizada no lado do cliente para validação do token gerado pelo captcha.

Resolução de Problemas

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

Captcha Não Aparece: Verifique se o elemento container com o ID easy-captcha está presente no HTML e se o script JavaScript está sendo carregado corretamente.
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.EasyCaptchaConfig.
Tokens Sempre Inválidos: Verifique se a função isTokenValid(token) está sendo chamada corretamente no lado do cliente e que a lógica personalizada de validação no servidor está implementada conforme necessário.
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 Easy Captcha System:

Exemplo Básico de Integração

<!-- Elemento Container -->
<div id="easy-captcha"></div>

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

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

Personalização de Estilos

/* Alterando a cor de fundo do container do captcha */
#easy-captcha .recaptcha-container {
  background-color: #f0f8ff;
  border-color: #1e90ff;
}

/* Modificando a cor do texto do label */
#easy-captcha .recaptcha-label {
  color: #1e90ff;
  font-size: 18px;
}

Implementação de Callback Personalizado

window.EasyCaptchaConfig = {
  onCaptchaComplete: function (token) {
    // Enviar o token para o servidor para validação
    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.');
  }
};