انتقل من Cloudflare Turnstile
يستخدم Caputchin النموذج ذا الجزأين نفسه كـ Cloudflare Turnstile، أداة على الصفحة تنتج رمزًا، وفحص على الخادم يؤكّده، فالانتقال أساسًا استبدال آليّ، لا إعادة كتابة. Turnstile الأقرب بين المزوّدين الشائعين إلى Caputchin، لأن كليهما يعيد نجاح/فشل موثوقًا بدل نتيجة مخاطرة، فلا عتبة لإعادة ضبطها. يعطي هذا الدليل القبل-والبعد لكل قطعة.
إن لم تكن قد أنشأت حساب Caputchin ومفتاح موقع بعد، فـأنشئ حسابك أولًا؛ ستحتاج مفتاحًا عامًّا (cpt_pub_...) للصفحة وسرًّا (cpt_sec_...) لخادمك الخلفي، التقسيم نفسه كمفتاح موقع Turnstile ومفتاحه السرّي.
النموذج الذهني دون تغيير
كل ما بنيته أصلًا حول Turnstile، اعرض أداة، واجمع رمزًا، وأرسِله POST إلى خادمك، وتحقّق منه قبل أن تثق بالطلب، يبقى. الأسماء ونقاط الوصول وحدها تتغيّر.
1. استبدل مقتطف العميل
| Turnstile | Caputchin | |
|---|---|---|
| السكربت | <script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer> | <script src="https://cdn.jsdelivr.net/npm/@caputchin/widget@3/dist/widget.js"> |
| العنصر | <div class="cf-turnstile" data-sitekey="..."> | <caputchin-widget sitekey="cpt_pub_..."> |
| حقل الرمز في نموذج | cf-turnstile-response (محقون تلقائيًّا) | caputchin-token (محقون تلقائيًّا) |
| قراءة الرمز في JS | turnstile.getResponse() | حدث pass detail.token |
كـ Turnstile، تحقن أداة Caputchin حقل رمز مخفيًّا تلقائيًّا في النموذج الذي تجلس فيه، فإن كان نموذجك يرسل POST عاديًّا أصلًا، فلا تغيّر سوى العنصر واسم الحقل الذي يقرؤه خادمك الخلفي. انظر أضف الأداة لإعداد العميل الكامل وخيار CDN مقابل npm.
2. استبدل تحقّق الخادم
هنا الأقرب بينهما، شكلا الطلب والاستجابة يصطفّان حقلًا بحقل تقريبًا.
| Turnstile | Caputchin | |
|---|---|---|
| نقطة الوصول | POST https://challenges.cloudflare.com/turnstile/v0/siteverify | POST https://caputchin.com/api/v1/siteverify |
| حقول الطلب | secret، وresponse | secret، وresponse (متطابق) |
| الاستجابة | { success, challenge_ts, hostname, "error-codes", action, cdata } | { success, challenge_ts, hostname, error-codes } |
| قاعدة الثقة | تصرّف فقط إن success === true | تصرّف فقط إن success === true (متطابق) |
في معظم المنظومات التغيير الوحيد لكود تحقّقك هو الرابط وقيمة السرّ؛ وكلاهما يتفرّع على success أصلًا، فلا عتبة نتيجة لنقلها. Turnstile يقبل أيضًا بـ JSON لنداء التحقّق، تمامًا كـ Caputchin، فشكل الجسم يحمل دون تغيير. مرجع الطلب/الاستجابة الكامل، بما فيه رموز الأخطاء، على تحقّق من رمز على خادمك الخلفي؛ ومقتطفات أطر العمل في أمثلة الخادم الخلفي.
إن كان تكامل Turnstile لديك يقرأ action أو cdata من الاستجابة، فلاحظ أن لا مكافئ مباشر لها في Caputchin؛ تلك وسوم خاصة بـ Turnstile تضبطها على الأداة. بيانات Caputchin المماثلة الوصفية (أي لعبة لُعِبت، ونتيجتها) تقيم في كتلة platform للاستجابة وهي للعلم فقط.
ما الذي يحمل، وما الذي يتحسّن
- ما زال نجاح/فشل نظيف. تبقي أبسط قاعدة ثقة ممكنة،
if (success)، بلا احتمال ولا عتبة لصيانتها. - موقف الخصوصية الذي اخترت Turnstile لأجله، محفوظًا. Caputchin لا يجمع IP، ولا User-Agent، ولا بصمة، ولا قياسًا سلوكيًّا؛ فالبروتوكول لا مكان فيه لمعرّف زائر. انظر الفلسفة.
- لعبة اختيارية. بدل تحدٍّ غير مرئيّ أو مُدار، تستطيع تحويل التحقّق إلى لعبة قصيرة يلعبها زوّارك فعلًا، وهي الجزء الذي يصمد أمام حلّالات الذكاء الاصطناعي. انظر أضف لعبة.
- CSP صارم يبقى صارمًا. يعمل Caputchin تحت Content-Security-Policy ضيّقة؛ تسمح ببضعة أصول بدل تخفيف سياستك. انظر كيف يعزل Caputchin الألعاب.
مزالق
- مفتاحان، بيتان. المفتاح العام (
cpt_pub_...) يذهب على الصفحة؛ والسرّ (cpt_sec_...) يبقى على الخادم فقط، انضباط Turnstile نفسه بالضبط. لا تشحن السرّ إلى المتصفّح. - الرمز للاستخدام مرة واحدة. كـ Turnstile، يتحقّق الرمز مرة. لا تخبّئه ولا تعد تشغيله.
- غيّر اسم الحقل الذي يقرؤه خادمك الخلفي. الحقل المخفي
caputchin-token، لاcf-turnstile-response، فوات شائع بسطر واحد. - لا
action/cdata. إن تفرّعت عليها، فانقل ذلك المنطق مكانًا آخر؛ Caputchin لا يحملها.
انظر أيضًا
- أضف الأداة: إعداد العميل الكامل.
- تحقّق من رمز على خادمك الخلفي: مرجع
siteverifyالموثوق. - أمثلة الخادم الخلفي: نداء التحقّق بكل لغة.
- أضف لعبة: حوّل التحقّق إلى لعبة.