Integración en el Sitio Web

Integrar ALTCHA en tu sitio web o aplicación web es sencillo y puede completarse en cuestión de minutos.

El método más fácil es utilizar nuestro widget de Componente Web (puedes ver la demo en la página principal).

Instalación vía NPM

Instala el paquete:

npm install altcha

Importalo en tu proyecto:

import 'altcha';

Alternativamente, descarga el script

Descarga el script de ALTCHA desde GitHub o usa el CDN:

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

o jsdelivr.net:

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

Para integrar el widget, añade el script a tu sitio web:

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

Para una integración óptima, coloca la etiqueta del script dentro de la sección <head>.

Ejemplos

Utilizando `<altcha-widget>`

El widget de ALTCHA funciona como un Componente Web y utiliza las capacidades internas del navegador para registrar una nueva etiqueta <altcha-widget>. Integra esta etiqueta dentro de tus formularios:

<form>
  <altcha-widget
    challengeurl="{TU_SERVIDOR_AQUÍ}"
  ></altcha-widget>
</form>

Configura challengeurl con la dirección de tu servidor, o utiliza la API oficial para una integración más fácil y rápida.

Tamaño del Paquete

El paquete predeterminado de ALTCHA es ligero, combinando todos los recursos, incluyendo CSS y el Trabajador Web de JavaScript, en un solo archivo. GZIPpeado, el total es de solo 17 kB, lo que hace que el widget de ALTCHA sea un 94% más pequeño que reCAPTCHA.

Distribución	Tamaño (GZIPpeado)
ALTCHA (v0.9.x)	17 kB
hCaptcha	48+ kB
reCAPTCHA	270+ kB

Configuración

Opciones requeridas (se requiere al menos una):

challengeurl - URL de su servidor para obtener el desafío. Consulte integración del servidor.
challengejson - Datos del desafío codificados en JSON. Si desea evitar una solicitud HTTP a challengeurl, proporcione los datos aquí.

Opciones adicionales:

auto: Verificación automática sin interacción del usuario (valores posibles: off, onfocus, onload, onsubmit).
delay: Retraso artificial en milisegundos antes de la verificación (valor predeterminado: 0).
expire: Duración de la expiración del desafío en milisegundos.
floating: Habilitar interfaz flotante (valores posibles: auto, top, bottom).
floatinganchor: Selector CSS del “ancla” al que se adjuntará la interfaz flotante (valor predeterminado: button[type="submit"] en el formulario relacionado).
floatingoffset: Desplazamiento Y desde el elemento ancla para la interfaz flotante en píxeles (valor predeterminado: 12).
hidefooter: Ocultar el pie de página (enlace de ALTCHA).
hidelogo: Ocultar el logotipo de ALTCHA.
maxnumber: Número máximo para iterar (valor predeterminado: 1.000.000).
name: Nombre del campo oculto que contiene la carga útil (valor predeterminado: “altcha”).
strings: Cadenas de traducción codificadas en JSON. Consulte personalización.
refetchonexpire: Recuperación y revalidación automática cuando expira el desafío (valor predeterminado: true).
workers: Número de trabajadores a utilizar para PoW (valor predeterminado: navigator.hardwareConcurrency || 8, valor máximo 16).
workerurl: URL del script de Worker (valor predeterminado: ./worker.js, solo funciona con la versión external).

Opciones relacionadas con el filtro de spam:

blockspam: Solo se usa con la opción spamfilter. Si está habilitado, bloqueará el envío del formulario y fallará la verificación si el filtro de spam devuelve una clasificación negativa. Esto evita el envío del formulario.
spamfilter: Habilitar filtro de spam.
verifyurl: URL para solicitudes de verificación del lado del servidor. Esta opción se configura automáticamente cuando se usa la opción spamfilter. Anule esta configuración solo si usa una implementación de servidor personalizada.

Opciones de ofuscación de datos:

obfuscated: Los datos ofuscados proporcionados como una cadena codificada en base64 (requiere el complemento altcha/obfuscation). Úselo solo sin challengeurl/challengejson.

Opciones de desarrollo/pruebas:

debug - Imprime mensajes de registro en la consola.
mockerror - Hace que la verificación falle siempre con un error “mock”.
test - Genera un desafío “mock” dentro del widget, evitando la solicitud a challengeurl.

Eventos

load - Se activa cuando se carga el widget. Los métodos exportados están disponibles después de este evento.
serververification - Se activa durante la verificación del lado del servidor cuando se utiliza la API.
statechange - Se activa cuando cambia un state interno.
verified - Se activa cuando se verifica el desafío.

Utilizando eventos:

document.querySelector('#altcha').addEventListener('statechange', (ev) => {
  // los estados pueden ser: unverified, verifying, verified, error
  console.log('estado:', ev.detail.state);
  if (ev.detail.state === 'verified') {
    // la carga útil contiene datos codificados en base64 para el servidor
    console.log('carga útil:', ev.detail.payload);
  }
});

Content-Security-Policy (CSP)

El paquete de distribución predeterminado del WebComponent incluye estilos y el worker en un solo archivo. Dado que el worker web se ejecuta desde un Blob, debes agregar la fuente blob: a tu CSP:

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

Agrupar todo en un solo archivo puede causar problemas con las reglas estrictas de CSP. Para cumplir con CSP estrictas, considera usar los scripts ubicados en el directorio /dist_external o importar el build external:

import 'altcha/external/altcha.js';

Con CSP estrictas, necesitarás incluir estas partes por separado:

altcha/external/altcha.js - El WebComponent sin CSS inyectado y WebWorker.
altcha/external/worker.js - El WebWorker.
altcha/altcha.css - CSS para el Widget.

Precauciones

Requisito de contexto seguro

El widget utiliza la interfaz subtle.crypto incorporada en el navegador para calcular soluciones de manera segura. Es importante tener en cuenta que esta interfaz criptográfica está disponible exclusivamente en un contexto seguro, comúnmente implementado a través de HTTPS.

El widget requiere una conexión segura HTTPS para funcionar. Los sitios web servidos a través de conexiones HTTP inseguras no admitirán la funcionalidad del widget debido a la falta de la interfaz criptográfica requerida. Para garantizar el correcto funcionamiento del widget, siempre sirve tu sitio web de forma segura a través de HTTPS.
Dependencia de JavaScript

El widget funciona con JavaScript y depende de su entorno de ejecución para realizar funciones de cálculo y envío. Por lo tanto, los navegadores con JavaScript habilitado son un requisito previo para que los usuarios interactúen correctamente con el widget.

Al integrar el widget en los formularios del sitio web, ten en cuenta que los usuarios sin JavaScript habilitado en sus navegadores no podrán utilizar ni enviar formularios protegidos por el widget. Asegúrate de que tu audiencia esté al tanto de este requisito para una presentación de formularios sin problemas.