ウィジェットのメソッドとイベント

Caputchin のウィジェットは 2 つのカスタム要素を出荷し、あなたのページは 2 つの方向でそれらと相互作用します。要素の メソッドを呼んで それを駆動し、それが発する イベントを待ち受けて 反応します。このページは、両方の面の網羅的なリファレンスです。

すべてのイベントは bubbles: true と composed: true で送出される CustomEvent なので、ウィジェットのシャドウ DOM を抜け出し、要素（またはどの祖先）でも直接それを待ち受けられます。データは常に event.detail にあります。

2 つの要素を一目で

要素	目的	メソッド
`<caputchin-widget>`	検証のみ（proof-of-work / チェックボックス）。	`start()`
`<caputchin-game>`	ゲームホスト、任意の検証つき。	`pass()`、`fail()`

チェックボックスウィジェットは start() だけを持ちます。pass() / fail() を 公開しません。ゲームホストには start() がありません（そのラウンドは、インラインではマウント時に、modal / fullscreen では最初のダイアログを開いたときにライブになります）。両方の要素が start、pass、error、degraded を発します。ゲームホストは加えて dialog-shown と dialog-hidden を発します。カバー範囲は下のイベントの表にあります。

メソッド

検証を即座に始めます。その目的は 手動トリガー です。要素が trigger="manual" を持つとき、組み込みのチェックボックスの代わりに、あなた自身のジェスチャー（たとえばフォームの送信時）から proof-of-work の解を発火するために start() を呼びます。既定の auto / click トリガーでは、要素が自身の起動を配線するので、これを呼びません。

const widget = document.querySelector("caputchin-widget");
widget.start();

ゲームホストには start() がありません。自分で駆動する完全な手順は手動モードを参照してください。

`pass(payload)`：`<caputchin-game>` のみ

検証ゲートを解放します。訪問者が成功しました。trigger="manual" のときだけ有効。手動でないゲームでそれを呼ぶと、コード invalid-call の error を発します。最初の pass() が判定を引き換えて ロック します。後の呼び出しは黙って無視されます（セッションにつき 1 ラウンド）。

const widget = document.querySelector("caputchin-game");
widget.pass({ trace: roundRecord });

`payload` フィールド	型	意味
`trace`	`string`	あなたのゲームが生む不透明なラウンドの記録。ゲートされたラウンドでは、サーバーが権威ある判定を導くためにそれをリプレイします。ゲートされていない、またはゲームのみのキーでは、そのまま受け付けられます。あなたのインタラクションにリプレイする記録がなければ、空の文字列を渡してください。

このメソッドに score フィールドはありません。ゲートはクライアントが申告するスコアではなく、trace のサーバーのリプレイです。（score は pass イベントには現れます。それは、あなたからウィジェットへではなく、ウィジェットからあなたへの報告です。）

ラウンドが始まる前（modal / fullscreen、まだダイアログが開いていない）に pass() を呼ぶと、コード invalid-call の error を発します。ゲームのみのキー（sitekey なし）では、解放するゲートがないので、pass() は単に token: null で pass イベントを発します。

`fail(payload?)`：`<caputchin-game>` のみ

ラウンドを中止します。決定的な敗北です。trigger="manual" のときだけ有効（さもなければ invalid-call）。任意で、終わっていないラウンドはいずれにせよ非 pass として扱われます。それは進行中の検証（proof-of-work と計測のチェック）を中止し、コード game-error-relayed の error イベントを表に出します。

widget.fail({ code: "out-of-moves", message: "no moves left" });

`payload` フィールド	型	意味
`code`	`string`（任意）	あなたの診断コード。`error` イベントの `originalCode` として表に出ます。既定は `game-failed`。
`message`	`string`（任意）	人間が読める理由。

イベント

addEventListener(type, handler) で待ち受けます。すべてのペイロードは event.detail にあります。

イベント	発する要素	`event.detail`	いつ発火するか
`start`	両方	`{ gameId: string \| null }`	検証が始まる（マウント時に自動、起動時、または `start()` 経由）。`gameId` はゲームのラウンドでは設定され、素のウィジェットでは `null`。
`pass`	両方	`{ token: string \| null, score: number \| null, durationMs: number \| null }`	検証が解放される。`token` はあなたのバックエンドに送る包まれたトークン。ゲームのみのキー（`sitekey` なし）では `null`。
`error`	両方	`{ code, message, severity, originalCode? }`	無害な設定の警告から、厳しい失敗まで何でも。error イベントを参照。
`degraded`	両方	`{ reason: "timeout" \| "network" \| "http" \| "malformed" }`	ウィジェットが、設定したサイズ / スキン / ロケールを間に合うように解決できず、同梱の既定値でレンダリングしました。エラーではありません。degraded イベントを参照。
`dialog-shown`	`<caputchin-game>`	`{ layout: "modal" \| "fullscreen" }`	オーバーレイのゲームのダイアログが開く（プログラム的、または最初のクリック）。
`dialog-hidden`	`<caputchin-game>`	`{ layout: "modal" \| "fullscreen" }`	オーバーレイのゲームのダイアログが閉じる（プログラム的、Escape、または背景のクリック）。

