> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# React-komponens

> Ágyazza be a ThunderPhone hangalapú widgetet egy React-alkalmazásba

A `ThunderPhoneWidget` komponens egy üvegszerű hívássávot jelenít meg beépített vezérlőkkel a némításhoz, a hívás befejezéséhez és a kapcsolati állapot megjelenítéséhez. Ez a leggyorsabb módja annak, hogy hangalapú AI-t adjon egy React-alkalmazáshoz.

## Telepítés

```bash theme={null}
npm install @thunderphone/widget
```

## Alapvető használat

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

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

<Warning>
  A widget megfelelő megjelenítéséhez **kötelező** importálnia a CSS-fájlt. Enélkül a widget formázatlan lesz.
</Warning>

***

## Kellékek

A komponens a következő kellékeket fogadja el a `ThunderPhoneWidgetProps` segítségével:

| Kellék           | Típus                                                          | Kötelező | Alapértelmezett                             | Leírás                                                                                                                                                                                   |
| ---------------- | -------------------------------------------------------------- | -------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `publishableKey` | `string`                                                       | Igen     | --                                          | A Fejlesztői beállításokban található nyilvános API-kulcs (`pk_live_...`). Az AI-ügynök automatikusan meghatározásra kerül a kulcs widgetkonfigurációja alapján.                         |
| `theme`          | `'light' \| 'dark'`                                            | Nem      | `'light'`                                   | Színséma. A `tp--light` vagy `tp--dark` osztályt alkalmazza a widget gyökérelemére.                                                                                                      |
| `primaryColor`   | `string`                                                       | Nem      | `'#000000'` (világos) / `'#ffffff'` (sötét) | Akcentusszínként használt CSS-színkarakterlánc (hívásgomb, hullámforma, aktív jelzők).                                                                                                   |
| `title`          | `string`                                                       | Nem      | `'Voice assistant'`                         | A widget sávjában megjelenített szöveg.                                                                                                                                                  |
| `position`       | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | Nem      | `'bottom-right'`                            | A widget rögzített pozíciója a nézetablakban.                                                                                                                                            |
| `apiBase`        | `string`                                                       | Nem      | `'https://api.thunderphone.com/v1'`         | API-alap URL felülbírálása.                                                                                                                                                              |
| `language`       | `string`                                                       | Nem      | --                                          | Munkamenetenkénti nyelvi felülbírálás -- nyelvkód vagy területi beállítás, például `en`, `es` vagy `fr-FR`. Ha nincs beállítva, az AI-ügynök konfigurált nyelve érvényes.                |
| `voice`          | `string`                                                       | Nem      | --                                          | Munkamenetenkénti hangfelülbírálás -- hangnév, például `maria`. Ha nincs beállítva, az AI-ügynök konfigurált hangja érvényes.                                                            |
| `context`        | `string`                                                       | Nem      | --                                          | Az AI-ügynöknek átadott, munkamenetenkénti tényszerű oldal- vagy webhelykontextus (például a látogató által megtekintett oldal részletei). A szerveroldalon 12 000 karakterre csonkolva. |
| `onConnect`      | `() => void`                                                   | Nem      | --                                          | Akkor hívódik meg, amikor a hangmunkamenet sikeresen csatlakozik.                                                                                                                        |
| `onDisconnect`   | `() => void`                                                   | Nem      | --                                          | Akkor hívódik meg, amikor a munkamenet véget ér.                                                                                                                                         |
| `onError`        | `(error) => void`                                              | Nem      | --                                          | Hibák esetén hívódik meg. Az `error` objektum `error` (kód) és `message` mezőkkel rendelkezik.                                                                                           |
| `className`      | `string`                                                       | Nem      | --                                          | A widget tárolójára alkalmazott további CSS-osztálynév.                                                                                                                                  |
| `ringtone`       | `boolean \| string`                                            | Nem      | `false`                                     | Csengőhang lejátszása csatlakozás közben. `true` az alapértelmezett csengőhanghoz, vagy URL-karakterlánc egyéni hanganyaghoz.                                                            |

***

## Példák

### Sötét téma egyéni színnel

```tsx theme={null}
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"
    />
  )
}
```

### Egyéni pozíció

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

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

### Munkamenetenkénti nyelv, hang és kontextus

A `language`, `voice` és `context` propok a hívás indításakor továbbításra kerülnek a munkamenet-kérelemnek (`POST /widget/session`), és felülírják az ügynök adott munkamenethez beállított alapértelmezett értékeit:

```tsx theme={null}
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%."
    />
  )
}
```

A `context` segítségével tényszerű információkat adhat az ügynöknek arról az oldalról, amelyen a látogató tartózkodik – például termékadatokat, árakat vagy oldalspecifikus gyakori kérdéseket. A rendszer szerveroldalon 12 000 karakterre csonkítja.

### Esemény-visszahívásokkal

```tsx theme={null}
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}`)
      }}
    />
  )
}
```

### Egyéni stílussal

```tsx theme={null}
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 theme={null}
.my-custom-widget .tp-button--end {
  background-color: #e74c3c;
}
```

Az összes elérhető CSS-osztályt és egyéni tulajdonságot a [Stílusútmutatóban](/hu/widget/styling) találja.

### Csengőhanggal

Játsszon le telefoncsörgő hangot a kapcsolat létrehozása közben:

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

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

Adjon meg egy hangfájl-URL-t egyéni csengőhang használatához:

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

A csengőhang ismétlődik, amíg a widget `connecting` állapotban van, és finoman elhalkul, amikor az ügynök kapcsolódik.

### Egyéni API-alappal

<Tip>
  A `apiBase` beállítására csak saját üzemeltetésű vagy proxy API-végpont használatakor van szükség. Az alapértelmezett érték a `https://api.thunderphone.com/v1` címre mutat.
</Tip>

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

***

## Hibakezelés

Amikor az `onError` visszahívás lefut, egy két mezőt tartalmazó hibaobjektumot kap:

| Mező      | Típus    | Leírás                           |
| --------- | -------- | -------------------------------- |
| `error`   | `string` | Géppel olvasható hibakód         |
| `message` | `string` | Ember által olvasható hibaleírás |

A gyakori hibakódok közé tartozik a nem engedélyezett domain, a nem található ügynök és az érvénytelen API-kulcs.

***

## Következő lépések

<CardGroup cols={2}>
  <Card title="Headless Hook" icon="code" href="/hu/widget/headless-hook">
    Teljes irányítást szeretne a felhasználói felület felett? Használja inkább a `useThunderPhone` hookot.
  </Card>

  <Card title="Stílusok" icon="palette" href="/hu/widget/styling">
    Szabja testre a színeket, méreteket és az elrendezést CSS egyéni tulajdonságokkal.
  </Card>
</CardGroup>