---
type: how-to
title: انتقل من reCAPTCHA
summary: "استبدل reCAPTCHA بـ Caputchin بأدنى تغييرات: الشكل ذو الجزأين نفسه (أداة عميل إضافةً إلى تحقّق على الخادم) يقابل واحدًا-بواحد تقريبًا، وإليك القبل-والبعد لكل قطعة بالضبط."
---

يستخدم Caputchin النموذج ذا الجزأين نفسه كـ reCAPTCHA، أداة على الصفحة تنتج رمزًا، وفحص على الخادم يؤكّده، فالانتقال أساسًا استبدال آليّ، لا إعادة كتابة. تبادل الخادم خصوصًا يعكس شكل `siteverify` الخاص بـ reCAPTCHA عمدًا. يعطي هذا الدليل القبل-والبعد لكل قطعة.

إن لم تكن قد أنشأت حساب Caputchin ومفتاح موقع بعد، فـ[أنشئ حسابك](/docs/getting-started/create-your-account) أولًا؛ ستحتاج **مفتاحًا عامًّا** (`cpt_pub_...`) للصفحة و**سرًّا** (`cpt_sec_...`) لخادمك الخلفي، التقسيم نفسه كمفتاح موقع reCAPTCHA ومفتاحه السرّي.

## النموذج الذهني دون تغيير

```mermaid
flowchart LR
  A["الأداة على صفحتك"] -->|رمز| B["نموذجك / طلبك"]
  B -->|رمز| C["خادمك الخلفي"]
  C -->|سرّ + رمز| D["نقطة وصول siteverify"]
  D -->|نجح؟| C
```

كل ما بنيته أصلًا حول reCAPTCHA، اعرض أداة، واجمع رمزًا، وأرسِله POST إلى خادمك، وتحقّق منه قبل أن تثق بالطلب، يبقى. الأسماء ونقاط الوصول وحدها تتغيّر.

## 1. استبدل مقتطف العميل

| | reCAPTCHA (v2 خانة اختيار) | Caputchin |
|---|---|---|
| السكربت | `<script src="https://www.google.com/recaptcha/api.js" async defer>` | `<script src="https://cdn.jsdelivr.net/npm/@caputchin/widget@3/dist/widget.js">` |
| العنصر | `<div class="g-recaptcha" data-sitekey="...">` | `<caputchin-widget sitekey="cpt_pub_...">` |
| حقل الرمز في نموذج | `g-recaptcha-response` (محقون تلقائيًّا) | `caputchin-token` (محقون تلقائيًّا) |
| قراءة الرمز في JS | `grecaptcha.getResponse()` | [حدث `pass`](/docs/references/widget-methods-and-events) `detail.token` |

كـ reCAPTCHA، تحقن أداة Caputchin **حقل رمز مخفيًّا تلقائيًّا** في النموذج الذي تجلس فيه، فإن كان نموذجك يرسل POST عاديًّا أصلًا، فلا تغيّر سوى العنصر واسم الحقل الذي يقرؤه خادمك الخلفي. انظر [أضف الأداة](/docs/getting-started/add-the-widget) لإعداد العميل الكامل و[خيار CDN مقابل npm](/docs/integration-guides/cdn).

## 2. استبدل تحقّق الخادم

هنا الأقرب بينهما، شكلا الطلب والاستجابة يصطفّان حقلًا بحقل تقريبًا.

| | reCAPTCHA | Caputchin |
|---|---|---|
| نقطة الوصول | `POST https://www.google.com/recaptcha/api/siteverify` | `POST https://verify.caputchin.com/v1/siteverify` |
| حقول الطلب | `secret`، و`response` | `secret`، و`response` (متطابق) |
| الاستجابة | `{ success, challenge_ts, hostname, "error-codes" }` | `{ success, challenge_ts, hostname, error-codes, score? }` |
| قاعدة الثقة | تصرّف فقط إن `success === true` | تصرّف فقط إن `success === true` (متطابق) |

في معظم المنظومات التغيير الوحيد لكود تحقّقك هو الرابط وقيمة السرّ. مرجع الطلب/الاستجابة الكامل، بما فيه رموز الأخطاء، على [تحقّق من رمز على خادمك الخلفي](/docs/integration-guides/verify-on-your-backend)؛ ومقتطفات أطر العمل في [أمثلة الخادم الخلفي](/docs/integration-guides/backend-examples).

## 3. اربط النتيجة، إن استخدمت reCAPTCHA v3

يعيد reCAPTCHA v3 نتيجة `score` (من 0.0 إلى 1.0) ويطلب منك اختيار عتبة، فأنت تخمّن كم بدا طلب بشريًّا. Caputchin **لا** يعمل هكذا: `success` نجاح/فشل موثوق، لأن التحقّق اجتيز فعلًا (فحص proof-of-work، أو [جولة لعبة معاد اشتقاقها على الخادم](/docs/understanding-caputchin/gaming-anti-cheat))، لا احتمالًا.

إن كان كودك `if (data.score >= 0.5)`، فاستبدله بـ `if (data.success)`. حقل `score` في Caputchin موجود فقط لجولات الألعاب وهو نتيجة **اللعبة** (للعلم، للوحات نتائجك الخاصة)، لا احتمال-روبوت أبدًا، فلا تحكّم الوصول به.

## ما الذي يتحسّن في النقلة

- **لا جمع بيانات زائر.** reCAPTCHA ينمّط زوّارك؛ وCaputchin لا يجمع IP، ولا User-Agent، ولا بصمة، ولا قياسًا سلوكيًّا، فالبروتوكول لا مكان فيه لمعرّف زائر. انظر [الفلسفة](/docs/understanding-caputchin/philosophy).
- **أداة واحدة، لا v2-مقابل-v3.** لا منتج غير-مرئي/نتيجة منفصل لتختار بينهما؛ عنصر واحد يغطّي خانة الاختيار واللعبة الاختيارية.
- **لعبة اختيارية.** بدل شبكة إشارات مرور، تستطيع تحويل التحقّق إلى لعبة قصيرة يلعبها زوّارك فعلًا. انظر [أضف لعبة](/docs/getting-started/add-a-game).
- **CSP صارم يبقى صارمًا.** يعمل Caputchin تحت Content-Security-Policy ضيّقة؛ تسمح ببضعة أصول بدل تخفيف سياستك. انظر [كيف يعزل Caputchin الألعاب](/docs/understanding-caputchin/game-sandboxing#the-csp-you-set-on-your-own-page).

## مزالق

- **مفتاحان، بيتان.** المفتاح العام (`cpt_pub_...`) يذهب على الصفحة؛ والسرّ (`cpt_sec_...`) يبقى على الخادم فقط، انضباط reCAPTCHA نفسه بالضبط. لا تشحن السرّ إلى المتصفّح.
- **الرمز للاستخدام مرة واحدة.** كـ reCAPTCHA، يتحقّق الرمز مرة. لا تخبّئه ولا تعد تشغيله.
- **غيّر اسم الحقل الذي يقرؤه خادمك الخلفي.** الحقل المخفي `caputchin-token`، لا `g-recaptcha-response`، فوات شائع بسطر واحد.

## انظر أيضًا

- [أضف الأداة](/docs/getting-started/add-the-widget): إعداد العميل الكامل.
- [تحقّق من رمز على خادمك الخلفي](/docs/integration-guides/verify-on-your-backend): مرجع `siteverify` الموثوق.
- [أمثلة الخادم الخلفي](/docs/integration-guides/backend-examples): نداء التحقّق بكل لغة.
- [أضف لعبة](/docs/getting-started/add-a-game): حوّل التحقّق إلى لعبة.