Kemudikan verifikasi sendiri dengan mode manual

Di akhir tutorial ini kamu akan telah mengemudikan siklus hidup verifikasi Caputchin dari kodemu sendiri alih-alih UI bawaan, pada mana pun dari dua elemen yang cocok dengan kasusmu. Mode manual (trigger="manual") ada di dua elemen berbeda, dan mereka melakukan pekerjaan yang sungguh berbeda:

Pilih berdasarkan pertanyaan yang kamu jawab:

• "Aku mau verifikasi tak-kasatmata/checkbox normal, tapi dipicu oleh gestur-ku sendiri dan tanpa checkbox baku." → widget checkbox, di bawah.
• "Aku mau tantangan interaktifku sendiri dirender di DOM-ku sendiri, bukan game iframe, dan aku memutuskan lolos/gagal." → host game, di bawah.

Baca jalankan game-mu sendiri untuk di mana jalur game cocok. Kamu butuh widget di halamanmu sudah; jika tidak, lakukan tambahkan widget dulu.

Satu batas yang dibagi keduanya: ronde mode-manual tak bisa memenuhi gerbang game. Elemen checkbox tak pernah menggerbang sebuah key sama sekali (hanya <caputchin-game> yang bisa), dan ronde <caputchin-game> manual tak punya trace yang bisa-diputar-ulang, jadi key bergerbang menolaknya. Mode manual untuk key tak-bergerbang (verifikasi proof-of-work) atau pemakaian hanya-game.

Jalur A: widget checkbox, pemicumu sendiri

Pakai ini saat kamu mau verifikasi standar tapi ingin menembakkannya sendiri, misalnya untuk menjalankan pemecahan hanya saat pengunjung mengirim formulir, atau di balik tombolmu sendiri alih-alih checkbox bawaan.

1. Tandai elemen manual

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

Dengan trigger="manual", UI checkbox bawaan disembunyikan; elemen menunggu kamu memulai pemecahan.

2. Mulai pemecahan dari gesturmu

Elemen checkbox dalam mode manual memaparkan satu metode, start():

• start() memicu pemecahan proof-of-work, menggantikan klik checkbox. Sah dengan trigger="manual".

Widget checkbox tak punya pass() / fail(); begitu kamu memanggil start(), pemecahan selesai sendiri dan memancarkan event pass. (Handle release/abort hidup di host game, dibahas di Jalur 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
});

Saat pemecahan selesai, elemen menuntaskan verifikasi dan (di sebuah formulir) menyuntikkan field caputchin-token seperti widget lain mana pun. Backend-mu memverifikasi token itu persis seperti biasa; mode manual tak mengubah apa pun di sisi-server.

Jalur B: host game, DOM-mu sendiri

Pakai ini saat kamu mau merender tantangan interaktifmu sendiri di markup-mu sendiri, alih-alih memuat game iframe, dan memutuskan hasilnya sendiri.

1. Tandai elemen manual dan selipkan markup-mu

Taruh trigger="manual" pada <caputchin-game> dan tempatkan markup-mu sendiri di dalamnya. Di setiap mode lain widget mengabaikan anak light-DOM; mode manual adalah satu mode di mana ia memproyeksikannya ke shell tata-letaknya lewat sebuah <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>

Dengan sitekey hadir dan key tak bergerbang, widget menjalankan pemeriksaan proof-of-work-nya di latar; interaksimu adalah bagian yang terlihat. Tanpa sitekey (atau no-verify), ia hanya-game: interaksimu berjalan tanpa apa pun untuk diverifikasi.

2. Kemudikan hasil dari kodemu

Host game dalam mode manual memaparkan pass() dan fail(). Tak ada start(): ronde hidup begitu elemen mount (factory yang ter-mount adalah sinyal mulai).

• pass(payload?) melepaskan verifikasi: pengunjung berhasil. Panggil ia sekali; panggilan berikutnya diabaikan (vonis terkunci).
• fail(payload?) membatalkan ronde. Opsional; ronde yang tak selesai diperlakukan sebagai non-lolos toh.

Payload-nya:

• pass({ trace }): trace adalah catatan ronde opaque yang dihasilkan interaksimu. Pada ronde bergerbang server memutarnya-ulang untuk vonis; pada key tak-bergerbang atau hanya-game ia diterima apa adanya, jadi lewatkan string kosong (atau penanda sederhana) saat tak ada yang diputar-ulang. Tak ada skor yang dipasok-klien di sini.
• fail({ code?, message? }): code dan message diagnostik opsional, keduanya metadata klien, tak pernah sinyal kepercayaan.

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

Seperti dengan jalur checkbox, pass() menuntaskan verifikasi dan menyuntikkan token; backend-mu memverifikasinya dengan cara yang sama.

Bereaksi terhadap hasil (kedua jalur)

Dengarkan event widget untuk memperbarui UI-mu sendiri:

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

Keputusan kepercayaan selalu backend-mu yang memastikan token, bukan event; event untuk UX.

Apa yang tak bisa dilakukan mode manual

• Menggerbang sebuah kunci situs. Sebuah key dengan wajibkan game menyala tak bisa dipenuhi elemen checkbox sama sekali, dan menolak <caputchin-game> manual (ia memunculkan galat konfigurasi saat penyiapan) karena tak ada trace yang bisa-diputar-ulang. Mode manual untuk key tak-bergerbang atau hanya-game.
• Memutar-ulang ronde game kustom. Jika kamu butuh game yang menggerbang, render ia sebagai game iframe swahosting dan hasilkan sebuah trace, bukan mode manual.

Lihat juga

• Metode dan event widget: referensi penuh untuk start() / pass() / fail() dan setiap event yang mereka pancarkan.
• Game iframe swahosting: game ber-sandbox, bisa-diputar-ulang yang bisa menggerbang.
• Jalankan game-mu sendiri: dua mode pengiriman dibandingkan.
• Verifikasi di backend-mu: memastikan token yang dihasilkan sebuah pass.