Saltearse al contenido
ALTCHA ALTCHA ALTCHA

Solución de problemas

Esta página proporciona orientación para resolver problemas comunes relacionados con integraciones de ALTCHA. Para comenzar, habilite el modo de depuración en el widget y revise los registros en la consola de desarrolladores.

Modo de Depuración

Para habilitar el modo de depuración en el widget, use el atributo debug:

<altcha-widget
  debug
></altcha-widget>

El modo de depuración mostrará mensajes de registro en la consola. Abra la consola de desarrolladores de su navegador para ver estos registros.

Problemas Comunes

Widget No Encuentra la Solución

Problema:

El widget informa “Verificación fallida” y la consola muestra “No se pudo encontrar una solución” (con debug habilitado).

Solución:

Este problema puede ocurrir debido a:

  1. Número Aleatorio Supera el Máximo: Asegúrese de que el número aleatorio generado por su servidor no supere el número máximo configurado. De forma predeterminada, el número máximo es 1,000,000, pero puede anularse mediante el parámetro maxnumber en la respuesta del desafío. Alinee la generación de números aleatorios de su servidor con este máximo.

  2. Cálculo de Desafío Incorrecto: Verifique la implementación de su servidor. Para más detalles, consulte la documentación del servidor o bibliotecas oficiales para implementaciones específicas de lenguaje. Por ejemplo, verifique si salt=some_salt?expires=1722614680 y number=1234 generan un challenge de SHA-256 igual a 8b1fa4ee51e9e9c8b53cd0c080ca42458accc39424a13fb51e56cfe439814d5f. Asegúrese de que se incluyan en la entrada del hash cualquier parámetro adicional (por ejemplo, expires).

Secure Context

Problema:
El widget de ALTCHA no funciona y muestra el siguiente error en la consola del desarrollador:
Uncaught TypeError: Cannot read properties of undefined (reading 'digest').

Solución:
El widget de ALTCHA utiliza la interfaz SubtleCrypto integrada en el navegador para realizar operaciones criptográficas de forma segura. Esta interfaz solo está disponible en un contexto seguro, que generalmente requiere HTTPS o configuraciones específicas de localhost.

Para resolver este problema:

  1. Asegúrate de acceder a tu sitio web a través de HTTPS.
  2. Para el desarrollo local, utiliza dominios localhost compatibles, como:
    • http://localhost
    • http://*.localhost (por ejemplo, http://miapp.localhost)

Esto habilitará el contexto seguro necesario para que el widget funcione correctamente.

Los oyentes de eventos no funcionan

Problema:

Eventos como statechange o verified no se activan.

Solución:

Asegúrese de adjuntar los oyentes de eventos después de que se haya cargado el script de ALTCHA y el componente se haya inicializado.

  1. Adjuntar oyentes después de la inicialización:
    Los oyentes de eventos deben añadirse solo después de que el script de ALTCHA se haya cargado por completo y el componente se haya inicializado.

    • Para frameworks modernos y empaquetadores:
      Asegúrese de importar import 'altcha' en su aplicación.

    • Para JavaScript personalizado:
      Use el evento DOMContentLoaded para adjuntar los oyentes:

      document.addEventListener('DOMContentLoaded', () => {
        altchaWidgetElement.addEventListener('statechange', (event) => {
          // Manejar evento statechange
        });
      });

  2. Manejo de importaciones asíncronas:
    Si utiliza importaciones asíncronas como import('altcha'), espere a que se resuelvan antes de agregar los oyentes:

    import('altcha').then(() => {
      altchaWidgetElement.addEventListener('statechange', (event) => {
        // Manejar evento statechange
      });
    });

Problemas con el renderizado en el lado del servidor (SSR)

Problema:

Al usar frameworks como Next.js o SvelteKit, la compilación puede fallar con el error ReferenceError: customElements is not defined.

Solución:

El widget de ALTCHA es un WebComponent personalizado y depende de la propiedad Window.customElements, que no suele estar disponible en entornos SSR.

Para resolver esto, asegúrese de que el widget solo se importe en el cliente (navegador). Por ejemplo, utilice la función dinámica import('altcha'). Algunos frameworks ofrecen funciones auxiliares para detectar si el código se ejecuta en el servidor. Si no es así, puede comprobar manualmente el entorno del navegador verificando typeof window.

En SvelteKit, puede usar $app/environment para detectar si el código se está ejecutando en el navegador:

+page.svelte
<script>
  import { browser } from '$app/environment';


  if (browser) {
    import('altcha');
  }
</script>


<altcha-widget></altcha-widget>

Problemas de Política de Seguridad de Contenido (CSP)

Problema:

El widget no se renderiza correctamente o la consola muestra errores relacionados con CSP.

Solución:

Consulte la documentación de Política de Seguridad de Contenido (CSP) para configurar correctamente CSP para el widget.

Problemas de Compartir Recursos de Origen Cruzado (CORS)

Problema:

El widget no puede obtener el desafío desde el servidor y aparecen errores relacionados con CORS en la consola.

Solución:

Este problema surge cuando su sitio web o aplicación está en un dominio diferente al de su servidor. Habilite CORS (Compartir Recursos de Origen Cruzado) en su servidor. Una configuración básica de CORS incluye:

Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *
Access-Control-Allow-Methods: GET, POST, OPTIONS

Para obtener orientación detallada, consulte la documentación de MDN.