רכיב 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"
    />
  )
}

שפה, קול והקשר לכל סשן

ה-props 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 באירוח עצמי או באמצעות proxy. ברירת המחדל מצביעה על 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 לא תקין.

השלבים הבאים

Hook ללא ממשק

זקוקים לשליטה מלאה בממשק המשתמש? השתמשו במקום זאת ב-hook useThunderPhone.

עיצוב

התאימו אישית צבעים, גדלים ופריסה באמצעות מאפייני CSS מותאמים אישית.

​התקנה

​שימוש בסיסי

​מאפיינים

​דוגמאות

​ערכת נושא כהה עם צבע מותאם אישית

​מיקום מותאם אישית

​שפה, קול והקשר לכל סשן

​עם קריאות חזרה לאירועים

​עם עיצוב מותאם אישית

​עם צלצול

​עם בסיס API מותאם אישית

​טיפול בשגיאות

​השלבים הבאים

Hook ללא ממשק

עיצוב

התקנה

שימוש בסיסי

מאפיינים

דוגמאות

ערכת נושא כהה עם צבע מותאם אישית

מיקום מותאם אישית

שפה, קול והקשר לכל סשן

עם קריאות חזרה לאירועים

עם עיצוב מותאם אישית

עם צלצול

עם בסיס API מותאם אישית

טיפול בשגיאות

השלבים הבאים