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:

npm install altcha

Importe no seu projeto:

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:

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

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

Exemplos

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>
  <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.

Tamanho do Pacote

O pacote padrão do ALTCHA é leve, combinando todos os recursos, incluindo CSS e o Web Worker JavaScript, em um único arquivo. GZIPado, totaliza apenas 17 kB, tornando o widget do ALTCHA 94% menor que o reCAPTCHA.

Distribuição	Tamanho (GZIPado)
ALTCHA (v0.9.x)	17 kB
hCaptcha	48+ kB
reCAPTCHA	270+ kB

Configuração

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

challengeurl - URL do seu servidor para buscar o desafio. Consulte integração do servidor.
challengejson - Dados do desafio codificados em JSON. Para 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: off, onfocus, onload, onsubmit).
delay: Atraso artificial em milissegundos antes da verificação (valor padrão: 0).
expire: Duração da expiração do desafio em milissegundos.
floating: Habilitar UI flutuante (valores possíveis: auto, top, bottom).
floatinganchor: Seletor CSS do “âncora” ao qual a UI flutuante será anexada (valor padrão: button[type="submit"] no formulário relacionado).
floatingoffset: Deslocamento Y do elemento âncora para a UI flutuante em pixels (valor padrão: 12).
hidefooter: Ocultar o rodapé (link ALTCHA).
hidelogo: Ocultar o logotipo ALTCHA.
maxnumber: Número máximo para iterar (valor padrão: 1.000.000).
name: Nome do campo oculto contendo o payload (valor padrão: “altcha”).
strings: Cadeias de tradução codificadas em JSON. Consulte personalização.
refetchonexpire: Re-obter e revalidar automaticamente quando o desafio expira (valor padrão: true).
workers: Número de workers a utilizar para PoW (valor padrão: navigator.hardwareConcurrency || 8, valor máximo 16).
workerurl: URL do script Worker (valor padrão: ./worker.js, funciona apenas com a build external).

Opções relacionadas ao filtro anti-spam:

blockspam: Usado apenas com a opção spamfilter. Se ativado, bloqueará o envio do formulário e falhará na verificação se o filtro anti-spam retornar uma classificação negativa. Isso impede o envio do formulário.
spamfilter: Ativar o filtro anti-spam.
verifyurl: URL para solicitações de verificação no lado do servidor. Esta opção é configurada automaticamente quando a opção spamfilter é usada. Substitua esta configuração apenas se estiver utilizando uma implementação de servidor personalizada.

Opções de ofuscação de dados:

obfuscated: Os dados ofuscados fornecidos como uma string codificada em base64 (requer o plugin altcha/obfuscation). Use apenas sem challengeurl/challengejson.

Opções de desenvolvimento/teste:

debug: Imprime mensagens de log no console.
mockerror: Causa a falha da verificação com um erro “mock”.
test: Gera um desafio “mock” dentro do widget, ignorando a solicitação para challengeurl.

Eventos

load: Dispara quando o widget é carregado. Os métodos exportados se tornam disponíveis após este evento.
serververification: Dispara durante a verificação no lado do servidor ao utilizar a API.
statechange: Dispara sempre que um estado interno muda.
verified: Dispara quando o desafio é verificado.

Usando eventos:

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. Como o web worker é executado a partir de um Blob, você precisa adicionar a fonte blob: à sua CSP:

Content-Security-Policy: script-src 'self'; worker-src 'self' blob:

Agrupar tudo em um único arquivo pode causar problemas com regras estritas de CSP. Para conformidade estrita com a CSP, considere usar os scripts localizados no diretório /dist_external ou importar o build external:

import 'altcha/external/altcha.js';

Com CSP estrita, você precisará incluir essas 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.