Open in

רכיב 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`	כן	--	מפתח 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`. כאשר הערך אינו מוגדר, נעשה שימוש בשפה שהוגדרה עבור הסוכן. דורש את `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 לא תקין.

השלבים הבאים

Hook ללא ממשק

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

עיצוב

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