---
title: "React компонента"
description: "Уградите ThunderPhone гласовни виџет у React апликацију"
---

Компонента `ThunderPhoneWidget` приказује стакласти панел за позиве са уграђеним контролама за искључивање звука, завршавање позива и приказ статуса везе. То је најбржи начин да додате гласовни AI у 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'` | Замена основног 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` прослеђују се захтеву за сесију (`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;
}
```

Погледајте [водич за стилизовање](/sr/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 крајњу тачку. Подразумевана вредност указује на `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="Headless Hook" icon="code" href="/sr/widget/headless-hook">
    Потребна Вам је потпуна контрола над корисничким интерфејсом? Уместо тога користите hook `useThunderPhone`.
  </Card>
  <Card title="Стилизација" icon="palette" href="/sr/widget/styling">
    Прилагодите боје, величине и распоред помоћу CSS прилагођених својстава.
  </Card>
</CardGroup>