Pular para o conteúdo

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.
  • delay - O atraso artificial em milissegundos para aplicar antes da verificação (padrão é 0).
  • expire - A expiração do desafio (duração em milissegundos).
  • floating - Ativar Floating UI (valores possíveis: auto, top, bottom).
  • floatinganchor - O seletor CSS do “âncora” ao qual a UI flutuante será anexada (padrão é o button[type="submit"] no formulário relacionado).
  • 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).
  • workerurl - A URL do script do Worker (padrão é ./worker.js, funciona apenas com a compilação external).

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);
}
});

Content Security Policy (CSP)

O pacote de distribuição padrão do WebComponent inclui estilos e o worker em um único arquivo. Isso pode causar problemas com regras estritas de CSP. Se você precisar de conformidade estrita com CSP, considere usar os scripts localizados no diretório /dist_external ou importe a compilação external:

form.js
import 'altcha/external/altcha.js';

Com CSP estrita, você precisará incluir estas partes separadamente:

  • altcha/external/altcha.js - O WebComponent sem CSS injetado e WebWorker.
  • altcha/external/worker.js - O WebWorker.
  • altcha/altcha.css - CSS para o Widget.

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.