> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# רכיב React

> הטמיעו את וידג'ט הקול של ThunderPhone ביישום React

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

## התקנה

```bash theme={null}
npm install @thunderphone/widget
```

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

```tsx theme={null}
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`. כאשר אינו מוגדר, תחול השפה שהוגדרה עבור הסוכן. |
| `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 עבור שמע מותאם אישית.                   |

***

## דוגמאות

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

```tsx theme={null}
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 theme={null}
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`) כאשר שיחה מתחילה, ועוקפים את ברירות המחדל שהוגדרו עבור הסוכן באותו סשן:

```tsx theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
.my-custom-widget .tp-button--end {
  background-color: #e74c3c;
}
```

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

### עם צלצול

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

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

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

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

```tsx theme={null}
<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 theme={null}
<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>