> ## 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 Bileşeni

> ThunderPhone ses widget'ını bir React uygulamasına yerleştirin

`ThunderPhoneWidget` bileşeni; sessize alma, aramayı sonlandırma ve bağlantı durumunu görüntüleme için yerleşik kontroller içeren cam efektli bir arama çubuğu oluşturur. Bir React uygulamasına sesli yapay zeka eklemenin en hızlı yoludur.

## Kurulum

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

## Temel Kullanım

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

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

<Warning>
  Widget'ın doğru şekilde oluşturulması için CSS dosyasını **mutlaka** içe aktarmalısınız. Bu dosya olmadan widget stilsiz görünür.
</Warning>

***

## Özellikler

Bileşen, `ThunderPhoneWidgetProps` aracılığıyla aşağıdaki özellikleri kabul eder:

| Özellik          | Tür                                                            | Zorunlu | Varsayılan                              | Açıklama                                                                                                                                                                                   |
| ---------------- | -------------------------------------------------------------- | ------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `publishableKey` | `string`                                                       | Evet    | --                                      | Geliştirici ayarlarındaki yayınlanabilir API anahtarı (`pk_live_...`). Yapay zeka ajanı, anahtarın widget yapılandırmasından otomatik olarak belirlenir.                                   |
| `theme`          | `'light' \| 'dark'`                                            | Hayır   | `'light'`                               | Renk şeması. Widget köküne `tp--light` veya `tp--dark` sınıfını uygular.                                                                                                                   |
| `primaryColor`   | `string`                                                       | Hayır   | `'#000000'` (açık) / `'#ffffff'` (koyu) | Vurgu rengi olarak kullanılan CSS renk dizesi (arama düğmesi, dalga biçimi, etkin göstergeler).                                                                                            |
| `title`          | `string`                                                       | Hayır   | `'Voice assistant'`                     | Widget çubuğunda görüntülenen metin.                                                                                                                                                       |
| `position`       | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | Hayır   | `'bottom-right'`                        | Widget için sabit görüntü alanı konumu.                                                                                                                                                    |
| `apiBase`        | `string`                                                       | Hayır   | `'https://api.thunderphone.com/v1'`     | API temel URL'sini geçersiz kılar.                                                                                                                                                         |
| `language`       | `string`                                                       | Hayır   | --                                      | Oturum başına dil geçersiz kılması -- `en`, `es` veya `fr-FR` gibi bir dil kodu ya da yerel ayar. Ayarlanmadığında, yapay zeka ajanının yapılandırılmış dili uygulanır.                    |
| `voice`          | `string`                                                       | Hayır   | --                                      | Oturum başına ses geçersiz kılması -- `maria` gibi bir ses adı. Ayarlanmadığında, yapay zeka ajanının yapılandırılmış sesi uygulanır.                                                      |
| `context`        | `string`                                                       | Hayır   | --                                      | Yapay zeka ajanına aktarılan, oturum başına olgusal sayfa veya site bağlamı (örneğin ziyaretçinin görüntülediği sayfanın ayrıntıları). Sunucu tarafında 12.000 karakterle sınırlandırılır. |
| `onConnect`      | `() => void`                                                   | Hayır   | --                                      | Sesli oturum başarıyla bağlandığında çağrılır.                                                                                                                                             |
| `onDisconnect`   | `() => void`                                                   | Hayır   | --                                      | Oturum sona erdiğinde çağrılır.                                                                                                                                                            |
| `onError`        | `(error) => void`                                              | Hayır   | --                                      | Hata oluştuğunda çağrılır. `error` nesnesinde `error` (kod) ve `message` alanları bulunur.                                                                                                 |
| `className`      | `string`                                                       | Hayır   | --                                      | Widget kapsayıcısına uygulanan ek CSS sınıf adı.                                                                                                                                           |
| `ringtone`       | `boolean \| string`                                            | Hayır   | `false`                                 | Bağlanırken zil sesi çalar. Varsayılan zil sesi için `true`, özel ses için ise bir URL dizesi kullanın.                                                                                    |

***

## Örnekler

### Özel Renkli Koyu Tema

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

### Özel Konum

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

### Oturum Başına Dil, Ses ve Bağlam

Bir arama başladığında `language`, `voice` ve `context` prop'ları oturum isteğine (`POST /widget/session`) iletilir ve bu oturum için ajanın yapılandırılmış varsayılanlarını geçersiz kılar:

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

`context` özelliğini, ziyaretçinin bulunduğu sayfa hakkında ajana ürün ayrıntıları, fiyatlandırma veya sayfaya özel sık sorulan sorular gibi olgusal bilgiler sağlamak için kullanın. Bu değer sunucu tarafında 12.000 karakterle sınırlanır.

### Olay Geri Çağrılarıyla

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

### Özel Stille

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

Kullanılabilir tüm CSS sınıfları ve özel özellikler için [Stil kılavuzuna](/tr/widget/styling) bakın.

### Zil Sesiyle

Bağlantı kurulurken telefon çalma sesi çalın:

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

Bir ses dosyası URL'si ileterek özel zil sesi kullanın:

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

Bileşen `connecting` durumundayken zil sesi döngü halinde çalar ve yapay zeka ajanı bağlandığında yumuşakça azalır.

### Özel API Tabanıyla

<Tip>
  `apiBase` değerini yalnızca kendi barındırdığınız veya proxy API uç noktası kullanıyorsanız ayarlamanız gerekir. Varsayılan değer `https://api.thunderphone.com/v1` adresini gösterir.
</Tip>

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

***

## Hata İşleme

`onError` geri çağrısı tetiklendiğinde, iki alan içeren bir hata nesnesi alır:

| Alan      | Tür      | Açıklama                                    |
| --------- | -------- | ------------------------------------------- |
| `error`   | `string` | Makine tarafından okunabilir hata kodu      |
| `message` | `string` | İnsan tarafından okunabilir hata açıklaması |

Yaygın hata kodları arasında izin verilmeyen alan adı, bulunamayan ajan ve geçersiz API anahtarı yer alır.

***

## Sonraki Adımlar

<CardGroup cols={2}>
  <Card title="Headless Hook" icon="code" href="/tr/widget/headless-hook">
    Arayüz üzerinde tam kontrol mü istiyorsunuz? Bunun yerine `useThunderPhone` hook'unu kullanın.
  </Card>

  <Card title="Stil Özelleştirme" icon="palette" href="/tr/widget/styling">
    CSS özel özellikleriyle renkleri, boyutları ve düzeni özelleştirin.
  </Card>
</CardGroup>