Pular para o conteúdo
ALTCHA ALTCHA ALTCHA

Integração de Site

Integrar a ALTCHA em seu site ou aplicativo web é simples e pode ser feito em questão de minutos.

O método mais fácil é utilizar nosso widget de Componente Web (confira a demo na página principal).

Instalação via NPM

Instale o pacote:

Terminal window
npm install altcha

Importe no seu projeto:

form.js
import 'altcha';

Como alternativa, faça o download do script

Baixe o script da ALTCHA do GitHub ou use o CDN:

https://eu.altcha.org/js/latest/altcha.min.js

ou jsdelivr.net:

https://cdn.jsdelivr.net/npm/altcha/dist/altcha.min.js

Para integrar o widget, adicione o script ao seu site:

form.html
<script async defer src="/altcha.js" type="module"></script>

Para uma integração ideal, coloque a tag de script dentro da seção <head>.

Utilizando <altcha-widget>

O widget ALTCHA funciona como um Componente Web e utiliza as capacidades internas do navegador para registrar uma nova tag <altcha-widget>. Integre essa tag em seus formulários:

form.html
<form>
  <altcha-widget
    challengeurl="{SEU_SERVIDOR_AQUI}"
  ></altcha-widget>
</form>

Configure o challengeurl com o endereço do seu servidor, ou use a API oficial para uma integração mais fácil e rápida.

Configuração

Opções obrigatórias (pelo menos uma é necessária):

  • challengeurl - URL do seu servidor para buscar o desafio. Consulte a integração do servidor.
  • challengejson - Dados do desafio codificados em JSON. Se desejar evitar uma solicitação HTTP para challengeurl, forneça os dados aqui.

Opções adicionais:

  • auto - Verificação automática sem interação do usuário (valores possíveis: onfocus, onload, onsubmit).
  • blockspam - Apenas é usado em conjunto com a opção spamfilter. Se ativado, bloqueará o envio do formulário e falhará a verificação se o filtro antispam retornar uma classificação negativa. Isso efetivamente impede o envio do formulário.
  • expire - A expiração do desafio (duração em milissegundos).
  • hidefooter - Ocultar o rodapé (link da ALTCHA).
  • hidelogo - Ocultar o logo da ALTCHA.
  • maxnumber - O número máximo de iteração (padrão: 1.000.000).
  • name - O nome do campo oculto contendo a carga útil (padrão: “altcha”).
  • refetchonexpire - Recupera e valida automaticamente quando o desafio expirar (padrão true).
  • spamfilter - Ative a função de Filtro de Spam.
  • strings - Strings de tradução codificadas em JSON. Consulte a personalização.
  • verifyurl - Abilita la verifica lato server configurando l’URL da usare per le richieste di verifica. Questa opzione può essere usata insieme a spamfilter per abilitare la verifica lato server.
  • workers - O número de workers a ser utilizado para PoW (padrão: navigator.hardwareConcurrency || 8).

Opções de desenvolvimento/teste:

  • debug - Exibir mensagens de log no console.
  • mockerror - Faz com que a verificação sempre falhe com um erro “mock”.
  • test - Gera um desafio “mock” no widget, ignorando a solicitação para challengeurl.

Eventos:

  • serververification - Acionado durante a verificação do lado do servidor ao utilizar a API.
  • statechange - Acionado sempre que um state interno muda.
  • verified - Acionado quando o desafio é verificado.

Usando eventos:

form.js
document.querySelector('#altcha').addEventListener('statechange', (ev) => {
  // state pode ser: unverified, verifying, verified, error
  console.log('state:', ev.detail.state);
  if (ev.detail.state === 'verified') {
    // A carga útil contém dados codificados em base64 para o servidor
    console.log('payload:', ev.detail.payload);
  }
});

Observações

  • Exigência de contexto seguro

    O widget utiliza a interface subtle.crypto integrada no navegador para calcular soluções de forma segura. É essencial observar que essa interface criptográfica está disponível exclusivamente em um contexto seguro, comumente implementado por meio do HTTPS.

    O widget requer uma conexão HTTPS segura para funcionar. Sites servidos por conexões HTTP inseguras não darão suporte à funcionalidade do widget devido à ausência da interface criptográfica necessária. Para garantir a operação perfeita do widget, sempre sirva seu site de forma segura via HTTPS.

  • Dependência de JavaScript

    O widget funciona com JavaScript e depende do ambiente de execução para realizar funções de cálculo e submissão. Como consequência, navegadores habilitados para JavaScript são requisitos para que os usuários interajam com sucesso com o widget.

    Ao integrar o widget em formulários de websites, considere que os usuários sem JavaScript habilitado em seus navegadores serão incapazes de utilizar ou enviar formulários protegidos pelo widget. Certifique-se de que seu público esteja ciente desse requisito para uma submissão de formulário sem falhas.