---
title: "React جزو"
description: "ThunderPhone وائس ویجیٹ کو React ایپلیکیشن میں شامل کریں"
---

`ThunderPhoneWidget` کمپوننٹ ایک گلاس مورفک کال بار رینڈر کرتا ہے جس میں خاموش کرنے، کال ختم کرنے، اور کنکشن کی حیثیت دکھانے کے لیے بلٹ اِن کنٹرولز شامل ہیں۔ React ایپ میں وائس AI شامل کرنے کا یہ تیز ترین طریقہ ہے۔

## انسٹالیشن

```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` | ہاں | -- | Developers کی ترتیبات سے قابلِ اشاعت 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'` | API بنیادی URL اووررائیڈ۔ |
| `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
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` props سیشن کی درخواست (`POST /widget/session`) کو بھیجے جاتے ہیں، اور اس سیشن کے لیے ایجنٹ کی ترتیب شدہ ڈیفالٹ ویلیوز کو اووررائیڈ کرتے ہیں:

```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;
}
```

تمام دستیاب CSS کلاسز اور حسب ضرورت خصوصیات کے لیے [اسٹائلنگ گائیڈ](/ur/widget/styling) دیکھیں۔

### رنگ ٹون کے ساتھ

کنکشن قائم ہونے کے دوران فون بجنے کی آواز چلائیں:

```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 اینڈ پوائنٹ استعمال کر رہے ہوں۔ ڈیفالٹ `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="ہیڈ لیس ہک" icon="code" href="/ur/widget/headless-hook">
    UI پر مکمل کنٹرول درکار ہے؟ اس کے بجائے `useThunderPhone` ہک استعمال کریں۔
  </Card>
  <Card title="اسٹائلنگ" icon="palette" href="/ur/widget/styling">
    CSS کسٹم پراپرٹیز کے ذریعے رنگ، سائز اور لے آؤٹ حسبِ ضرورت بنائیں۔
  </Card>
</CardGroup>