CDN / وسم البرنامج النصي
أضف ويدجت الصوت من ThunderPhone إلى أي موقع ويب دون استخدام أداة تجميع
يتضمن إصدار 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>الاستخدام الأساسي
<!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>استكشاف الأخطاء وإصلاحها
لا تظهر الأداة
تأكد من تحميل ملفَّي CSS وJS. تحقّق من وحدة تحكم المتصفح بحثًا عن أخطاء الشبكة. تحقّق من وجود العنصر المستهدف في DOM قبل استدعاء ThunderPhone.mount().
ThunderPhone غير معرّف
لم يتم تحميل البرنامج النصي بعد. تأكد من ظهور وسم <script> الخاص بـ widget.js قبل استدعاء التركيب، أو ضَع استدعاء التركيب داخل مستمع DOMContentLoaded.
خطأ: النطاق غير مسموح
أضف نطاقك إلى قائمة النطاقات المسموح بها في إعدادات المطورين على app.thunderphone.com. تذكّر أن localhost مسموح به دائمًا.