أعدّ التحقّق المُستضاف بصندوق اختبار

بنهاية هذا الدرس سيكون لديك نموذج تواصل عامل تُتحقَّق إرسالياته بـ Caputchin وتُسلَّم إلى webhook، وستكون قد شاهدت إرسالية متحقَّقًا منها تحطّ في صندوق اختبار يمكنك فحصه. نستخدم webhook.site كوجهة أولًا، لأنها تعرض لك الحمولة بالضبط التي يرسلها Caputchin قبل أن تلتزم بنقطة وصولك الخاصة.

تحتاج إلى باقة Alpha أو Troop أو Apex (التحقّق المُستضاف ليس على Solo)، ومفتاح موقع، وصفحة يمكنك فيها تحرير HTML النموذج. إن لم تكن قد أضفت الأداة إلى صفحة بعد، فـأضف الأداة أولًا؛ يفترض هذا الدرس <caputchin-widget> عاملًا.

1. احصل على صندوق اختبار

افتح webhook.site في علامة تبويب جديدة. تعطيك فورًا رابطًا فريدًا يبدو مثل https://webhook.site/#!/<uuid>، ورابط تسليم مطابقًا على هيئة https://webhook.site/<uuid>. انسخ رابط التسليم (ذلك بلا #!/). اترك العلامة مفتوحة؛ كل طلب يستقبله يظهر هناك آنيًّا.

هذا الرابط بديل عن webhook الحقيقي خاصتك. عامله كقابل للرمي، لأن أي أحد بالرابط يستطيع قراءة ما يصل.

2. شغّل التحقّق المُستضاف

في لوحة التحكّم، افتح مفتاح الموقع واذهب إلى صفحة التحقّق المُستضاف خاصته.

1. ألصق رابط تسليم webhook.site في حقل الرابط.
2. اترك البريد فارغًا الآن.
3. احفظ.

لست مضطرًّا إلى قلب مبدّل مفعّل بعد. تستخدم الخطوة التالية اختبار التسليم، الذي يعمل على وجهة محفوظة سواء أكان التحقّق المُستضاف مشغّلًا أم لا، فتؤكّد الربط قبل الانطلاق.

3. أرسِل تسليمًا اختباريًّا

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

انتقل إلى علامة webhook.site. يظهر POST جديد خلال ثانية أو ثانيتين. يبدو جسمه بـ JSON هكذا:

{
  "caputchin": {
    "site_key": "cpt_pub_...",
    "session_id": "test_...",
    "game_id": null,
    "score": null,
    "duration_ms": null,
    "verified_at": 1748640000000,
    "test": true
  },
  "form": {
    "email": "test@example.com",
    "message": "Test submission from your Caputchin dashboard."
  }
}