`pass` イベントとトークン

pass イベントは検証が成功したというあなたへの合図ですが、それは信頼の判断では ありません。信頼の判断は、あなたのバックエンドが detail.token を確認することです。常にバックエンドでトークンを検証してください。フロントエンドのイベントだけでアクセスを許可しては決していけません。フォームの中では、ウィジェットはトークンを caputchin-token フィールドとしても注入するので、通常のフォーム POST がそれを運びます。このイベントの score と durationMs は、クライアントが報告する分析で、null になり得ます。決してそれらを信頼のシグナルとして扱わないでください。

`error` イベント

error イベントは、安定した code、人間向けの message、severity、そして時には originalCode を運びます。各コードは固定の既定の severity を持つので、コードと severity の表をハードコードする ことなく、「走り続けた」警告を「本当に壊れた」失敗から絞り込めます。detail.severity を読むだけです。コードの完全なセット：

`code`	`severity`	意味
`invalid-config`	`warn`	ウィジェットが拒否した属性か組み合わせ。優雅に劣化し、走り続けます。
`invalid-call`	`warn`	有効でないときに呼ばれたメソッド（たとえば手動でないゲームでの `pass()`、またはラウンドが始まる前）。
`verification-failed`	`error`	proof-of-work か計測のチェック（またはトークンの引き換え）が失敗。トークンは発行されません。
`game-load-failed`	`error`	ゲームのバンドルを解決、読み込み、登録できませんでした。
`gate-unavailable`	`error`	サーバーがブートストラップで権威ある拒否を返しました（ゲートされたキーが有効なゲームを供給できませんでした）。
`game-error-relayed`	`error`	ゲームの中から表に出たエラー（iframe から、または手動の `fail()` から中継）。

detail.originalCode は、公開の code がより具体的な内部の理由の一般化であるときに存在します（たとえば、game-load-failed として中継された iframe の読み込み失敗は、生の iframe-load-failed / iframe-script-blocked / game-not-registered を originalCode に運びます）。分岐には code を、診断にだけ originalCode を使ってください。

`degraded` イベント

マウント時、ウィジェットは Caputchin に短い呼び出しを 1 回行い、あなたが設定したサイズ、スキン、ロケール（そしてマーケットプレイスのゲームなら、その好みのフットプリント）を解決します。その呼び出しが失敗したり遅すぎたりしても、ウィジェットはブロックも破綻もしません。バンドルに焼き込まれた値でレンダリングし、degraded を発するので、フォールバックが静かに起こることは決してありません。degraded イベントの後もウィジェットは完全に機能し続け、解決された見た目だけが、あなたが設定したものと異なる場合があります（ゲームが既定のサイズで現れたり、チェックボックスが既定のテーマで現れたりします）。ウィジェットはフォールバックする前に遅い解決を再試行するので、degraded は試行が尽きたことを意味し、1 回の試行が遅かったことではありません。

detail.reason は、解決がなぜフォールバックしたかを教えるので、あなた自身のテレメトリに表せます：

`reason`	意味
`timeout`	解決が時間の予算内に答えませんでした（サービスが遅いか到達不能）。
`network`	リクエスト自体が失敗しました（オフライン、DNS、ブロック、または接続リセット）。
`http`	サービスがエラーのステータスで答えました。
`malformed`	サービスは答えましたが、ボディが有効ではありませんでした。

degraded は通知であって失敗ではないので、意図的に error イベントでは ありません。遅い解決が、本当の失敗のために配線したハンドラを発火させるべきではないからです。劣化したレンダリングを観察したい場合だけ、たとえば訪問者がフォールバックの見た目を見ているときに警報を出すために、これを待ち受けてください。

実践での待ち受け

const widget = document.querySelector("caputchin-game");

const onPass = (e) => {
  // send e.detail.token to your backend to verify
};
const onError = (e) => {
  if (e.detail.severity === "error") {
    console.error(e.detail.code, e.detail.message);
  }
};

widget.addEventListener("pass", onPass);
widget.addEventListener("error", onError);

// Clean up when you tear down your view:
widget.removeEventListener("pass", onPass);
widget.removeEventListener("error", onError);

これらはネイティブの DOM CustomEvent なので、React では ref と addEventListener でそれらを取り付けます（JSX の onPass プロップではなく）。フロントエンドの例が、フレームワーク固有の配線を示します。すべてのイベントはバブルし composed なので、各ウィジェットを個別にバインドするのではなく、コンテナ要素から委譲もできます。

あわせて読む

ウィジェットを追加する：マークアップで設定する構成の属性（この出力の面への、入力の面）。
手動モードで自分で検証を駆動する：start() / pass() / fail() を使うチュートリアル。
バックエンドで検証する：pass イベントのトークンで何をするか。
フロントエンドの例：React、Vue、素の JS でこれらのイベントを配線する。