---
title: "React komponenta"
description: "Ugradite ThunderPhone glasovni widget u React aplikaciju"
---

Komponenta `ThunderPhoneWidget` prikazuje staklastu traku za pozive s ugrađenim kontrolama za isključivanje zvuka, završavanje poziva i prikaz statusa veze. To je najbrži način za dodavanje glasovnog AI-ja u React aplikaciju.

## Instalacija

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

## Osnovna upotreba

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

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

<Warning>
  CSS datoteku morate uvesti kako bi se widget ispravno prikazao. Bez nje widget neće imati stil.
</Warning>

---

## Svojstva

Komponenta prihvaća sljedeća svojstva putem `ThunderPhoneWidgetProps`:

| Svojstvo | Vrsta | Obavezno | Zadano | Opis |
|------|------|----------|---------|-------------|
| `publishableKey` | `string` | Da | -- | Javni API ključ (`pk_live_...`) iz postavki za razvojne programere. Agent se automatski određuje iz konfiguracije widgeta tog ključa. |
| `theme` | `'light' \| 'dark'` | Ne | `'light'` | Shema boja. Primjenjuje klasu `tp--light` ili `tp--dark` na korijenski element widgeta. |
| `primaryColor` | `string` | Ne | `'#000000'` (svijetla) / `'#ffffff'` (tamna) | CSS niz boje koji se koristi kao naglasna boja (gumb za poziv, valni oblik, aktivni indikatori). |
| `title` | `string` | Ne | `'Voice assistant'` | Tekst prikazan u traci widgeta. |
| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | Ne | `'bottom-right'` | Fiksni položaj widgeta u prikazu. |
| `apiBase` | `string` | Ne | `'https://api.thunderphone.com/v1'` | Nadjačavanje osnovnog URL-a API-ja. |
| `language` | `string` | Ne | -- | Nadjačavanje jezika po sesiji -- jezični kod ili regionalna postavka, kao što su `en`, `es` ili `fr-FR`. Ako nije postavljeno, primjenjuje se konfigurirani jezik agenta. |
| `voice` | `string` | Ne | -- | Nadjačavanje glasa po sesiji -- naziv glasa, kao što je `maria`. Ako nije postavljeno, primjenjuje se konfigurirani glas agenta. |
| `context` | `string` | Ne | -- | Činjenični kontekst stranice ili web-mjesta po sesiji koji se prosljeđuje agentu (na primjer, pojedinosti stranice koju posjetitelj pregledava). Na poslužitelju se skraćuje na 12.000 znakova. |
| `onConnect` | `() => void` | Ne | -- | Poziva se kada se glasovna sesija uspješno poveže. |
| `onDisconnect` | `() => void` | Ne | -- | Poziva se kada sesija završi. |
| `onError` | `(error) => void` | Ne | -- | Poziva se pri pogreškama. Objekt `error` ima polja `error` (kôd) i `message`. |
| `className` | `string` | Ne | -- | Dodatni naziv CSS klase primijenjen na spremnik widgeta. |
| `ringtone` | `boolean \| string` | Ne | `false` | Reproducira melodiju zvona tijekom povezivanja. `true` za zadanu melodiju zvona ili URL niz za prilagođeni zvuk. |

---

## Primjeri

### Tamna tema s prilagođenom bojom

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

### Prilagođeni položaj

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

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

### Jezik, glas i kontekst po sesiji

Svojstva `language`, `voice` i `context` prosljeđuju se zahtjevu za sesiju (`POST /widget/session`) pri pokretanju poziva te za tu sesiju nadjačavaju zadano konfigurirane postavke agenta:

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

Upotrijebite `context` da biste agentu pružili činjenične informacije o stranici na kojoj se posjetitelj nalazi -- pojedinosti o proizvodu, cijene ili česta pitanja specifična za stranicu. Na poslužitelju se skraćuje na 12.000 znakova.

### S povratnim pozivima događaja

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

### S prilagođenim stilom

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

Pogledajte [vodič za stiliziranje](/hr/widget/styling) za sve dostupne CSS klase i prilagođena svojstva.

### Sa zvukom zvonjenja

Reproducirajte zvuk zvonjenja telefona tijekom uspostavljanja veze:

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

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

Upotrijebite prilagođeni zvuk zvonjenja prosljeđivanjem URL-a audiodatoteke:

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

Zvuk zvonjenja ponavlja se dok je widget u stanju `connecting` i postupno se stišava kada se agent poveže.

### S prilagođenom osnovom API-ja

<Tip>
  `apiBase` trebate postaviti samo ako upotrebljavate samostalno hostiranu ili proxy krajnju točku API-ja. Zadana vrijednost upućuje na `https://api.thunderphone.com/v1`.
</Tip>

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

---

## Rukovanje pogreškama

Kada se aktivira povratni poziv `onError`, prima objekt pogreške s dvama poljima:

| Polje | Vrsta | Opis |
|-------|------|-------------|
| `error` | `string` | Strojno čitljiv kôd pogreške |
| `message` | `string` | Čovjeku čitljiv opis pogreške |

Uobičajeni kôdovi pogrešaka uključuju nedopuštenu domenu, agenta koji nije pronađen i nevažeći API ključ.

---

## Sljedeći koraci

<CardGroup cols={2}>
  <Card title="Headless Hook" icon="code" href="/hr/widget/headless-hook">
    Trebate potpunu kontrolu nad korisničkim sučeljem? Umjesto toga upotrijebite hook `useThunderPhone`.
  </Card>
  <Card title="Stiliziranje" icon="palette" href="/hr/widget/styling">
    Prilagodite boje, veličine i raspored pomoću prilagođenih CSS svojstava.
  </Card>
</CardGroup>