CDN / وسم البرنامج النصي

يتضمن إصدار CDN مكتبة React داخليًا، لذا يمكنك استخدام الأداة المصغّرة على المواقع الثابتة أو WordPress أو Webflow أو أي صفحة يمكنك فيها إضافة HTML. لا حاجة إلى npm أو أداة تجميع أو إطار عمل.

عناوين URL لشبكة CDN

<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>

<!-- Each stable release also publishes an immutable /widget/vX.Y.Z/ path
     matching the @thunderphone/widget npm version (v1.1.2 at the time of
     writing). If you pin, you own updating the URL for new releases. -->
<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/v1.1.2/style.css" />
<script src="https://cdn.thunderphone.com/widget/v1.1.2/widget.js"></script>

عناوين URL الخاصة بـ latest هي ما يُنشئه مولّد مقتطفات التضمين في لوحة المعلومات. تُخزَّن مؤقتًا لمدة 5 دقائق وتلتقط الإصدارات المستقرة الجديدة تلقائيًا. مسارات /widget/vX.Y.Z/ المثبّتة غير قابلة للتغيير وتُخزَّن مؤقتًا على المدى الطويل — إذا ثبّتَّ إصدارًا، فطابق الإصدار مع إصدار npm ‏@thunderphone/widget الذي تطوّر عليه.

الاستخدام الأساسي

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
</head>
<body>

  <div id="thunderphone"></div>

  <script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
  <script>
    ThunderPhone.mount({
      element: '#thunderphone',
      publishableKey: 'pk_live_your_publishable_key',
    })
  </script>

</body>
</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`. عند عدم تعيينه، تُطبَّق اللغة المُعدّة للوكيل الصوتي.
`voice`	`string`	لا	—	تجاوز الصوت لكل جلسة — اسم صوت مثل `maria`. عند عدم تعيينه، يُطبَّق الصوت المُعدّ للوكيل الصوتي.
`context`	`string`	لا	—	سياق واقعي لكل جلسة عن الصفحة أو الموقع يُمرَّر إلى الوكيل الصوتي. يُقتطع من جهة الخادم إلى 12,000 حرف.
`onConnect`	`() => void`	لا	—	يُستدعى عند اتصال الجلسة الصوتية.
`onDisconnect`	`() => void`	لا	—	يُستدعى عند انتهاء الجلسة.
`onError`	`(error) => void`	لا	—	يُستدعى عند حدوث أخطاء. يحتوي الخطأ على الحقلين `error` (الرمز) و`message`.
`ringtone`	`boolean \| string`	لا	`false`	شغّل نغمة رنين أثناء الاتصال. استخدم `true` لنغمة الرنين الافتراضية، أو سلسلة URL لصوت مخصص.

التنظيف

تُرجع ThunderPhone.mount() مثيلًا للأداة يتضمن أساليب للتنظيف:

<script>
  var widget = ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
  })

  // Later, when you want to remove the widget:
  widget.unmount()

  // Or equivalently:
  widget.destroy()
</script>

يؤدي كل من unmount() وdestroy() الوظيفة نفسها — إذ يقطعان أي جلسة صوتية نشطة ويزيلان الأداة من DOM. استخدم ما يبدو أوضح في شفرتك.

نظّف الأداة دائمًا عند مغادرة الصفحة في تطبيقات الصفحة الواحدة أو عند إزالة العنصر الحاوي. يضمن ذلك قطع اتصال الجلسات الصوتية النشطة بشكل صحيح.

أمثلة

مظهر داكن بلون مخصص

<div id="thunderphone"></div>

<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
<script>
  ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
    theme: 'dark',
    primaryColor: '#8b5cf6',
    title: 'Talk to our AI',
  })
</script>

موضع مخصص

<div id="thunderphone"></div>

<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
<script>
  ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
    position: 'bottom-left',
  })
</script>

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

<div id="thunderphone"></div>

<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
<script>
  ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
    onConnect: function () {
      console.log('Call started')
    },
    onDisconnect: function () {
      console.log('Call ended')
    },
    onError: function (error) {
      console.error('Widget error:', error.error, error.message)
    },
  })
</script>

مع نغمة رنين

<div id="thunderphone"></div>

<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
<script>
  ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
    ringtone: true, // or a custom URL: 'https://example.com/ringtone.mp3'
  })
</script>

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

<div id="thunderphone"></div>

<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
<script>
  var container = document.getElementById('thunderphone')

  ThunderPhone.mount({
    element: container,
    publishableKey: 'pk_live_your_publishable_key',
  })
</script>

تكامل WordPress / CMS

أضف هذا إلى كتلة HTML مخصصة أو إلى تذييل المظهر الخاص بك:

<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>

<div id="thunderphone-widget"></div>
<script>
  ThunderPhone.mount({
    element: '#thunderphone-widget',
    publishableKey: 'pk_live_your_publishable_key',
  })
</script>

يمكن وضع <div> في أي مكان — فهو مجرد نقطة تحميل. تُعرض الأداة نفسها كتراكب ثابت في إحدى زوايا إطار العرض (يُحدد عبر خيار position) ولا تتدفق مع المحتوى المحيط.

استكشاف الأخطاء وإصلاحها

لا تظهر الأداة

تأكد من تحميل ملفَّي CSS وJS. تحقّق من وحدة تحكم المتصفح بحثًا عن أخطاء الشبكة. تحقّق من وجود العنصر المستهدف في DOM قبل استدعاء ThunderPhone.mount().

ThunderPhone غير معرّف

لم يتم تحميل البرنامج النصي بعد. تأكد من ظهور وسم <script> الخاص بـ widget.js قبل استدعاء التركيب، أو ضَع استدعاء التركيب داخل مستمع DOMContentLoaded.

خطأ: النطاق غير مسموح

أضف نطاقك إلى قائمة النطاقات المسموح بها في إعدادات المطورين على app.thunderphone.com. تذكّر أن localhost مسموح به دائمًا.

Widget

CDN / وسم البرنامج النصي

عناوين URL لشبكة CDN

الاستخدام الأساسي

خيارات التركيب

التنظيف

أمثلة

مظهر داكن بلون مخصص

موضع مخصص

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

مع نغمة رنين

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

تكامل WordPress / CMS

استكشاف الأخطاء وإصلاحها

الخطوات التالية

التنسيق

مكوّن React

​عناوين URL لشبكة CDN

​الاستخدام الأساسي

​خيارات التركيب

​التنظيف

​أمثلة

​مظهر داكن بلون مخصص

​موضع مخصص

​مع دوال رد الاتصال للأحداث

​مع نغمة رنين

​باستخدام مرجع عنصر DOM

​تكامل WordPress / CMS

​استكشاف الأخطاء وإصلاحها

​الخطوات التالية

التنسيق

مكوّن React

عناوين URL لشبكة CDN

الاستخدام الأساسي

خيارات التركيب

التنظيف

أمثلة

مظهر داكن بلون مخصص

موضع مخصص

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

مع نغمة رنين

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

تكامل WordPress / CMS

استكشاف الأخطاء وإصلاحها

الخطوات التالية