ThunderPhone 2.0 متاح الآن.خدمة ذاتية، ابتداءً من 2 سنت/دقيقة.اقرأ الإعلان
ابدأ الآن

Widget

View as Markdown
Open in
ClaudeChatGPTCursor

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

أضف ويدجت الصوت من ThunderPhone إلى أي موقع ويب دون استخدام أداة تجميع

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

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

Latest (recommended)
<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
Pinned version
<!-- 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>

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

<!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:

الخيارالنوعمطلوبالافتراضيالوصف
elementstring | HTMLElementنعم--محدد CSS (مثل '#thunderphone') أو مرجع إلى عنصر DOM.
publishableKeystringنعم--مفتاح API قابل للنشر (pk_live_...). يُحدَّد الوكيل تلقائيًا من إعدادات الأداة المرتبطة بالمفتاح.
theme'light' | 'dark'لا'light'نظام الألوان.
primaryColorstringلا'#000000' (فاتح) / '#ffffff' (داكن)سلسلة ألوان CSS مستخدمة كلون تمييز.
titlestringلا'Voice assistant'النص المعروض في شريط الأداة.
position'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'لا'bottom-right'موضع ثابت ضمن إطار العرض.
apiBasestringلا'https://api.thunderphone.com/v1'تجاوز عنوان URL الأساسي لواجهة API.
languagestringلا--تجاوز اللغة لكل جلسة -- رمز لغة أو إعداد محلي مثل en أو es أو fr-FR. عند عدم تعيينه، تُطبَّق اللغة المضبوطة للوكيل. يتطلب language ضمن تجاوزات المتصفح الخاصة بالمفتاح.
voicestringلا--تجاوز الصوت لكل جلسة -- اسم صوت مثل maria. عند عدم تعيينه، يُطبَّق الصوت المضبوط للوكيل. يتطلب voice ضمن تجاوزات المتصفح الخاصة بالمفتاح.
contextstringلا--سياق واقعي للصفحة أو الموقع لكل جلسة يُمرَّر إلى الوكيل. يُقتطع من جانب الخادم إلى 12,000 حرف. يتطلب context ضمن تجاوزات المتصفح الخاصة بالمفتاح.
onConnect() => voidلا--يُستدعى عند اتصال الجلسة الصوتية.
onDisconnect() => voidلا--يُستدعى عند انتهاء الجلسة.
onError(error) => voidلا--يُستدعى عند حدوث أخطاء. يحتوي الخطأ على حقلي error (الرمز) وmessage.
ringtoneboolean | 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>

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

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

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

ThunderPhone غير معرّف

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

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

أضف نطاقك إلى النطاقات المسموح بها للأداة على صفحة عناصر الويب في app.thunderphone.com. لا يُسمح بـ localhost تلقائيًا في بيئة الإنتاج؛ أضِفه إلى القائمة للاختبار محليًا.

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

التنسيق

خصّص مظهر الأداة باستخدام خصائص CSS المخصصة.

مكوّن React

هل تستخدم React؟ تكامل المكوّن أبسط.