> ## 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-komponentti

> Upota ThunderPhone-puhewidgetti React-sovellukseen

`ThunderPhoneWidget`-komponentti renderöi lasimaisen puhelupalkin, jossa on sisäänrakennetut hallintatoiminnot mykistämiseen, puhelun lopettamiseen ja yhteyden tilan näyttämiseen. Se on nopein tapa lisätä puhetekoäly React-sovellukseen.

## Asennus

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

## Peruskäyttö

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

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

<Warning>
  Sinun **on** tuotava CSS-tiedosto, jotta widget renderöityy oikein. Ilman sitä widgetillä ei ole tyylejä.
</Warning>

***

## Propit

Komponentti hyväksyy seuraavat propit `ThunderPhoneWidgetProps`-rajapinnan kautta:

| Proppi           | Tyyppi                                                         | Pakollinen | Oletusarvo                                 | Kuvaus                                                                                                                                                                           |
| ---------------- | -------------------------------------------------------------- | ---------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `publishableKey` | `string`                                                       | Kyllä      | --                                         | Kehittäjäasetusten julkaistava API-avain (`pk_live_...`). Agentti määritetään automaattisesti avaimen widget-määrityksen perusteella.                                            |
| `theme`          | `'light' \| 'dark'`                                            | Ei         | `'light'`                                  | Värimaailma. Lisää widgetin juurielementtiin luokan `tp--light` tai `tp--dark`.                                                                                                  |
| `primaryColor`   | `string`                                                       | Ei         | `'#000000'` (vaalea) / `'#ffffff'` (tumma) | Korostusvärinä käytettävä CSS-värimerkkijono (soittopainike, aaltomuoto, aktiiviset ilmaisimet).                                                                                 |
| `title`          | `string`                                                       | Ei         | `'Voice assistant'`                        | Widget-palkissa näytettävä teksti.                                                                                                                                               |
| `position`       | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | Ei         | `'bottom-right'`                           | Widgetin kiinteä sijainti näkymässä.                                                                                                                                             |
| `apiBase`        | `string`                                                       | Ei         | `'https://api.thunderphone.com/v1'`        | API-perusosoitteen ohitus.                                                                                                                                                       |
| `language`       | `string`                                                       | Ei         | --                                         | Istuntokohtainen kieliohitus -- kielikoodi tai alueasetus, kuten `en`, `es` tai `fr-FR`. Jos sitä ei ole asetettu, käytetään agentin määritettyä kieltä.                         |
| `voice`          | `string`                                                       | Ei         | --                                         | Istuntokohtainen äänen ohitus -- äänen nimi, kuten `maria`. Jos sitä ei ole asetettu, käytetään agentin määritettyä ääntä.                                                       |
| `context`        | `string`                                                       | Ei         | --                                         | Agentille välitettävä istuntokohtainen faktapohjainen sivu- tai sivustokonteksti (esimerkiksi tiedot sivusta, jota kävijä katselee). Palvelin katkaisee tekstin 12 000 merkkiin. |
| `onConnect`      | `() => void`                                                   | Ei         | --                                         | Kutsutaan, kun puheistunto muodostaa yhteyden onnistuneesti.                                                                                                                     |
| `onDisconnect`   | `() => void`                                                   | Ei         | --                                         | Kutsutaan, kun istunto päättyy.                                                                                                                                                  |
| `onError`        | `(error) => void`                                              | Ei         | --                                         | Kutsutaan virhetilanteissa. `error`-objektissa on kentät `error` (koodi) ja `message`.                                                                                           |
| `className`      | `string`                                                       | Ei         | --                                         | Widget-säilöön lisättävä CSS-luokan nimi.                                                                                                                                        |
| `ringtone`       | `boolean \| string`                                            | Ei         | `false`                                    | Toista soittoääni yhteyden muodostamisen aikana. Käytä arvoa `true` oletussoittoäänelle tai URL-merkkijonoa mukautetulle äänelle.                                                |

***

## Esimerkkejä

### Tumma teema mukautetulla värillä

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

### Mukautettu sijainti

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

### Istuntokohtainen kieli, ääni ja konteksti

`language`-, `voice`- ja `context`-propit välitetään istuntopyyntöön (`POST /widget/session`) puhelun alkaessa, ja ne ohittavat agentin määritetyt oletusarvot kyseisessä istunnossa:

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

Käytä `context`-proppia antaaksesi agentille faktatietoa sivusta, jolla kävijä on — esimerkiksi tuotetietoja, hinnoittelua tai sivukohtaisia usein kysyttyjä kysymyksiä. Se katkaistaan palvelinpuolella 12 000 merkkiin.

### Tapahtumakutsujen kanssa

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

### Mukautetulla tyylillä

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

Katso kaikki käytettävissä olevat CSS-luokat ja mukautetut ominaisuudet [tyylioppaasta](/fi/widget/styling).

### Soittoäänellä

Toista puhelimen sointiääni yhteyden muodostamisen aikana:

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

Käytä mukautettua soittoääntä välittämällä äänitiedoston URL-osoite:

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

Soittoääni toistuu silmukassa, kun widget on `connecting`-tilassa, ja vaimenee pehmeästi, kun agentti yhdistyy.

### Mukautetulla API-perusosoitteella

<Tip>
  Määritä `apiBase` vain, jos käytät itse ylläpidettyä tai välityspalvelimen API-päätepistettä. Oletusarvo osoittaa osoitteeseen `https://api.thunderphone.com/v1`.
</Tip>

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

***

## Virheenkäsittely

Kun `onError`-takaisinkutsu käynnistyy, se vastaanottaa virheobjektin, jossa on kaksi kenttää:

| Kenttä    | Tyyppi   | Kuvaus                            |
| --------- | -------- | --------------------------------- |
| `error`   | `string` | Koneellisesti luettava virhekoodi |
| `message` | `string` | Ihmiselle luettava virheen kuvaus |

Yleisiä virhekoodeja ovat esimerkiksi toimialue ei sallittu, agenttia ei löytynyt ja virheellinen API-avain.

***

## Seuraavat vaiheet

<CardGroup cols={2}>
  <Card title="Headless-hook" icon="code" href="/fi/widget/headless-hook">
    Tarvitsetko täyden hallinnan käyttöliittymään? Käytä sen sijaan `useThunderPhone`-hookia.
  </Card>

  <Card title="Tyylittely" icon="palette" href="/fi/widget/styling">
    Mukauta värejä, kokoja ja asettelua CSS-mukautetuilla ominaisuuksilla.
  </Card>
</CardGroup>