Pular para o conteúdo
ALTCHA ALTCHA ALTCHA

Resolução de Problemas

Esta página fornece orientações para resolver problemas comuns relacionados às integrações do ALTCHA. Para começar, habilite o modo de depuração no widget e verifique os registros no console do desenvolvedor.

Modo de Depuração

Para habilitar o modo de depuração no widget, use o atributo debug:

<altcha-widget
  debug
></altcha-widget>

O modo de depuração exibirá mensagens de log no console. Abra o console do desenvolvedor do seu navegador para visualizar esses logs.

Problemas Comuns

Widget Não Consegue Encontrar a Solução

Problema:

O widget relata “Falha na verificação” e o console exibe “Não é possível encontrar uma solução” (com o debug habilitado).

Solução:

Este problema pode ocorrer devido a:

  1. Número Aleatório Excede o Máximo: Certifique-se de que o número aleatório gerado pelo seu servidor não excede o número máximo configurado. Por padrão, o número máximo é 1.000.000, mas pode ser substituído pelo parâmetro maxnumber na resposta do desafio. Alinhe a geração de números aleatórios do seu servidor com este máximo.

  2. Cálculo do Desafio Incorreto: Verifique a implementação do seu servidor. Para detalhes, consulte a documentação do servidor ou bibliotecas oficiais para implementações específicas de linguagens. Por exemplo, verifique se salt=some_salt?expires=1722614680 e number=1234 geram um challenge SHA-256 igual a 8b1fa4ee51e9e9c8b53cd0c080ca42458accc39424a13fb51e56cfe439814d5f. Certifique-se de que quaisquer parâmetros adicionais (por exemplo, expires) sejam incluídos na entrada do hash.

Secure Context

Problema:
O widget ALTCHA não funciona e exibe o seguinte erro no console do desenvolvedor:
Uncaught TypeError: Cannot read properties of undefined (reading 'digest').

Solução:
O widget ALTCHA utiliza a interface SubtleCrypto integrada no navegador para realizar operações criptográficas de forma segura. Esta interface está disponível apenas em um contexto seguro, que geralmente exige HTTPS ou determinadas configurações de localhost.

Para resolver este problema:

  1. Certifique-se de acessar seu site por meio de HTTPS.
  2. Para desenvolvimento local, use domínios localhost suportados, como:
    • http://localhost
    • http://*.localhost (por exemplo, http://meuapp.localhost)

Isso ativará o contexto seguro necessário para que o widget funcione corretamente.

Os ouvintes de eventos não funcionam

Problema:

Eventos como statechange ou verified não são acionados.

Solução:

Certifique-se de anexar os ouvintes de eventos após o script ALTCHA ser carregado e o componente ser inicializado.

  1. Anexar ouvintes após a inicialização:
    Os ouvintes de eventos devem ser adicionados apenas depois que o script ALTCHA for completamente carregado e o componente inicializado.

    • Para frameworks modernos e empacotadores:
      Certifique-se de importar import 'altcha' na sua aplicação.

    • Para JavaScript personalizado:
      Use o evento DOMContentLoaded para anexar os ouvintes:

      document.addEventListener('DOMContentLoaded', () => {
        altchaWidgetElement.addEventListener('statechange', (event) => {
          // Manipular o evento statechange
        });
      });

  2. Lidar com importações assíncronas:
    Se usar importações assíncronas como import('altcha'), aguarde a resolução da importação antes de adicionar os ouvintes:

    import('altcha').then(() => {
      altchaWidgetElement.addEventListener('statechange', (event) => {
        // Manipular o evento statechange
      });
    });

Problemas com renderização no lado do servidor (SSR)

Problema:

Ao usar frameworks como Next.js ou SvelteKit, a compilação pode falhar com o erro ReferenceError: customElements is not defined.

Solução:

O widget ALTCHA é um WebComponent personalizado e depende da propriedade Window.customElements, que normalmente não está disponível em ambientes SSR.

Para resolver isso, certifique-se de que o widget seja importado apenas no cliente (navegador). Por exemplo, use a função dinâmica import('altcha'). Alguns frameworks oferecem funções auxiliares para detectar se o código está sendo executado no servidor. Caso contrário, você pode verificar manualmente o ambiente do navegador usando typeof window.

No SvelteKit, você pode usar $app/environment para detectar se o código está sendo executado no navegador:

+page.svelte
<script>
  import { browser } from '$app/environment';


  if (browser) {
    import('altcha');
  }
</script>


<altcha-widget></altcha-widget>

Problemas de Política de Segurança de Conteúdo (CSP)

Problema:

O widget não é renderizado corretamente, ou o console exibe erros relacionados à CSP.

Solução:

Consulte a documentação da Política de Segurança de Conteúdo (CSP) para configurar corretamente a CSP para o widget.

Problemas de Compartilhamento de Recursos de Origem Cruzada (CORS)

Problema:

O widget falha ao buscar o desafio do servidor e erros relacionados ao CORS aparecem no console.

Solução:

Este problema surge quando seu site ou aplicativo está em um domínio diferente do seu servidor. Habilite o CORS (Compartilhamento de Recursos de Origem Cruzada) no seu servidor. Uma configuração básica do CORS inclui:

Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *
Access-Control-Allow-Methods: GET, POST, OPTIONS

Para orientação detalhada, consulte a documentação do MDN.