علامة "test": true تخبر معالِجك بأن هذا اختبار لوحة تحكّم، لا زائرًا حقيقيًّا؛ وهي غائبة على الإرساليات الحقيقية. إن رأيت هذه الحمولة، فالوجهة تعمل. إن لم يصل شيء، فأعد فحص أنك نسخت رابط التسليم (لا رابط العارض #!/) وحفظته.

4. وجّه نموذجك إلى المُحوِّل

الآن اجعل إرسالية حقيقية تمرّ عبر Caputchin. التغيير الوحيد على نموذجك هو action خاصته: بدل خادمك الخلفي، يرسل POST إلى رابط المُحوِّل الذي يعرضه لك مفتاح الموقع على صفحة التحقّق المُستضاف.

<form action="https://caputchin.com/api/forward/cpt_pub_..." method="POST">
  <input name="email" type="email" />
  <input name="message" />
  <caputchin-widget sitekey="cpt_pub_..."></caputchin-widget>
  <button type="submit">Send</button>
</form>

لا شيء آخر يتغيّر. ما زالت الأداة تحقن حقل caputchin-token المخفي حين يجتاز الزائر التحدّي؛ يقرأ المُحوِّل ذلك الحقل، ويتحقّق منه، ويزيله قبل تسليم الباقي إلى وجهتك.

5. فعّل التحقّق المُستضاف

عودةً على صفحة التحقّق المُستضاف، اقلب مبدّل مفعّل واحفظ. يرفض المُحوِّل إرساليات مفتاح موقع غير مفعّل، فهذا المبدّل هو ما يجعل الخطوة 4 حيّة.

6. أرسِل النموذج حقًّا

حمّل صفحتك، واملأ النموذج، واجتز التحدّي، وأرسِل. راقب علامة webhook.site: يصل POST ثانٍ، هذه المرة بلا حقل test وببيانات تحقّق وصفية حقيقية.

{
  "caputchin": {
    "site_key": "cpt_pub_...",
    "session_id": "...",
    "game_id": "caputchin/games/leaf-memory",
    "score": 847,
    "duration_ms": 4200,
    "verified_at": 1748640000000
  },
  "form": {
    "email": "visitor@example.com",
    "message": "Hello!"
  }
}

ذلك هو المسار كله: يرسل الزائر، ويتحقّق Caputchin، وتستقبل وجهتك الإرسالية المتحقّق منها فقط. إرسالية تفشل في التحقّق (رمز مفقود، أو منتهٍ، أو مُعاد استخدامه) لا تبلغ وجهتك البتّة.

عامِل كتلة caputchin كما تعامل حُكم خادم خلفي: game_id، وscore، وduration_ms بيانات وصفية يدّعيها العميل لتحليلاتك، لا إشارة ثقة. قرار الثقة هو حقيقة وصول الإرسالية أصلًا. أيٌّ من تلك الثلاثة قد يكون null على إرسالية حقيقية (مثلًا تحقّق بلا لعبة)، فاحرس ضدّ null قبل قراءتها.

7. جرّب وجهة البريد أيضًا

يعطي webhook.site أيضًا كل صندوق عنوان بريد، فتستطيع اختبار تسليم البريد بالطريقة نفسها. على صفحة webhook.site، جِد عنوان بريد صندوقك الفريد وانسخه؛ في وقت الكتابة يبدو مثل <your-inbox-id>@emailhook.site، لكن افحص الصفحة للهيئة الحالية لأن webhook.site يملك تلك التفصيلة. ثم:

1. عودةً على صفحة التحقّق المُستضاف، ألصق ذلك العنوان في حقل البريد.
2. احفظ، واستخدم اختبار التسليم مجدّدًا.

يصل البريد في صندوق webhook.site إلى جانب الطلبات: رسالة عادية تحمل حقول النموذج وتذييلًا يشير إلى أن Caputchin تحقّق من الإرسالية. يُسلَّم البريد عبر مزوّد بريد Caputchin، فقد يستغرق وصوله أطول قليلًا من POST webhook. مع رابط webhook وعنوان بريد مضبوطين، تتوزّع إرسالية واحدة إلى كليهما، وتُحسَب مُسلَّمة إن نجح أيٌّ منهما.

8. استبدل بوجهتك الحقيقية

حين يكون صندوق الاختبار قد أراك ما تتوقّعه، استبدله بوجهتك الخاصة:

• webhook الخاص بك. ضع رابط نقطة وصولك في حقل الرابط. يجب أن يكون رابط https عامًّا؛ يرفض Caputchin الروابط التي تُحلّ إلى عناوين خاصة أو loopback أو بيانات سحابة وصفية، ولا يتّبع عمليات إعادة التوجيه. يستقبل معالِجك شكل JSON أعلاه بالضبط. التسليمات غير موقّعة، فأبقِ الرابط سرّيًّا، لأن سرّيته هي ما يصادق النداء.
• البريد بدلًا، أو إضافةً. ضع عنوانك الخاص في حقل البريد، بالطريقة نفسها التي اختبرته بها أعلاه. تستطيع تشغيل كليهما معًا، مثلًا webhook للمعالجة إضافةً إلى نسخة بريد لنفسك.

أرسِل إرسالية حقيقية أخرى مقابل الوجهة الحيّة للتأكيد، وتكون قد انتهيت.

إلى أين تذهب تاليًا

• إحصاءات التحقّق المُستضاف: راقب صحّة التسليم عبر الزمن.
• التحقّق المُستضاف: المفاهيم، وموقف الخصوصية، وما الذي تُرك عمدًا.
• التحقّق على خادمك الخلفي: البديل إن أضفت خادمًا لاحقًا.