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.

Listeners 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 do ALTCHA ter sido carregado e o componente inicializado. Em frameworks modernos e empacotadores, certifique-se de importar ‘altcha’ em seu aplicativo. Para JavaScript personalizado, use:

window.addEventListener('load', () => {
  altchaWidgetElement.addEventListener('statechange', (ev) => {
    // Manipule 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.