Saltearse al contenido
ALTCHA ALTCHA ALTCHA

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:

Ventana de terminal
npm install altcha

Importalo en tu proyecto:

form.js
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:

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

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

Configuración

Opciones obligatorias (al menos una es requerida):

  • challengeurl - URL de tu servidor para obtener el desafío. Consulta la integración del servidor.
  • challengejson - Datos de desafío codificados en JSON. Si deseas evitar una solicitud HTTP a challengeurl, proporciona los datos aquí.

Opciones adicionales:

  • auto - Verificar automáticamente sin interacción del usuario (valores posibles: onfocus, onload, onsubmit).
  • blockspam - Solo se usa junto con la opción spamfilter. Si está habilitado, bloqueará el envío del formulario y fallará la verificación si el filtro antispam devuelve una clasificación negativa. Esto efectivamente evita el envío del formulario.
  • expire - Expiración del desafío (duración en milisegundos).
  • hidefooter - Ocultar el pie de página (enlace de ALTCHA).
  • hidelogo - Ocultar el logo de ALTCHA.
  • maxnumber - Número máximo de iteraciones (por defecto, 1,000,000).
  • name - Nombre del campo oculto que contiene la carga útil (por defecto, “altcha”).
  • refetchonexpire - Vuelve a recuperar y validar automáticamente cuando expira el desafío (predeterminado a true).
  • spamfilter - Habilita la función de Filtro de Spam.
  • strings - Cadenas de traducción codificadas en JSON. Consulta la personalización.
  • verifyurl - Habilita la verificación del lado del servidor configurando la URL para usar las solicitudes de verificación. Esta opción se puede usar junto con spamfilter para habilitar la verificación del lado del servidor.
  • workers - Número de trabajadores a utilizar para PoW (por defecto, navigator.hardwareConcurrency || 8).

Opciones de desarrollo/pruebas:

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

Eventos:

  • serververification - Se activa durante la verificación del lado del servidor al utilizar la API.
  • statechange - Se activa cada vez que cambia el estado interno state.
  • verified - Se activa cuando se verifica el desafío.

Utilizando eventos:

form.js
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);
  }
});

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.