Conduce la verificación tú mismo con el modo manual

Al final de este tutorial habrás conducido el ciclo de vida de verificación de Caputchin desde tu propio código en lugar de la UI integrada, en cualquiera de los dos elementos que encaje con tu caso. El modo manual (trigger="manual") existe en dos elementos distintos, y hacen trabajos genuinamente distintos:

Elige según la pregunta que respondes:

• "Quiero la verificación normal invisible/checkbox, pero disparada por mi propio gesto y sin la checkbox por defecto." → el widget de checkbox, abajo.
• "Quiero mi propio reto interactivo renderizado en mi propio DOM, no un juego en iframe, y yo decido pass/fail." → el anfitrión de juego, abajo.

Lee corre tu propio juego para saber dónde encaja el camino del juego. Necesitas el widget en tu página ya; si no, añade el widget primero.

Un límite que comparten ambos: una ronda en modo manual no puede satisfacer un gate de juego. El elemento de checkbox nunca ejerce de gate de una clave en absoluto (solo <caputchin-game> puede), y una ronda manual de <caputchin-game> no tiene traza reproducible, así que una clave con gate la rechaza. El modo manual es para claves sin gate (verificación de proof-of-work) o para uso solo-juego.

Camino A: el widget de checkbox, tu propio disparador

Usa esto cuando quieras la verificación estándar pero quieras dispararla tú mismo, por ejemplo para correr la resolución solo cuando el visitante envía un formulario, o tras tu propio botón en vez de la checkbox integrada.

1. Marca el elemento como manual

<caputchin-widget id="cap" sitekey="cpt_pub_..." trigger="manual"></caputchin-widget>
<button id="go" type="button">Verify and continue</button>

Con trigger="manual", la UI de checkbox integrada se oculta; el elemento espera a que inicies la resolución.

2. Inicia la resolución desde tu gesto

El elemento de checkbox en modo manual expone un único método, start():

• start() arranca la resolución de proof-of-work, reemplazando el clic en la checkbox. Válido con trigger="manual".

El widget de checkbox no tiene pass() / fail(); una vez que llamas a start(), la resolución se resuelve sola y emite el evento pass. (Los controles de liberar/abortar viven en el anfitrión de juego, cubierto en el Camino B.)

const widget = document.getElementById("cap");

document.getElementById("go").addEventListener("click", () => {
  widget.start(); // begin verification now
});

widget.addEventListener("pass", () => {
  // token issued; submit your form / continue
});

Cuando la resolución se resuelve, el elemento completa la verificación y (en un formulario) inyecta el campo caputchin-token como cualquier otro widget. Tu backend verifica ese token exactamente como siempre; el modo manual no cambia nada en el servidor.

Camino B: el anfitrión de juego, tu propio DOM

Usa esto cuando quieras renderizar tu propio reto interactivo en tu propio markup, en vez de cargar un juego en iframe, y decidir el desenlace tú mismo.

1. Marca el elemento como manual y encaja tu markup

Pon trigger="manual" en <caputchin-game> y coloca tu propio markup dentro de él. En todos los demás modos el widget ignora los hijos del light DOM; el modo manual es el único modo donde los proyecta en su shell de layout a través de un <slot>.

<caputchin-game id="cap" sitekey="cpt_pub_..." trigger="manual">
  <!-- Your own markup. The widget renders it inside its shell. -->
  <div id="my-game">
    <p>Tap the banana three times.</p>
    <button id="banana" type="button">🍌</button>
  </div>
</caputchin-game>

Con una sitekey presente y la clave sin gate, el widget corre su comprobación de proof-of-work en segundo plano; tu interacción es la parte visible. Sin sitekey (o no-verify), es solo-juego: tu interacción corre sin nada que verificar.

2. Conduce el desenlace desde tu código

El anfitrión de juego en modo manual expone pass() y fail(). No hay start(): la ronda está en vivo en cuanto el elemento se monta (que la factory esté montada es la señal de inicio).

• pass(payload?) libera la verificación: el visitante tuvo éxito. Llámalo una vez; las llamadas posteriores se ignoran (el veredicto queda bloqueado).
• fail(payload?) aborta la ronda. Opcional; una ronda sin terminar se trata como un no-pass de todos modos.

Los payloads:

• pass({ trace }): trace es el registro opaco de ronda que tu interacción produce. En una ronda con gate el servidor la repite para el veredicto; en una clave sin gate o solo-juego se acepta tal cual, así que pasa una cadena vacía (o un marcador simple) cuando no hay nada que repetir. No hay puntuación suministrada por el cliente aquí.
• fail({ code?, message? }): un code y message de diagnóstico opcionales, ambos metadato del cliente, nunca una señal de confianza.

const widget = document.getElementById("cap");
let taps = 0;

document.getElementById("banana").addEventListener("click", () => {
  taps += 1;
  if (taps >= 3) {
    widget.pass({ trace: `banana:${taps}` }); // visitor won
  }
});

// Optional: give up explicitly.
// widget.fail({ code: "gave-up", message: "closed the prompt" });

Como en el camino de la checkbox, pass() completa la verificación e inyecta el token; tu backend lo verifica de la misma forma.

Reacciona al desenlace (ambos caminos)

Escucha los eventos del widget para actualizar tu propia UI:

widget.addEventListener("pass", () => {
  // verification released
});
widget.addEventListener("error", (e) => {
  console.warn("verification error", e.detail);
});

La decisión de confianza es siempre tu backend confirmando el token, no el evento; el evento es para UX.

Lo que el modo manual no puede hacer

• Ejercer de gate de una clave de sitio. Una clave con exigir un juego activado no puede satisfacerse con el elemento de checkbox en absoluto, y rechaza un <caputchin-game> manual (lanza un error de configuración en el montaje) porque no hay traza reproducible. El modo manual es para claves sin gate o solo-juego.
• Repetir la ronda de un juego a medida. Si necesitas un juego que ejerza de gate, renderízalo como un juego autoalojado en iframe y produce una traza, no el modo manual.

Véase también

• Métodos y eventos del widget: la referencia completa de start() / pass() / fail() y cada evento que emiten.
• Juego autoalojado en iframe: un juego en sandbox y reproducible que puede ejercer de gate.
• Corre tu propio juego: los dos modos de entrega comparados.
• Verifica en tu backend: confirmar el token que produce un pass.