---
title: "Kijenzi cha React"
description: "Pachika wijeti ya sauti ya ThunderPhone katika programu ya React"
---

Kipengele cha `ThunderPhoneWidget` huonyesha upau wa simu wenye athari ya kioo na vidhibiti vilivyojengewa ndani vya kunyamazisha, kumaliza simu, na kuonyesha hali ya muunganisho. Hii ndiyo njia ya haraka zaidi ya kuongeza AI ya sauti kwenye programu ya React.

## Usakinishaji

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

## Matumizi ya Msingi

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

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

<Warning>
  Lazima **uagize** faili ya CSS ili wijeti ionyeshwe kwa usahihi. Bila hiyo, wijeti haitakuwa na mtindo.
</Warning>

---

## Sifa

Kipengele kinakubali props zifuatazo kupitia `ThunderPhoneWidgetProps`:

| Prop | Aina | Inahitajika | Chaguo-msingi | Maelezo |
|------|------|----------|---------|-------------|
| `publishableKey` | `string` | Ndiyo | -- | Ufunguo wa API unaoweza kuchapishwa (`pk_live_...`) kutoka kwenye mipangilio ya Watengenezaji. Ejenti hutambuliwa kiotomatiki kutoka kwenye usanidi wa wijeti wa ufunguo. |
| `theme` | `'light' \| 'dark'` | Hapana | `'light'` | Mpangilio wa rangi. Hutumia class ya `tp--light` au `tp--dark` kwenye mzizi wa wijeti. |
| `primaryColor` | `string` | Hapana | `'#000000'` (nyepesi) / `'#ffffff'` (giza) | Mfuatano wa rangi wa CSS unaotumika kama rangi ya msisitizo (kitufe cha simu, umbo la wimbi, viashiria vinavyotumika). |
| `title` | `string` | Hapana | `'Voice assistant'` | Maandishi yanayoonyeshwa kwenye upau wa wijeti. |
| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | Hapana | `'bottom-right'` | Nafasi isiyobadilika ya wijeti kwenye eneo la kuonyesha. |
| `apiBase` | `string` | Hapana | `'https://api.thunderphone.com/v1'` | Kubadilisha URL ya msingi ya API. |
| `language` | `string` | Hapana | -- | Kubadilisha lugha kwa kila kikao -- msimbo wa lugha au lokaliti kama vile `en`, `es`, au `fr-FR`. Isipowekwa, lugha iliyosanidiwa ya ejenti hutumika. |
| `voice` | `string` | Hapana | -- | Kubadilisha sauti kwa kila kikao -- jina la sauti kama vile `maria`. Isipowekwa, sauti iliyosanidiwa ya ejenti hutumika. |
| `context` | `string` | Hapana | -- | Muktadha wa taarifa wa ukurasa au tovuti kwa kila kikao unaopelekwa kwa ejenti (kwa mfano, maelezo ya ukurasa anaoutazama mgeni). Hukatwa upande wa seva hadi herufi 12,000. |
| `onConnect` | `() => void` | Hapana | -- | Huitwa kikao cha sauti kinapounganishwa kwa mafanikio. |
| `onDisconnect` | `() => void` | Hapana | -- | Huitwa kikao kinapoisha. |
| `onError` | `(error) => void` | Hapana | -- | Huitwa hitilafu zinapotokea. Kitu cha `error` kina sehemu za `error` (msimbo) na `message`. |
| `className` | `string` | Hapana | -- | Jina la ziada la class ya CSS linalotumika kwenye kontena la wijeti. |
| `ringtone` | `boolean \| string` | Hapana | `false` | Cheza mlio wa simu wakati wa kuunganisha. `true` kwa mlio wa simu chaguo-msingi, au mfuatano wa URL kwa sauti maalum. |

---

## Mifano

### Mandhari Meusi yenye Rangi Maalum

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

### Nafasi Maalum

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

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

### Lugha, Sauti na Muktadha kwa Kila Kikao

Sifa za `language`, `voice`, na `context` hutumwa kwa ombi la kikao (`POST /widget/session`) simu inapoanza, zikibatilisha chaguo-msingi zilizosanidiwa za ejenti kwa kikao hicho:

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

Tumia `context` kumpa ejenti maarifa ya ukweli kuhusu ukurasa ambao mgeni yuko -- maelezo ya bidhaa, bei, au Maswali Yanayoulizwa Mara kwa Mara ya ukurasa mahususi. Hukatwa upande wa seva hadi herufi 12,000.

### Zenye Callbacks za Matukio

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

### Zenye Uwekaji Mitindo Maalum

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

Tazama [mwongozo wa uwekaji mitindo](/sw/widget/styling) kwa madarasa yote ya CSS na sifa maalum zinazopatikana.

### Yenye Mlio wa Simu

Cheza sauti ya simu inayolia wakati muunganisho unaanzishwa:

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

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

Tumia mlio maalum wa simu kwa kupitisha URL ya faili ya sauti:

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

Mlio wa simu hurudiwa wakati wijeti iko katika hali ya `connecting` na hupungua kwa ulaini ejenti inapounganishwa.

### Yenye Msingi Maalum wa API

<Tip>
  Unahitaji tu kuweka `apiBase` ikiwa unatumia endpoint ya API inayojihudumia au ya proksi. Chaguo-msingi huelekeza kwenye `https://api.thunderphone.com/v1`.
</Tip>

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

---

## Ushughulikiaji wa Hitilafu

Callback ya `onError` inapowashwa, hupokea kitu cha hitilafu chenye sehemu mbili:

| Sehemu | Aina | Maelezo |
|-------|------|-------------|
| `error` | `string` | Msimbo wa hitilafu unaosomeka na mashine |
| `message` | `string` | Maelezo ya hitilafu yanayosomeka na binadamu |

Misimbo ya hitilafu ya kawaida inajumuisha kikoa kisichoruhusiwa, ejenti haikupatikana, na ufunguo wa API usio sahihi.

---

## Hatua Zinazofuata

<CardGroup cols={2}>
  <Card title="Hook Isiyo na Kiolesura" icon="code" href="/sw/widget/headless-hook">
    Unahitaji udhibiti kamili wa UI? Tumia hook ya `useThunderPhone` badala yake.
  </Card>
  <Card title="Urembo" icon="palette" href="/sw/widget/styling">
    Geuza rangi, ukubwa na mpangilio upendavyo kwa kutumia sifa maalum za CSS.
  </Card>
</CardGroup>