手動モードで自分で検証を駆動する

このチュートリアルの終わりまでに、組み込みの UI ではなく自分のコードから、あなたのケースに合うほうの要素で、Caputchin の検証のライフサイクルを駆動していることでしょう。手動モード（trigger="manual"）は 2 つの異なる要素に存在し、それらは本当に異なる仕事をします：

答えている問いで選んでください：

• 「通常の不可視/チェックボックスの検証が欲しいが、自分のジェスチャーで引き起こし、既定のチェックボックスなしで。」 → 下の チェックボックスウィジェット。
• 「iframe のゲームではなく、自分の DOM でレンダリングされる自分のインタラクティブなチャレンジが欲しく、pass/fail を自分で決める。」 → 下の ゲームホスト。

ゲームのパスがどこに合うかは 自分のゲームを動かす を読んでください。すでにあなたのページにウィジェットが要ります。なければ先に ウィジェットを追加する を行ってください。

両方が共有する 1 つの限界：手動モードのラウンドは ゲームゲート を満たせません。チェックボックス要素はそもそもキーをまったくゲートせず（<caputchin-game> だけができます）、手動の <caputchin-game> のラウンドにはリプレイ可能なトレースがないので、ゲートされたキーはそれを拒みます。手動モードは、ゲートされていないキー（proof-of-work の検証）か、ゲームのみの使用のためです。

パス A：チェックボックスウィジェット、自分のトリガー

標準の検証が欲しいが自分で発火したいとき、たとえば訪問者がフォームを送信したときだけ解を走らせる、または組み込みのチェックボックスの代わりに自分のボタンの背後で、これを使ってください。

1. 要素を手動にマークする

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

trigger="manual" だと、組み込みのチェックボックス UI は隠れます。要素はあなたが解を開始するのを待ちます。

2. あなたのジェスチャーから解を開始する

手動モードのチェックボックス要素は、単一のメソッド start() を公開します：

• start() は proof-of-work の解を始め、チェックボックスのクリックを置き換えます。trigger="manual" で有効。

チェックボックスウィジェットには pass() / fail() がありません。start() を呼ぶと、解は自分で解決し、pass イベントを発します。（解放/中止のハンドルはゲームホストにあり、パス 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
});

解が解決すると、要素は検証を完了し、（フォームの中では）ほかのどのウィジェットとも同じように caputchin-token フィールドを注入します。あなたのバックエンドは そのトークンを検証 します。いつもとちょうど同じです。手動モードはサーバー側で何も変えません。

パス B：ゲームホスト、自分の DOM

iframe のゲームを読み込む代わりに、自分のマークアップで自分のインタラクティブなチャレンジをレンダリングし、結果を自分で決めたいとき、これを使ってください。

1. 要素を手動にマークし、マークアップをスロットする

<caputchin-game> に trigger="manual" を置き、その中に自分のマークアップを置きます。ほかのすべてのモードでウィジェットはライト DOM の子を無視します。手動モードは、それらを <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>

sitekey が存在しキーがゲートされていないと、ウィジェットはバックグラウンドで proof-of-work のチェックを走らせます。あなたのインタラクションが見える部分です。sitekey がない（または no-verify）と、ゲームのみです。あなたのインタラクションが、検証するもの何もなしに走ります。

2. あなたのコードから結果を駆動する

手動モードのゲームホストは pass() と fail() を公開します。start() はありません。ラウンドは要素がマウントするとライブです（ファクトリーがマウントされることが開始のシグナルです）。

• pass(payload?) は検証を解放します。訪問者が成功しました。一度呼んでください。後の呼び出しは無視されます（判定はロックされます）。
• fail(payload?) はラウンドを中止します。任意です。終わっていないラウンドは、いずれにせよ非 pass として扱われます。

ペイロード：

• pass({ trace })：trace は、あなたのインタラクションが生む不透明なラウンドの記録です。ゲートされたラウンドでは、サーバーが判定のためにそれをリプレイします。ゲートされていない、またはゲームのみのキーでは、そのまま受け付けられるので、リプレイするものがないときは空の文字列（または単純なマーカー）を渡してください。ここにクライアントが供給するスコアはありません。
• fail({ code?, message? })：任意の診断の code と message。どちらもクライアントのメタデータで、決して信頼のシグナルではありません。

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" });

チェックボックスのパスと同じく、pass() は検証を完了してトークンを注入します。あなたのバックエンドは同じやり方でそれを検証します。

結果に反応する（両方のパス）

ウィジェットのイベントを待ち受けて、自分の UI を更新します：

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

信頼の判断は常に、イベントではなく、あなたのバックエンドがトークンを確認することです。イベントは UX のためです。

手動モードができないこと

• サイトキーをゲートする。 ゲームを必須にする をオンにしたキーは、チェックボックス要素ではまったく満たせず、手動の <caputchin-game> を拒みます（設定時に設定エラーを出します）。リプレイ可能なトレースがないからです。手動モードは、ゲートされていない、またはゲームのみのキーのためです。
• カスタムゲームのラウンドをリプレイする。 ゲートするゲームが必要なら、手動モードではなく、セルフホストの iframe ゲーム としてレンダリングし、トレースを生んでください。

あわせて読む

• ウィジェットのメソッドとイベント：start() / pass() / fail() と、それらが発するすべてのイベントの完全なリファレンス。
• セルフホストの iframe ゲーム：ゲートできる、サンドボックス化されたリプレイ可能なゲーム。
• 自分のゲームを動かす：比較された 2 つの配信モード。
• バックエンドで検証する：pass が生むトークンを確認する。