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

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

تُمرَّر الخصائص `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;
}
```

راجع [دليل التنسيق](/ar/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 مستضافة ذاتيًا أو عبر وكيل. يشير الإعداد الافتراضي إلى `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="خطاف بلا واجهة" icon="code" href="/ar/widget/headless-hook">
    هل تحتاج إلى تحكم كامل في واجهة المستخدم؟ استخدم الخطاف `useThunderPhone` بدلًا من ذلك.
  </Card>

  <Card title="التنسيق" icon="palette" href="/ar/widget/styling">
    خصّص الألوان والأحجام والتخطيط باستخدام خصائص CSS المخصصة.
  </Card>
</CardGroup>