قُد التحقّق بنفسك بالوضع اليدوي

بنهاية هذا الدرس ستكون قد قُدت دورة حياة تحقّق Caputchin من كودك الخاص بدل الواجهة المدمجة، على أيّ من العنصرين يناسب حالتك. الوضع اليدوي (trigger="manual") موجود على عنصرين مختلفين، ويؤدّيان مهامّ مختلفة حقًّا:

اختر بحسب السؤال الذي تجيب عنه:

• "أريد التحقّق العادي غير المرئي/خانة الاختيار، لكن مُطلَقًا بإيماءتي الخاصة ودون خانة الاختيار الافتراضية." ← أداة خانة الاختيار، أدناه.
• "أريد تحديي التفاعلي الخاص معروضًا في DOM خاصتي، لا لعبة iframe، وأقرّر النجاح/الفشل." ← مضيف اللعبة، أدناه.

اقرأ شغّل لعبتك الخاصة لمكان مسار اللعبة. تحتاج إلى الأداة على صفحتك أصلًا؛ إن لا، فـأضف الأداة أولًا.

حدّ واحد يتشاركه كلاهما: جولة الوضع اليدوي لا تستطيع إرضاء بوّابة لعبة. عنصر خانة الاختيار لا يحرس مفتاحًا البتّة (<caputchin-game> وحده يستطيع)، وجولة <caputchin-game> يدوية لا أثر قابل لإعادة تشغيلها لها، فيرفضها مفتاح محكوم. الوضع اليدوي للمفاتيح غير المحكومة (تحقّق proof-of-work) أو لاستخدام لعبة-فقط.

المسار أ: أداة خانة الاختيار، مُطلِقك الخاص

استخدم هذا حين تريد التحقّق القياسي لكن تريد إطلاقه بنفسك، مثلًا لتشغيل الحلّ فقط حين يرسل الزائر نموذجًا، أو خلف زرّك الخاص بدل خانة الاختيار المدمجة.

1. وسِم العنصر يدويًّا

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

مع trigger="manual"، تكون واجهة خانة الاختيار المدمجة مخفية؛ ينتظر العنصر أن تبدأ الحلّ.

2. ابدأ الحلّ من إيماءتك

يكشف عنصر خانة الاختيار في الوضع اليدوي طريقة واحدة، start():

• start() يركل حلّ proof-of-work، مستبدلًا نقرة خانة الاختيار. صالح مع trigger="manual".

أداة خانة الاختيار لا pass() / fail() لها؛ بمجرّد أن تنادي start()، يحلّ الحلّ نفسه ويبثّ حدث pass. (مقابض الإطلاق/الإجهاض تعيش على مضيف اللعبة، مغطّاة في المسار ب.)

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 كأي أداة أخرى. خادمك الخلفي يتحقّق من ذلك الرمز تمامًا كالمعتاد؛ الوضع اليدوي لا يغيّر شيئًا على الخادم.

المسار ب: مضيف اللعبة، DOM خاصتك

استخدم هذا حين تريد عرض تحديك التفاعلي الخاص في تركيبك الخاص، بدل تحميل لعبة iframe، وتقرّر الحصيلة بنفسك.

1. وسِم العنصر يدويًّا وخصّص تركيبك

ضع trigger="manual" على <caputchin-game> وضع تركيبك الخاص داخله. في كل وضع آخر تتجاهل الأداة أبناء 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({ 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() يتمّ التحقّق ويحقن الرمز؛ ويتحقّق خادمك الخلفي منه بالطريقة نفسها.

تفاعل مع الحصيلة (المساران معًا)

أنصِت لأحداث الأداة لتحديث واجهتك الخاصة:

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

قرار الثقة هو دائمًا تأكيد خادمك الخلفي للرمز، لا الحدث؛ الحدث لتجربة الاستخدام.

ما الذي لا يستطيعه الوضع اليدوي

• حراسة مفتاح موقع. مفتاح بـ اشترِط لعبة مشغّلة لا يمكن إرضاؤه بعنصر خانة الاختيار البتّة، ويرفض <caputchin-game> يدويًّا (يرفع خطأ إعداد عند الإعداد) لأن لا أثر قابلًا لإعادة تشغيله. الوضع اليدوي للمفاتيح غير المحكومة أو لعبة-فقط.
• إعادة تشغيل جولة لعبة مخصّصة. إن احتجت لعبة تحرس، فاعرضها كـ لعبة iframe مستضافة ذاتيًّا وأنتج أثرًا، لا الوضع اليدوي.

انظر أيضًا

• طرائق الأداة وأحداثها: المرجع الكامل لـ start() / pass() / fail() وكل حدث تبثّه.
• لعبة iframe مستضافة ذاتيًّا: لعبة معزولة قابلة لإعادة التشغيل تستطيع الحراسة.
• شغّل لعبتك الخاصة: وضعا التسليم مقارنين.
• تحقّق على خادمك الخلفي: تأكيد الرمز الذي ينتجه النجاح.