--- title: "CDN / وسم البرنامج النصي" description: "أضف ويدجت الصوت من ThunderPhone إلى أي موقع ويب دون استخدام أداة تجميع" --- يتضمن إصدار CDN مكتبة React داخليًا، لذا يمكنك استخدام الأداة المصغّرة على المواقع الثابتة أو WordPress أو Webflow أو أي صفحة يمكنك فيها إضافة HTML. لا حاجة إلى npm أو أداة تجميع أو إطار عمل. ## عناوين URL لشبكة CDN ```html Latest (recommended) ``` ```html Pinned version ``` عناوين URL الخاصة بـ `latest` هي ما يُنشئه مولّد مقتطفات التضمين في لوحة المعلومات. تُخزَّن مؤقتًا لمدة 5 دقائق وتلتقط الإصدارات المستقرة الجديدة تلقائيًا. مسارات `/widget/vX.Y.Z/` المثبّتة غير قابلة للتغيير وتُخزَّن مؤقتًا على المدى الطويل -- إذا ثبّتَّ إصدارًا، فطابق الإصدار مع إصدار npm ‏`@thunderphone/widget` الذي تطوّر عليه. --- ## الاستخدام الأساسي ```html

``` تُركَّب الأداة المصغّرة داخل العنصر المستهدف وتُعرض على هيئة **شريط ثابت الموضع في إحدى زوايا إطار العرض** (القيمة الافتراضية `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`. عند عدم تعيينه، تُطبَّق اللغة المضبوطة للوكيل. يتطلب `language` ضمن [تجاوزات المتصفح](/ar/guides/embed-web-widget) الخاصة بالمفتاح. | | `voice` | `string` | لا | -- | تجاوز الصوت لكل جلسة -- اسم صوت مثل `maria`. عند عدم تعيينه، يُطبَّق الصوت المضبوط للوكيل. يتطلب `voice` ضمن [تجاوزات المتصفح](/ar/guides/embed-web-widget) الخاصة بالمفتاح. | | `context` | `string` | لا | -- | سياق واقعي للصفحة أو الموقع لكل جلسة يُمرَّر إلى الوكيل. يُقتطع من جانب الخادم إلى 12,000 حرف. يتطلب `context` ضمن [تجاوزات المتصفح](/ar/guides/embed-web-widget) الخاصة بالمفتاح. | | `onConnect` | `() => void` | لا | -- | يُستدعى عند اتصال الجلسة الصوتية. | | `onDisconnect` | `() => void` | لا | -- | يُستدعى عند انتهاء الجلسة. | | `onError` | `(error) => void` | لا | -- | يُستدعى عند حدوث أخطاء. يحتوي الخطأ على حقلي `error` (الرمز) و`message`. | | `ringtone` | `boolean \| string` | لا | `false` | شغّل نغمة رنين أثناء الاتصال. استخدم `true` لنغمة الرنين الافتراضية، أو سلسلة URL لصوت مخصص. | --- ## التنظيف تُرجع `ThunderPhone.mount()` مثيلًا للأداة يتضمن أساليب للتنظيف: ```html ``` يؤدي كل من `unmount()` و`destroy()` الوظيفة نفسها -- إذ يقطعان أي جلسة صوتية نشطة ويزيلان الأداة من DOM. استخدم ما يبدو أوضح في شفرتك. نظّف الأداة دائمًا عند مغادرة الصفحة في تطبيقات الصفحة الواحدة أو عند إزالة العنصر الحاوي. يضمن ذلك قطع اتصال الجلسات الصوتية النشطة بشكل صحيح. --- ## أمثلة ### مظهر داكن بلون مخصص ```html

``` ### موضع مخصص ```html

``` ### مع دوال رد الاتصال للأحداث ```html

``` ### مع نغمة رنين ```html

``` ### باستخدام مرجع عنصر DOM ```html

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

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