---
title: "Komponent React"
description: "Vložte hlasový widget ThunderPhone do aplikácie React"
---

Komponent `ThunderPhoneWidget` vykresľuje sklenený panel hovoru so vstavanými ovládacími prvkami na stlmenie, ukončenie hovoru a zobrazenie stavu pripojenia. Je to najrýchlejší spôsob, ako pridať hlasovú AI do aplikácie React.

## Inštalácia

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

## Základné použitie

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

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

<Warning>
  Na správne vykreslenie widgetu **musíte** importovať súbor CSS. Bez neho nebude widget naštýlovaný.
</Warning>

---

## Vlastnosti

Komponent prijíma nasledujúce vlastnosti prostredníctvom `ThunderPhoneWidgetProps`:

| Vlastnosť | Typ | Povinné | Predvolené | Popis |
|------|------|----------|---------|-------------|
| `publishableKey` | `string` | Áno | -- | Verejný API kľúč (`pk_live_...`) z nastavení Vývojári. Hlasový agent sa automaticky určí z konfigurácie widgetu daného kľúča. |
| `theme` | `'light' \| 'dark'` | Nie | `'light'` | Farebná schéma. Na koreňový prvok widgetu aplikuje triedu `tp--light` alebo `tp--dark`. |
| `primaryColor` | `string` | Nie | `'#000000'` (svetlá) / `'#ffffff'` (tmavá) | Reťazec farby CSS použitý ako akcentová farba (tlačidlo hovoru, priebeh zvukovej vlny, aktívne indikátory). |
| `title` | `string` | Nie | `'Voice assistant'` | Text zobrazený v paneli widgetu. |
| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | Nie | `'bottom-right'` | Pevná pozícia widgetu vo výreze obrazovky. |
| `apiBase` | `string` | Nie | `'https://api.thunderphone.com/v1'` | Prepísanie základnej adresy URL API. |
| `language` | `string` | Nie | -- | Prepísanie jazyka pre jednotlivú reláciu – kód jazyka alebo miestne nastavenie, napríklad `en`, `es` alebo `fr-FR`. Ak nie je nastavené, použije sa nakonfigurovaný jazyk agenta. |
| `voice` | `string` | Nie | -- | Prepísanie hlasu pre jednotlivú reláciu – názov hlasu, napríklad `maria`. Ak nie je nastavené, použije sa nakonfigurovaný hlas agenta. |
| `context` | `string` | Nie | -- | Faktický kontext stránky alebo webu pre jednotlivú reláciu odovzdaný agentovi (napríklad podrobnosti o stránke, ktorú návštevník prezerá). Na strane servera sa skráti na 12 000 znakov. |
| `onConnect` | `() => void` | Nie | -- | Vyvolá sa po úspešnom pripojení hlasovej relácie. |
| `onDisconnect` | `() => void` | Nie | -- | Vyvolá sa po skončení relácie. |
| `onError` | `(error) => void` | Nie | -- | Vyvolá sa pri chybách. Objekt `error` má polia `error` (kód) a `message`. |
| `className` | `string` | Nie | -- | Ďalší názov triedy CSS aplikovaný na kontajner widgetu. |
| `ringtone` | `boolean \| string` | Nie | `false` | Počas pripájania prehrá vyzváňací tón. `true` pre predvolený vyzváňací tón alebo reťazec URL pre vlastný zvuk. |

---

## Príklady

### Tmavá téma s vlastnou farbou

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

### Vlastná pozícia

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

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

### Jazyk, hlas a kontext pre jednotlivé relácie

Vlastnosti `language`, `voice` a `context` sa pri začatí hovoru odovzdajú požiadavke relácie (`POST /widget/session`) a pre danú reláciu prepíšu nakonfigurované predvolené hodnoty 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%."
    />
  )
}
```

Pomocou `context` poskytnite agentovi faktické informácie o stránke, na ktorej sa návštevník nachádza – podrobnosti o produkte, ceny alebo často kladené otázky špecifické pre danú stránku. Na strane servera sa skracuje na 12 000 znakov.

### S obslužnými funkciami udalostí

```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 vlastným štýlom

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

Všetky dostupné triedy CSS a vlastné vlastnosti nájdete v [príručke štýlovania](/sk/widget/styling).

### S vyzváňacím tónom

Počas vytvárania spojenia prehrávajte zvuk zvonenia telefónu:

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

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

Vlastný vyzváňací tón použite odovzdaním adresy URL zvukového súboru:

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

Vyzváňací tón sa opakuje, kým je widget v stave `connecting`, a po pripojení agenta plynulo stíchne.

### S vlastnou základnou adresou API

<Tip>
  `apiBase` je potrebné nastaviť iba pri používaní samoobslužne hostovaného alebo proxy koncového bodu API. Predvolená hodnota odkazuje na `https://api.thunderphone.com/v1`.
</Tip>

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

---

## Spracovanie chýb

Keď sa spustí spätné volanie `onError`, prijme objekt chyby s dvoma poľami:

| Pole | Typ | Popis |
|-------|------|-------------|
| `error` | `string` | Strojovo čitateľný kód chyby |
| `message` | `string` | Používateľsky čitateľný popis chyby |

Medzi bežné kódy chýb patria nepovolená doména, nenájdený agent a neplatný kľúč API.

---

## Ďalšie kroky

<CardGroup cols={2}>
  <Card title="Headless Hook" icon="code" href="/sk/widget/headless-hook">
    Potrebujete úplnú kontrolu nad používateľským rozhraním? Použite namiesto toho hook `useThunderPhone`.
  </Card>
  <Card title="Štylizácia" icon="palette" href="/sk/widget/styling">
    Prispôsobte farby, veľkosti a rozloženie pomocou vlastných vlastností CSS.
  </Card>
</CardGroup>