Open in

مكوّن React

تضمين ودجت ThunderPhone الصوتي في تطبيق React

يعرض المكوّن ThunderPhoneWidget شريط مكالمات بتصميم زجاجي مع عناصر تحكم مدمجة لكتم الصوت وإنهاء المكالمة وعرض حالة الاتصال. وهو أسرع طريقة لإضافة الذكاء الاصطناعي الصوتي إلى تطبيق React.

التثبيت

npm install @thunderphone/widget

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

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
    />
  )
}

الخصائص

يقبل المكوّن الخصائص التالية عبر ThunderPhoneWidgetProps:

الخاصية	النوع	مطلوب	الافتراضي	الوصف
`publishableKey`	`string`	نعم	--	مفتاح واجهة برمجة التطبيقات القابل للنشر (`pk_live_...`) من أدوات الويب في لوحة التحكم. يُحدَّد الوكيل تلقائيًا من إعدادات الأداة المرتبطة بالمفتاح.
`theme`	`'light' \| 'dark'`	لا	`'light'`	نظام الألوان. يطبّق الفئة `tp--light` أو `tp--dark` على جذر الأداة.
`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 الأساسي لواجهة برمجة التطبيقات.
`language`	`string`	لا	--	تجاوز اللغة لكل جلسة -- رمز لغة أو إعدادات محلية مثل `en` أو `es` أو `fr-FR`. عند عدم تعيينه، تُطبَّق اللغة المُعدّة للوكيل. يتطلب `language` ضمن تجاوزات المتصفح الخاصة بالمفتاح.
`voice`	`string`	لا	--	تجاوز الصوت لكل جلسة -- اسم صوت مثل `maria`. عند عدم تعيينه، يُطبَّق الصوت المُعدّ للوكيل. يتطلب `voice` ضمن تجاوزات المتصفح الخاصة بالمفتاح.
`context`	`string`	لا	--	سياق واقعي للصفحة أو الموقع لكل جلسة يُمرَّر إلى الوكيل (مثل تفاصيل الصفحة التي يعرضها الزائر). يُقتطع من جانب الخادم إلى 12,000 حرف. يتطلب `context` ضمن تجاوزات المتصفح الخاصة بالمفتاح.
`onConnect`	`() => void`	لا	--	يُستدعى عند اتصال الجلسة الصوتية بنجاح.
`onDisconnect`	`() => void`	لا	--	يُستدعى عند انتهاء الجلسة.
`onError`	`(error) => void`	لا	--	يُستدعى عند حدوث أخطاء. يحتوي الكائن `error` على الحقلين `error` (الرمز) و`message`.
`className`	`string`	لا	--	اسم فئة CSS إضافي يُطبَّق على حاوية الأداة.
`ringtone`	`boolean \| string`	لا	`false`	شغّل نغمة رنين أثناء الاتصال. استخدم `true` لنغمة الرنين الافتراضية، أو سلسلة URL لصوت مخصص.

أمثلة

سمة داكنة بلون مخصص

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      theme="dark"
      primaryColor="#8b5cf6"
      title="Talk to our AI"
    />
  )
}

موضع مخصص

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      position="bottom-left"
    />
  )
}

تُمرَّر الخصائص language وvoice وcontext إلى طلب الجلسة (POST /widget/session) عند بدء مكالمة، متجاوزةً الإعدادات الافتراضية التي ضُبطت للوكيل لتلك الجلسة. فعّل كل خاصية تستخدمها ضمن تجاوزات المتصفح للأداة في لوحة التحكم (أو في allowed_overrides للمفتاح). لا تقبل الأدوات الجديدة أيًّا منها، ويفشل طلب جلسة يتضمن خاصية غير مفعّلة بالخطأ 400 override_not_allowed؛ راجع تجاوزات المتصفح.

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function PricingPageWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      language="es"
      voice="maria"
      context="Page: Pricing. Plans: Starter $29/mo, Pro $99/mo. Annual billing saves 20%."
    />
  )
}

استخدم context لمنح الوكيل معرفة واقعية حول الصفحة التي يتصفحها الزائر، مثل تفاصيل المنتج أو الأسعار أو الأسئلة الشائعة الخاصة بالصفحة. يتعامل الوكيل معها كمحتوى للصفحة، لا كتعليمات. ويُقتطع من جانب الخادم إلى 12,000 حرف.

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

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function SupportWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      onConnect={() => {
        console.log('Voice session connected')
        analytics.track('widget_call_started')
      }}
      onDisconnect={() => {
        console.log('Voice session ended')
        analytics.track('widget_call_ended')
      }}
      onError={(error) => {
        console.error(`Widget error: ${error.error} - ${error.message}`)
      }}
    />
  )
}

مع تنسيق مخصص

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function BrandedWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      primaryColor="#4a90d9"
      className="my-custom-widget"
    />
  )
}

.my-custom-widget .tp-button--end {
  background-color: #e74c3c;
}

راجع دليل التنسيق للاطلاع على جميع فئات CSS والخصائص المخصصة المتاحة.

مع نغمة رنين

شغّل صوت رنين هاتف أثناء إنشاء الاتصال:

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function PhoneWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      ringtone={true}
    />
  )
}

استخدم نغمة رنين مخصصة بتمرير عنوان URL لملف صوتي:

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  ringtone="https://example.com/my-ringtone.mp3"
/>

تتكرر نغمة الرنين بينما تكون الأداة في حالة connecting، وتتلاشى بسلاسة عند اتصال الوكيل.

مع أساس API مخصص

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  apiBase="https://your-proxy.example.com/v1"
/>

معالجة الأخطاء

عند تشغيل معاودة onError، تتلقى كائن خطأ يحتوي على حقلين:

الحقل	النوع	الوصف
`error`	`string`	رمز خطأ قابل للقراءة آليًا
`message`	`string`	وصف خطأ قابل للقراءة البشرية

تشمل رموز الأخطاء الشائعة: النطاق غير مسموح به، أو لم يُعثر على الوكيل، أو مفتاح API غير صالح.

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

خطاف بلا واجهة

هل تحتاج إلى تحكم كامل في واجهة المستخدم؟ استخدم الخطاف useThunderPhone بدلًا من ذلك.

التنسيق

خصّص الألوان والأحجام والتخطيط باستخدام خصائص CSS المخصصة.