---
type: tutorial
title: Conduza a verificação você mesmo com o modo manual
summary: O modo manual deixa seu próprio código conduzir o ciclo de vida da verificação. Ele existe em dois elementos (a checkbox do widget e o anfitrião de jogo) com trabalhos diferentes; esta página constrói os dois e mostra quando usar cada um.
---

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:

| Elemento | O que o modo manual te dá | Você conduz |
|---|---|---|
| `<caputchin-widget>` | A checkbox embutida fica oculta; você dispara a resolução de proof-of-work do seu **próprio gatilho** (um envio de formulário, um botão personalizado). Sem jogo. | `start()` (depois a resolução geralmente se resolve sozinha) |
| `<caputchin-game>` | Sem iframe; você encaixa **seu próprio markup de jogo** no shell de layout do widget e decide o resultado a partir da jogabilidade. | `pass()` / `fail()` (sem `start()`; a rodada está ativa na montagem) |

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](/docs/custom-game-development/overview) 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](/docs/getting-started/add-the-widget) primeiro.

Um limite compartilhado pelos dois: uma rodada de modo manual **não pode satisfazer um [portão de jogo](/docs/site-keys/games)**. 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

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

```js
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](/docs/integration-guides/verify-on-your-backend) 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>`.

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

```js
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:

```js
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](/docs/site-keys/games) 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](/docs/custom-game-development/self-hosted-game) e produza um trace, não modo manual.

## Veja também

- [Métodos e eventos do widget](/docs/references/widget-methods-and-events): a referência completa de `start()` / `pass()` / `fail()` e cada evento que eles emitem.
- [Jogo em iframe auto-hospedado](/docs/custom-game-development/self-hosted-game): um jogo em sandbox, reproduzível, que pode proteger.
- [Rode seu próprio jogo](/docs/custom-game-development/overview): os dois modos de entrega comparados.
- [Verificar no seu backend](/docs/integration-guides/verify-on-your-backend): confirmar o token que uma aprovação produz.