التكامل على جانب الخادم

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

تحتاج إلى خادم خلفي قادر على إجراء طلب صادر، وسرّ مفتاح موقعك (cpt_sec_...) متاحًا هناك، لا في المتصفّح أبدًا.

1. اقرأ الرمز

حين يرسل النموذج، يستقبل معالِجك حقلًا إضافيًّا واحدًا إلى جانب حقولك: caputchin-token. حقنته الأداة في النموذج حين اجتاز الزائر التحدّي.

2. أكّده بـ /siteverify

أرسِل POST بالرمز وسرّك. الطلب والاستجابة مصاغان على هيئة siteverify الخاص بـ reCAPTCHA، فينتقل تكامل قائم بقليل من التغيير:

POST https://caputchin.com/api/v1/siteverify
Content-Type: application/json

{ "secret": "cpt_sec_...", "response": "<caputchin-token>" }

// Node 18+
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) {
  // reject the submission
}

النداء نفسه بلغات أخرى موجود في أمثلة تكامل الخادم الخلفي.

3. اقرأ الاستجابة

{
  "success": true,
  "error-codes": [],
  "platform": { "game_id": "caputchin/games/leaf-memory", "score": 847, "duration_ms": 4200 }
}

• success هو الشيء الوحيد الذي تتفرّع عليه. true تعني أن زائرًا حقيقيًّا اجتاز التحدّي؛ ثِق بالطلب. false تعني أسقطه.
• error-codes تظهر حين تكون success بقيمة false، مسمّيةً ما الذي أخفق (رمز مفقود، أو منتهٍ، أو مستخدَم بالفعل، وهكذا).
• platform بيانات وصفية يدّعيها العميل (أيّ لعبة، والنتيجة، والمدة). قابلة لأن تكون فارغة وليست إشارة أمان. سجّلها للتحليلات إن شئت، لكن لا تحكّم الثقة بالنتيجة أبدًا.

القواعد التي تحميك

• الاستخدام لمرة واحدة. يتحقّق الرمز مرة. إرسال الرمز نفسه ثانيةً يعيد success: false، فلا حاجة لأن تتتبّع إعادات التشغيل بنفسك.
• قصير العمر. ينتهي الرمز بعد عشر دقائق من إصداره، فتحقّق منه أثناء معالجة الإرسالية، لا في مهمة مؤجَّلة.
• السرّ يبقى على الخادم. لا يذهب إلى المتصفّح أبدًا، وهو ما يصادق على النداء.

أخطاء شائعة

• التحقّق على جانب العميل. حدث pass ووجود الرمز للتجربة فقط. كل قرار ثقة يحدث هنا، على جانب الخادم، بسرّك.
• التحكيم بـ score. إنه بيانات وصفية، لا قيمة ثقة.

انظر أيضًا

• أمثلة تكامل الخادم الخلفي لهذا النداء بلغتك.
• التحقّق المُستضاف لتخطّي الخادم الخلفي كليًّا.