---
title: "רכיב React"
description: "הטמיעו את וידג'ט הקול של ThunderPhone ביישום React"
---

הרכיב `ThunderPhoneWidget` מציג סרגל שיחה בעיצוב זכוכיתי עם פקדים מובנים להשתקה, לסיום השיחה ולהצגת סטטוס החיבור. זו הדרך המהירה ביותר להוסיף בינה מלאכותית קולית לאפליקציית React.

## התקנה

```bash
npm install @thunderphone/widget
```

## שימוש בסיסי

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
    />
  )
}
```

<Warning>
  עליכם **חובה** לייבא את קובץ ה-CSS כדי שהווידג'ט יוצג כראוי. בלעדיו, הווידג'ט יוצג ללא עיצוב.
</Warning>

---

## מאפיינים

הרכיב מקבל את המאפיינים הבאים באמצעות `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` תחת [דריסות דפדפן](/he/guides/embed-web-widget) של המפתח. |
| `voice` | `string` | לא | -- | דריסת קול לכל הפעלה -- שם קול כגון `maria`. כאשר הערך אינו מוגדר, נעשה שימוש בקול שהוגדר עבור הסוכן. דורש את `voice` תחת [דריסות דפדפן](/he/guides/embed-web-widget) של המפתח. |
| `context` | `string` | לא | -- | הקשר עובדתי של דף או אתר לכל הפעלה המועבר לסוכן (לדוגמה, פרטי הדף שבו המבקר צופה). נחתך בצד השרת ל-12,000 תווים. דורש את `context` תחת [דריסות דפדפן](/he/guides/embed-web-widget) של המפתח. |
| `onConnect` | `() => void` | לא | -- | מופעל כאשר הפעלת הקול מתחברת בהצלחה. |
| `onDisconnect` | `() => void` | לא | -- | מופעל כאשר ההפעלה מסתיימת. |
| `onError` | `(error) => void` | לא | -- | מופעל בעת שגיאות. לאובייקט `error` יש שדות `error` (קוד) ו-`message`. |
| `className` | `string` | לא | -- | שם מחלקת CSS נוסף המוחל על מכל הווידג'ט. |
| `ringtone` | `boolean \| string` | לא | `false` | השמיעו צליל חיוג בזמן ההתחברות. `true` עבור צליל החיוג המוגדר כברירת מחדל, או מחרוזת URL עבור שמע מותאם אישית. |

---

## דוגמאות

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

```tsx
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"
    />
  )
}
```

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

```tsx
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`; ראו [עקיפות דפדפן](/he/guides/embed-web-widget).

```tsx
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 תווים.

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

```tsx
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}`)
      }}
    />
  )
}
```

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

```tsx
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"
    />
  )
}
```

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

עיינו ב[מדריך העיצוב](/he/widget/styling) לכל מחלקות ה-CSS והמאפיינים המותאמים האישית הזמינים.

### עם צלצול

השמיעו צליל צלצול טלפון בזמן שהחיבור נוצר:

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function PhoneWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      ringtone={true}
    />
  )
}
```

השתמשו בצלצול מותאם אישית באמצעות העברת כתובת URL של קובץ שמע:

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

הצלצול מתנגן בלולאה כאשר הווידג'ט במצב `connecting` ונחלש בהדרגה כאשר הסוכן מתחבר.

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

<Tip>
  עליכם להגדיר את `apiBase` רק אם אתם משתמשים בנקודת קצה של API באירוח עצמי או באמצעות proxy. ברירת המחדל מצביעה על `https://api.thunderphone.com/v1`.
</Tip>

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

---

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

כאשר קריאת החזרה `onError` מופעלת, היא מקבלת אובייקט שגיאה עם שני שדות:

| שדה | סוג | תיאור |
|-------|------|-------------|
| `error` | `string` | קוד שגיאה קריא למכונה |
| `message` | `string` | תיאור שגיאה קריא לאדם |

קודי שגיאה נפוצים כוללים דומיין שאינו מורשה, סוכן שלא נמצא ומפתח API לא תקין.

---

## השלבים הבאים

<CardGroup cols={2}>
  <Card title="Hook ללא ממשק" icon="code" href="/he/widget/headless-hook">
    זקוקים לשליטה מלאה בממשק המשתמש? השתמשו במקום זאת ב-hook `useThunderPhone`.
  </Card>
  <Card title="עיצוב" icon="palette" href="/he/widget/styling">
    התאימו אישית צבעים, גדלים ופריסה באמצעות מאפייני CSS מותאמים אישית.
  </Card>
</CardGroup>