---
title: "React komponentas"
description: "Įterpkite ThunderPhone balso valdiklį į React programą"
---

Komponentas `ThunderPhoneWidget` pateikia stiklo efekto skambučių juostą su integruotais nutildymo, skambučio baigimo ir ryšio būsenos rodymo valdikliais. Tai greičiausias būdas pridėti balso DI prie React programos.

## Diegimas

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

## Pagrindinis naudojimas

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

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

<Warning>
  Kad valdiklis būtų tinkamai pateiktas, **privalote** importuoti CSS failą. Be jo valdiklis neturės stiliaus.
</Warning>

---

## Savybės

Komponentas priima šias savybes per `ThunderPhoneWidgetProps`:

| Savybė | Tipas | Būtina | Numatytoji reikšmė | Aprašymas |
|------|------|----------|---------|-------------|
| `publishableKey` | `string` | Taip | -- | Viešas API raktas (`pk_live_...`) iš Kūrėjų nustatymų. Agentas automatiškai nustatomas pagal rakto valdiklio konfigūraciją. |
| `theme` | `'light' \| 'dark'` | Ne | `'light'` | Spalvų schema. Valdiklio šakniniam elementui priskiria `tp--light` arba `tp--dark` klasę. |
| `primaryColor` | `string` | Ne | `'#000000'` (šviesi) / `'#ffffff'` (tamsi) | CSS spalvos eilutė, naudojama kaip akcento spalva (skambučio mygtukas, bangos forma, aktyvūs indikatoriai). |
| `title` | `string` | Ne | `'Voice assistant'` | Valdiklio juostoje rodomas tekstas. |
| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | Ne | `'bottom-right'` | Fiksuota valdiklio padėtis peržiūros srityje. |
| `apiBase` | `string` | Ne | `'https://api.thunderphone.com/v1'` | API bazinio URL pakeitimas. |
| `language` | `string` | Ne | -- | Vienos sesijos kalbos pakeitimas -- kalbos kodas arba lokalė, pvz., `en`, `es` arba `fr-FR`. Kai nenustatyta, taikoma sukonfigūruota agento kalba. |
| `voice` | `string` | Ne | -- | Vienos sesijos balso pakeitimas -- balso pavadinimas, pvz., `maria`. Kai nenustatyta, taikomas sukonfigūruotas agento balsas. |
| `context` | `string` | Ne | -- | Agentui perduodamas vienos sesijos faktinis puslapio arba svetainės kontekstas (pavyzdžiui, informacija apie puslapį, kurį lankytojas peržiūri). Serverio pusėje sutrumpinama iki 12 000 simbolių. |
| `onConnect` | `() => void` | Ne | -- | Iškviečiama, kai balso sesija sėkmingai prisijungia. |
| `onDisconnect` | `() => void` | Ne | -- | Iškviečiama, kai sesija baigiama. |
| `onError` | `(error) => void` | Ne | -- | Iškviečiama įvykus klaidoms. Objektas `error` turi laukus `error` (kodas) ir `message`. |
| `className` | `string` | Ne | -- | Papildomas CSS klasės pavadinimas, priskiriamas valdiklio konteineriui. |
| `ringtone` | `boolean \| string` | Ne | `false` | Leisti skambėjimo toną, kol užmezgamas ryšys. `true` naudoja numatytąjį skambėjimo toną, o URL eilutė -- pasirinktinį garsą. |

---

## Pavyzdžiai

### Tamsi tema su pasirinkta spalva

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

### Pasirinkta pozicija

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

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

### Kalba, balsas ir kontekstas kiekvienai sesijai

Prasidėjus skambučiui, `language`, `voice` ir `context` rekvizitai perduodami sesijos užklausai (`POST /widget/session`), pakeisdami tam seansui sukonfigūruotas numatytąsias agento reikšmes:

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

Naudokite `context`, kad suteiktumėte agentui faktinių žinių apie puslapį, kuriame yra lankytojas: produkto informaciją, kainodarą ar konkretaus puslapio dažnai užduodamus klausimus. Serverio pusėje jis sutrumpinamas iki 12 000 simbolių.

### Su įvykių atgaliniais iškvietimais

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

### Su pasirinktu stiliumi

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

Visas galimas CSS klases ir tinkintas savybes rasite [stiliaus vadove](/lt/widget/styling).

### Su skambėjimo tonu

Kol nustatomas ryšys, leiskite telefono skambėjimo garsą:

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

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

Naudokite pasirinktą skambėjimo toną, perduodami garso failo URL:

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

Skambėjimo tonas kartojamas, kol valdiklio būsena yra `connecting`, ir sklandžiai nutyla, kai prisijungia agentas.

### Su pasirinkta API baze

<Tip>
  `apiBase` reikia nustatyti tik jei naudojate savarankiškai talpinamą arba tarpinio serverio API galinį tašką. Pagal numatytuosius nustatymus naudojama `https://api.thunderphone.com/v1`.
</Tip>

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

---

## Klaidų tvarkymas

Suveikus `onError` atgaliniam iškvietimui, jis gauna klaidos objektą su dviem laukais:

| Laukas | Tipas | Aprašas |
|-------|------|-------------|
| `error` | `string` | Kompiuterio skaitomas klaidos kodas |
| `message` | `string` | Žmogui suprantamas klaidos aprašas |

Dažniausi klaidų kodai apima neleidžiamą domeną, nerastą agentą ir netinkamą API raktą.

---

## Tolesni veiksmai

<CardGroup cols={2}>
  <Card title="Headless Hook" icon="code" href="/lt/widget/headless-hook">
    Reikia visiškos naudotojo sąsajos kontrolės? Vietoje to naudokite `useThunderPhone` kablį.
  </Card>
  <Card title="Stilius" icon="palette" href="/lt/widget/styling">
    Tinkinkite spalvas, dydžius ir išdėstymą naudodami CSS pasirinktines ypatybes.
  </Card>
</CardGroup>