مكوّن React - ThunderPhone

يعرض المكوّن 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"
    />
  )
}

يجب استيراد ملف CSS لكي يُعرض الودجت بصورة صحيحة. بدونه، سيظهر الودجت دون تنسيق.

الخصائص

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

الخاصية	النوع	مطلوب	الافتراضي	الوصف
`publishableKey`	`string`	نعم	—	مفتاح API قابل للنشر (`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 الأساسي لـ API.
`language`	`string`	لا	—	تجاوز اللغة لكل جلسة — رمز لغة أو إعدادات محلية مثل `en` أو `es` أو `fr-FR`. عند عدم تعيينه، تُطبّق اللغة المهيأة للوكيل.
`voice`	`string`	لا	—	تجاوز الصوت لكل جلسة — اسم صوت مثل `maria`. عند عدم تعيينه، يُطبّق الصوت المهيأ للوكيل.
`context`	`string`	لا	—	سياق واقعي للصفحة أو الموقع لكل جلسة يُمرَّر إلى الوكيل (على سبيل المثال، تفاصيل الصفحة التي يعرضها الزائر). يُقتطع على جانب الخادم إلى 12,000 حرف.
`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) عند بدء مكالمة، لتتجاوز الإعدادات الافتراضية التي ضُبطت للوكيل لتلك الجلسة:

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 مخصص

لا تحتاج إلى ضبط apiBase إلا إذا كنت تستخدم نقطة نهاية API مستضافة ذاتيًا أو عبر وكيل. يشير الإعداد الافتراضي إلى https://api.thunderphone.com/v1.

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

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

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

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

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

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

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

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

التنسيق

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

​التثبيت

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

​الخصائص

​أمثلة

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

​موضع مخصص

​اللغة والصوت والسياق لكل جلسة

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

​مع تنسيق مخصص

​مع نغمة رنين

​مع أساس API مخصص

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

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

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

التنسيق

التثبيت

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

الخصائص

أمثلة

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

موضع مخصص

اللغة والصوت والسياق لكل جلسة

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

مع تنسيق مخصص

مع نغمة رنين

مع أساس API مخصص

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

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