--- type: how-to title: التكامل على جانب العميل summary: كيف تضع الأداة على صفحتك، بوسم script من CDN أو باستيراد npm، وأيّهما تستخدم. --- الأداة حزمة واحدة صغيرة، `@caputchin/widget`، تسجّل العنصرين المخصّصين `` و``. هناك طريقتان لوضعها على صفحتك. اختر بحسب ما إذا كان لموقعك خطوة بناء. العنصران غير متبادلين حين يشترِط مفتاح لعبة. إن كان لمفتاح موقع بوّابة لعبة مشغّلة (إعداد **اشتراط لعبة للتحقّق** خاصته)، فلا يستطيع `` ذو خانة الاختيار المرور عليه ويرفع خطأ `gate-unavailable`؛ ولا يعمل هناك سوى ``. هذا بالتصميم، لأن البوّابة مفروضة في جانب Caputchin. انظر [بوّابة اللعبة](/docs/site-keys/games). ## وسم script‏ (CDN) لا خطوة بناء، صفحة HTML عادية أو مُعرَّضة على الخادم؟ حمّلها مباشرةً من CDN الخاص بـ jsDelivr: ```html ``` الـ `@3` يثبّت الإصدار الأكبر الحالي، فتحصل على الإصلاحات والألعاب الجديدة دون كسر مفاجئ. أسقط ذلك السطر الواحد في `` (أو قُبيل ``)، والعناصر مسجَّلة للصفحة كلها. ## npm‏ (ESM) لديك مُجمِّع (Vite، أو webpack، أو Next.js، وما إليها)؟ ثبّت الحزمة واستوردها مرة واحدة عند الإقلاع: ```bash npm install @caputchin/widget ``` ```js import "@caputchin/widget"; ``` لا يكشف الاستيراد شيئًا لتناديه؛ يعمل لأثره الجانبي في تسجيل العناصر المخصّصة. ضعه عند نقطة دخول تطبيقك كي يعمل قبل أن يُعرَض أي ``. ## أيّهما؟ - **لا خطوة بناء** (HTML عادي، قالب مُعرَّض على الخادم): استخدم **وسم script**. إنه التكامل كله في سطر واحد. - **تطبيق مُجمَّع** (React، وVue، والبقية): استخدم **استيراد npm**. يتأصدر مع ملف القفل خاصتك ويتجنّب طلبًا خارجيًّا يحجب العرض. في كلتا الحالتين، العنصر وكل ما يليه (الرمز المحقون، فحص خادمك) متطابقان. الشيء الوحيد الذي يتغيّر هو طريقة وصول الحزمة. ## انظر أيضًا - [أمثلة تكامل الواجهة](/docs/integration-guides/frontend-examples) للعنصر في كل إطار عمل. - [أضف الأداة إلى موقعك](/docs/getting-started/add-the-widget) للشرح الكامل خطوة بخطوة.