> ## Documentation Index > Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt > Use this file to discover all available pages before exploring further. # CDN / وسم البرنامج النصي > أضف ويدجت الصوت من ThunderPhone إلى أي موقع ويب دون استخدام أداة تجميع يتضمن إصدار CDN مكتبة React داخليًا، لذا يمكنك استخدام الأداة المصغّرة على المواقع الثابتة أو WordPress أو Webflow أو أي صفحة يمكنك فيها إضافة HTML. لا حاجة إلى npm أو أداة تجميع أو إطار عمل. ## عناوين URL لشبكة CDN ```html Latest (recommended) theme={null} ``` ```html Pinned version theme={null} ``` عناوين URL الخاصة بـ `latest` هي ما يُنشئه مولّد مقتطفات التضمين في لوحة المعلومات. تُخزَّن مؤقتًا لمدة 5 دقائق وتلتقط الإصدارات المستقرة الجديدة تلقائيًا. مسارات `/widget/vX.Y.Z/` المثبّتة غير قابلة للتغيير وتُخزَّن مؤقتًا على المدى الطويل -- إذا ثبّتَّ إصدارًا، فطابق الإصدار مع إصدار npm ‏`@thunderphone/widget` الذي تطوّر عليه. *** ## الاستخدام الأساسي ```html theme={null}

``` تُركَّب الأداة المصغّرة داخل العنصر المستهدف وتُعرض على هيئة **شريط ثابت الموضع في إحدى زوايا إطار العرض** (القيمة الافتراضية `bottom-right`، ويتحكم به الخيار `position`). عنصر التركيب هو جذر React فقط -- ولا يؤثر موقعه في الصفحة في موضع ظهور الأداة المصغّرة. *** ## خيارات التركيب يقبل `ThunderPhone.mount()` الخيارات نفسها التي يقبلها مكوّن React، إضافةً إلى الخاصية `element`: | الخيار | النوع | مطلوب | الافتراضي | الوصف | | ---------------- | -------------------------------------------------------------- | ----- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `element` | `string \| HTMLElement` | نعم | -- | محدد CSS (مثل `'#thunderphone'`) أو مرجع إلى عنصر DOM. | | `publishableKey` | `string` | نعم | -- | مفتاح API قابل للنشر (`pk_live_...`). يُحدَّد الوكيل الصوتي تلقائيًا من إعدادات الأداة المصغّرة الخاصة بالمفتاح. | | `theme` | `'light' \| 'dark'` | لا | `'light'` | نظام الألوان. | | `primaryColor` | `string` | لا | `'#000000'` (فاتح) / `'#ffffff'` (داكن) | سلسلة ألوان CSS تُستخدم كلون تمييز. | | `title` | `string` | لا | `'Voice assistant'` | النص المعروض في شريط الأداة المصغّرة. | | `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | لا | `'bottom-right'` | موضع ثابت في إطار العرض. | | `apiBase` | `string` | لا | `'https://api.thunderphone.com/v1'` | تجاوز عنوان URL الأساسي لـ API. | | `language` | `string` | لا | -- | تجاوز اللغة لكل جلسة -- رمز لغة أو إعداد محلي مثل `en` أو `es` أو `fr-FR`. عند عدم تعيينه، تُطبَّق اللغة المُعدّة للوكيل الصوتي. | | `voice` | `string` | لا | -- | تجاوز الصوت لكل جلسة -- اسم صوت مثل `maria`. عند عدم تعيينه، يُطبَّق الصوت المُعدّ للوكيل الصوتي. | | `context` | `string` | لا | -- | سياق واقعي لكل جلسة عن الصفحة أو الموقع يُمرَّر إلى الوكيل الصوتي. يُقتطع من جهة الخادم إلى 12,000 حرف. | | `onConnect` | `() => void` | لا | -- | يُستدعى عند اتصال الجلسة الصوتية. | | `onDisconnect` | `() => void` | لا | -- | يُستدعى عند انتهاء الجلسة. | | `onError` | `(error) => void` | لا | -- | يُستدعى عند حدوث أخطاء. يحتوي الخطأ على الحقلين `error` (الرمز) و`message`. | | `ringtone` | `boolean \| string` | لا | `false` | شغّل نغمة رنين أثناء الاتصال. استخدم `true` لنغمة الرنين الافتراضية، أو سلسلة URL لصوت مخصص. | *** ## التنظيف تُرجع `ThunderPhone.mount()` مثيلًا للأداة يتضمن أساليب للتنظيف: ```html theme={null} ``` يؤدي كل من `unmount()` و`destroy()` الوظيفة نفسها -- إذ يقطعان أي جلسة صوتية نشطة ويزيلان الأداة من DOM. استخدم ما يبدو أوضح في شفرتك. نظّف الأداة دائمًا عند مغادرة الصفحة في تطبيقات الصفحة الواحدة أو عند إزالة العنصر الحاوي. يضمن ذلك قطع اتصال الجلسات الصوتية النشطة بشكل صحيح. *** ## أمثلة ### مظهر داكن بلون مخصص ```html theme={null}

``` ### موضع مخصص ```html theme={null}

``` ### مع دوال رد الاتصال للأحداث ```html theme={null}

``` ### مع نغمة رنين ```html theme={null}

``` ### باستخدام مرجع عنصر DOM ```html theme={null}

``` ### تكامل WordPress / CMS أضف هذا إلى كتلة HTML مخصصة أو إلى تذييل المظهر الخاص بك: ```html theme={null} ``` يمكن وضع `

` في أي مكان -- فهو مجرد نقطة تحميل. تُعرض الأداة نفسها كتراكب ثابت في إحدى زوايا إطار العرض (يُحدد عبر خيار `position`) ولا تتدفق مع المحتوى المحيط. *** ## استكشاف الأخطاء وإصلاحها تأكد من تحميل ملفَّي CSS وJS. تحقّق من وحدة تحكم المتصفح بحثًا عن أخطاء الشبكة. تحقّق من وجود العنصر المستهدف في DOM قبل استدعاء `ThunderPhone.mount()`. لم يتم تحميل البرنامج النصي بعد. تأكد من ظهور وسم `