أضف الأداة إلى موقعك

صار لديك مفتاح BananaSeed العام من الدرس السابق. الآن نضع الأداة على نموذج تواصل React، ونشاهد لوحة التحكّم تؤكّد أن زائرًا حقيقيًّا اجتازه، ثم نضيف نداء الخادم الواحد الذي يحوّل ذلك إلى حماية حقيقية.

ما الذي سيكون لديك في النهاية

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

1. أضف الأداة إلى نموذج React الخاص بك

ثبّت الحزمة. تسجّل عنصر <caputchin-widget> (وعنصر <caputchin-game> للدرس التالي):

npm install @caputchin/widget

استورده مرة واحدة عند الإقلاع، مثلًا عند نقطة دخول تطبيقك (main.jsx):

import "@caputchin/widget";

الآن أسقط الأداة في نموذج تواصل BananaSeed. حين تُجتاز خانة الاختيار، تضيف الأداة حقل caputchin-token مخفيًّا إلى النموذج، فتقرأه عند الإرسال تمامًا مثل حقولك الخاصة. استبدل cpt_pub_... بمفتاحك العام:

export function ContactForm() {
  async function handleSubmit(e) {
    e.preventDefault();
    const data = new FormData(e.currentTarget);
    await fetch("/api/contact", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({
        email: data.get("email"),
        message: data.get("message"),
        token: data.get("caputchin-token"),
      }),
    });
  }

  return (
    <form onSubmit={handleSubmit}>
      <input name="email" type="email" required />
      <textarea name="message" required />
      <caputchin-widget sitekey="cpt_pub_..." />
      <button type="submit">Send</button>
    </form>
  );
}

على صفحة HTML عادية بلا خطوة بناء، أو داخل تطبيق جوّال أصلي؟ انظر تكامل وسم script‏ (CDN) ودليل تطبيقات الجوّال.

2. شاهده يتحقّق

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

3. أكّده في لوحة التحكّم

عودةً إلى لوحة التحكّم، افتح فريقك وانقر داخل مفتاح موقعك. تعرض إحصاءاته قمعًا: الجلسات المبدوءة، والمُكمَّلة على العميل، والمُتحقَّق منها على الخادم، والتهديدات المحجوبة. حدّث الصفحة؛ الجلسات المبدوءة والمُكمَّلة على العميل تعرضان الآن كلتاهما 1 على الأقل. تلك زيارتك: حُمّلت الأداة (بُدئت) وحُلّ التحدّي في المتصفّح (أُكمل على العميل)، دون أي خادم خلفي معنيّ على الإطلاق.

المُتحقَّق منها على الخادم ما زالت 0، لأن لا شيء على خادمك فحص رمزًا بعد. تلك الفجوة هي الخطوة التالية.

أداتك حيّة، ولوحة التحكّم تسجّل بالفعل تحقّقات حقيقية، قبل أن تكتب سطرًا من كود الخادم الخلفي. 🎉

4. تحقّق من الرمز على خادمك الخلفي

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

import express from "express";

const app = express();
app.use(express.json());

app.post("/api/contact", async (req, res) => {
  const { email, message, token } = req.body;

  const verdict = await fetch("https://caputchin.com/api/v1/siteverify", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      secret: process.env.CAPUTCHIN_SECRET,
      response: token,
    }),
  }).then((r) => r.json());

  if (!verdict.success) {
    return res.status(400).json({ error: "Could not verify you are human." });
  }

  // Verified. Handle the real message: store it, email it, whatever you do.
  res.json({ ok: true });
});

app.listen(3001);

فحص verdict.success ذاك هو بيت القصيد: روبوت يرسل POST مباشرةً إلى /api/contact لا يحمل رمزًا، فترجع success بقيمة false، وتُسقط الرسالة قبل أن تمسّها أنت أصلًا.

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

5. أكّد فحص الخادم

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

لقراءة ذلك القمع بالاتّجاه الآخر (ما تخبرك به الفجوات بين العدّادات عن تسرّب الزوّار وأخطاء التكامل)، انظر الإحصاءات والجلسات.

صار نموذج تواصلك محميًّا حقًّا الآن: كل إرسالية تُفحَص على خادمك، والروبوتات بلا رمز تُصدّ. 🎉

ما الذي حدث للتوّ

التالي

خانة الاختيار تعمل. الآن الجزء الممتع: استبدلها بلعبة حقيقية قابلة للّعب، دون تغيير في خادمك الخلفي.

تابع إلى أضف لعبة من المتجر.