Conduza a verificação você mesmo com o modo manual

Ao final deste tutorial você terá conduzido o ciclo de vida da verificação Caputchin a partir do seu próprio código em vez da UI embutida, em qualquer dos dois elementos que se encaixe no seu caso. O modo manual (trigger="manual") existe em dois elementos diferentes, e eles fazem trabalhos genuinamente diferentes:

Escolha pela pergunta que você está respondendo:

• "Quero a verificação invisível/checkbox normal, mas disparada pelo meu próprio gesto e sem a checkbox padrão." → a checkbox do widget, abaixo.
• "Quero meu próprio desafio interativo renderizado no meu próprio DOM, não um jogo em iframe, e eu decido aprova/reprova." → o anfitrião de jogo, abaixo.

Leia rode seu próprio jogo para onde o caminho de jogo se encaixa. Você precisa do widget na sua página já; se não, faça adicionar o widget primeiro.

Um limite compartilhado pelos dois: uma rodada de modo manual não pode satisfazer um portão de jogo. O elemento de checkbox nunca protege uma chave de jeito nenhum (só o <caputchin-game> pode), e uma rodada manual de <caputchin-game> não tem trace reproduzível, então uma chave com portão a recusa. O modo manual é para chaves sem portão (verificação de proof-of-work) ou uso só-jogo.

Caminho A: a checkbox do widget, seu próprio gatilho

Use isto quando quiser a verificação padrão mas quiser dispará-la você mesmo, por exemplo para rodar a resolução só quando o visitante envia um formulário, ou atrás do seu próprio botão em vez da checkbox embutida.

1. Marque o elemento como manual

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

Com trigger="manual", a UI de checkbox embutida fica oculta; o elemento espera você iniciar a resolução.

2. Inicie a resolução do seu gesto

O elemento de checkbox em modo manual expõe um único método, start():

• start() dispara a resolução de proof-of-work, substituindo o clique na checkbox. Válido com trigger="manual".

A checkbox do widget não tem pass() / fail(); uma vez que você chama start(), a resolução se resolve sozinha e emite o evento pass. (Os controles de liberar/abortar vivem no anfitrião de jogo, cobertos no Caminho 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
});

Quando a resolução se resolve, o elemento completa a verificação e (em um formulário) injeta o campo caputchin-token como qualquer outro widget. Seu backend verifica esse token exatamente como de costume; o modo manual não muda nada no servidor.

Caminho B: o anfitrião de jogo, seu próprio DOM

Use isto quando quiser renderizar seu próprio desafio interativo no seu próprio markup, em vez de carregar um jogo em iframe, e decidir o resultado você mesmo.

1. Marque o elemento como manual e encaixe seu markup

Ponha trigger="manual" no <caputchin-game> e coloque seu próprio markup dentro dele. Em todo outro modo o widget ignora os filhos de light-DOM; o modo manual é o único modo em que ele os projeta no seu shell de layout por um <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>

Com uma sitekey presente e a chave sem portão, o widget roda sua checagem de proof-of-work em segundo plano; sua interação é a parte visível. Sem sitekey (ou no-verify), é só-jogo: sua interação roda sem nada para verificar.

2. Conduza o resultado a partir do seu código

O anfitrião de jogo em modo manual expõe pass() e fail(). Não há start(): a rodada está ativa assim que o elemento monta (a fábrica sendo montada é o sinal de início).

• pass(payload?) libera a verificação: o visitante teve sucesso. Chame-a uma vez; chamadas posteriores são ignoradas (o veredito fica travado).
• fail(payload?) aborta a rodada. Opcional; uma rodada inacabada é tratada como uma não-aprovação de qualquer forma.

Os payloads:

• pass({ trace }): trace é o registro opaco da rodada que sua interação produz. Numa rodada com portão o servidor o reexecuta para o veredito; numa chave sem portão ou só-jogo ele é aceito como está, então passe uma string vazia (ou um marcador simples) quando não há nada para reexecutar. Não há pontuação fornecida pelo cliente aqui.
• fail({ code?, message? }): um code e message de diagnóstico opcionais, ambos metadados de cliente, nunca um sinal de confiança.

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 no caminho de checkbox, pass() completa a verificação e injeta o token; seu backend o verifica do mesmo jeito.

Reaja ao resultado (ambos os caminhos)

Escute os eventos do widget para atualizar sua própria UI:

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

A decisão de confiança é sempre seu backend confirmando o token, não o evento; o evento é para UX.

O que o modo manual não consegue fazer

• Proteger uma chave de site. Uma chave com exigir um jogo ligado não pode ser satisfeita pelo elemento de checkbox de jeito nenhum, e recusa um <caputchin-game> manual (ele lança um erro de configuração na montagem) porque não há trace reproduzível. O modo manual é para chaves sem portão ou só-jogo.
• Reexecutar a rodada de um jogo personalizado. Se você precisa de um jogo que protege, renderize-o como um jogo em iframe auto-hospedado e produza um trace, não modo manual.

Veja também

• Métodos e eventos do widget: a referência completa de start() / pass() / fail() e cada evento que eles emitem.
• Jogo em iframe auto-hospedado: um jogo em sandbox, reproduzível, que pode proteger.
• Rode seu próprio jogo: os dois modos de entrega comparados.
• Verificar no seu backend: confirmar o token que uma aprovação produz.