---
title: "Komponenta React"
description: "Vdelajte glasovni pripomoček ThunderPhone v aplikacijo React"
---

Komponenta `ThunderPhoneWidget` prikaže klicno vrstico s steklenim videzom in vgrajenimi kontrolniki za utišanje, končanje klica ter prikaz stanja povezave. To je najhitrejši način za dodajanje glasovne umetne inteligence v aplikacijo React.

## Namestitev

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

## Osnovna uporaba

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

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

<Warning>
  Datoteko CSS **morate** uvoziti, da se gradnik pravilno prikaže. Brez nje gradnik ne bo oblikovan.
</Warning>

---

## Lastnosti

Komponenta prek `ThunderPhoneWidgetProps` sprejema naslednje lastnosti:

| Lastnost | Vrsta | Obvezno | Privzeto | Opis |
|------|------|----------|---------|-------------|
| `publishableKey` | `string` | Da | -- | Javni ključ API-ja (`pk_live_...`) iz nastavitev za razvijalce. Agent se samodejno določi iz konfiguracije gradnika ključa. |
| `theme` | `'light' \| 'dark'` | Ne | `'light'` | Barvna shema. Na korensko mesto gradnika uporabi razred `tp--light` ali `tp--dark`. |
| `primaryColor` | `string` | Ne | `'#000000'` (svetla) / `'#ffffff'` (temna) | Niz z barvo CSS, uporabljen kot poudarjena barva (gumb za klic, valovna oblika, aktivni indikatorji). |
| `title` | `string` | Ne | `'Voice assistant'` | Besedilo, prikazano v vrstici gradnika. |
| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | Ne | `'bottom-right'` | Fiksni položaj gradnika v vidnem polju. |
| `apiBase` | `string` | Ne | `'https://api.thunderphone.com/v1'` | Preglasitev osnovnega URL-ja API-ja. |
| `language` | `string` | Ne | -- | Preglasitev jezika za posamezno sejo -- koda jezika ali krajevne nastavitve, kot so `en`, `es` ali `fr-FR`. Če ni nastavljeno, se uporabi jezik, konfiguriran za agenta. |
| `voice` | `string` | Ne | -- | Preglasitev glasu za posamezno sejo -- ime glasu, kot je `maria`. Če ni nastavljeno, se uporabi glas, konfiguriran za agenta. |
| `context` | `string` | Ne | -- | Dejanski kontekst strani ali spletnega mesta za posamezno sejo, posredovan agentu (na primer podrobnosti strani, ki jo obiskovalec pregleduje). Na strani strežnika je skrajšan na 12.000 znakov. |
| `onConnect` | `() => void` | Ne | -- | Pokliče se, ko je glasovna seja uspešno povezana. |
| `onDisconnect` | `() => void` | Ne | -- | Pokliče se, ko se seja konča. |
| `onError` | `(error) => void` | Ne | -- | Pokliče se ob napakah. Objekt `error` ima polji `error` (koda) in `message`. |
| `className` | `string` | Ne | -- | Dodatno ime razreda CSS, uporabljeno za vsebnik gradnika. |
| `ringtone` | `boolean \| string` | Ne | `false` | Med povezovanjem predvaja melodijo zvonjenja. `true` za privzeto melodijo zvonjenja ali niz URL za zvok po meri. |

---

## Primeri

### Temna tema z barvo po meri

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

### Položaj po meri

```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 in kontekst za posamezno sejo

Lastnosti `language`, `voice` in `context` se ob začetku klica posredujejo zahtevi seje (`POST /widget/session`) ter za to sejo preglasijo nastavljene privzete vrednosti glasovnega 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%."
    />
  )
}
```

Uporabite `context`, da agentu zagotovite dejansko znanje o strani, na kateri je obiskovalec -- podrobnosti o izdelku, cene ali pogosta vprašanja, značilna za stran. Na strežniški strani je skrajšan na 12.000 znakov.

### S povratnimi klici dogodkov

```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 oblikovanjem po meri

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

Za vse razpoložljive razrede CSS in lastnosti po meri glejte [vodnik za oblikovanje](/sl/widget/styling).

### Z melodijo zvonjenja

Med vzpostavljanjem povezave predvajajte zvok zvonjenja telefona:

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

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

Melodijo zvonjenja po meri uporabite tako, da podate URL zvočne datoteke:

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

Melodija zvonjenja se ponavlja, ko je gradnik v stanju `connecting`, in gladko utihne, ko se glasovni agent poveže.

### Z osnovnim URL-jem API po meri

<Tip>
  `apiBase` morate nastaviti le, če uporabljate samostojno gostujočo ali posredniško končno točko API. Privzeta vrednost kaže na `https://api.thunderphone.com/v1`.
</Tip>

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

---

## Obravnava napak

Ko se sproži povratni klic `onError`, prejme objekt napake z dvema poljema:

| Polje | Vrsta | Opis |
|-------|------|-------------|
| `error` | `string` | Strojno berljiva koda napake |
| `message` | `string` | Uporabniku razumljiv opis napake |

Pogoste kode napak vključujejo nedovoljeno domeno, agenta ni mogoče najti in neveljaven ključ API.

---

## Naslednji koraki

<CardGroup cols={2}>
  <Card title="Brezglavni hook" icon="code" href="/sl/widget/headless-hook">
    Potrebujete popoln nadzor nad uporabniškim vmesnikom? Namesto tega uporabite hook `useThunderPhone`.
  </Card>
  <Card title="Oblikovanje" icon="palette" href="/sl/widget/styling">
    Prilagodite barve, velikosti in postavitev z lastnostmi CSS po meri.
  </Card>
</CardGroup>