---
title: "Gömülebilir Sesli Widget"
description: "Birkaç satır kodla herhangi bir web sitesine sesli AI ajanı ekleyin"
---

ThunderPhone yerleştirilebilir ses widget'ı, web sitenizin ziyaretçilerinin tarayıcıdan doğrudan bir yapay zeka ajanıyla konuşmasını sağlar. Telefon görüşmesi gerekmez -- kullanıcılar bir düğmeye tıklar ve ThunderPhone destekli gerçek zamanlı sesli görüşme başlatır.

Widget, özelleştirilebilir vurgu renkleri ve konumlandırmayla açık ve koyu temalara uyum sağlayan cam efektli bir çubuk olarak görüntülenir. `@thunderphone/widget` npm paketi olarak dağıtılır ve paketleyici kullanılmayan ortamlar için CDN üzerinden de kullanılabilir.

<Frame>
  <img src="/images/widget-showcase.png" alt="Çeşitli vurgu renkleriyle açık ve koyu temalarda ThunderPhone widget'ı" />
</Frame>

## Ön Koşullar

Widget'ı yerleştirmeden önce [ThunderPhone Dashboard](https://app.thunderphone.com) içinde şu üç adımı tamamlayın:

<Steps>
<Step title="Web bileşeni oluşturun">
  Kontrol panelinde **Web Bileşenleri** bölümüne gidin ve bir bileşen oluşturun. Kullanıma sunmak istediğiniz yapay zeka ajanını seçin. Her bileşenin kendine ait bir yayınlanabilir anahtarı (`pk_live_...`) vardır; bu anahtarı istemci tarafı koduna eklemek güvenlidir ve yapay zeka ajanı anahtardan belirlenir.
</Step>

<Step title="İzin verilen alan adlarını yapılandırın">
  Aynı bileşende, bileşenin gömüleceği alan adlarını ekleyin. Joker karakterler desteklenir (ör. `*.example.com`). Bu liste, birisi anahtarınızı başka bir siteye kopyaladığında bileşenin çalışmasını engeller; tarayıcı dışındaki bir betik herhangi bir `Origin` üst bilgisi gönderebildiğinden kimlik doğrulama sağlamaz. `localhost` üretimde otomatik olarak izinli değildir: üretim API'sine karşı yerel olarak test etmek için listeye ekleyin.
</Step>

<Step title="Tarayıcı geçersiz kılmalarını seçin">
  Sayfanız `language`, `voice` veya `context` ayarlıyorsa, her birini **Tarayıcı geçersiz kılmaları** altında etkinleştirin. Yeni bileşenler hiçbirini kabul etmez ve kapalı bir ayarı içeren oturum isteği `400 override_not_allowed` hatasıyla başarısız olur. Bkz. [Tarayıcı geçersiz kılmaları](/tr/guides/embed-web-widget).
</Step>
</Steps>

<Warning>
  Yayınlanabilir anahtarlar (`pk_live_...`), gizli API belirteçlerinizle **aynı değildir**. Yayınlanabilir anahtarlar istemci tarafında kullanım için tasarlanmıştır ve izin verilen alan adlarınızdaki widget oturumlarıyla sınırlıdır. Gizli API belirtecinizi asla istemci tarafı kodunda kullanmayın.
</Warning>

<Note>
  Bileşen oturumları varsayılan olarak 30 dakika sonra veya yapay zeka ajanının kendi maksimum arama süresi daha kısaysa daha erken sona erer. Her anahtar için sınırı [yayınlanabilir anahtarda](/api-reference/publishable-keys) `max_call_duration_seconds` ile değiştirin (en fazla 6 saat) ya da yapay zeka ajanının kendi sınırını kullanmak için `null` olarak ayarlayın.
</Note>

---

## Hızlı Başlangıç

Paketi yükleyin:

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

Widget'ı uygulamanıza ekleyin:

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

Hepsi bu kadar. Kullanıcılarınız, tek tıklamayla onları yapay zeka ajanınıza bağlayan cam efektli bir arama çubuğu görecektir.

---

## Özelleştirme

Widget'ın görünüm için dört prop'u vardır:

| Prop | Varsayılan | Açıklama |
|------|---------|-------------|
| `theme` | `'light'` | Beyaz cam için `'light'`, koyu cam için `'dark'` |
| `primaryColor` | `'#000000'` (açık) / `'#ffffff'` (koyu) | Başlat düğmesi, dalga formu ve bağlanma göstergesi için vurgu rengi |
| `title` | `'Voice assistant'` | Widget'ta görüntülenen metin |
| `position` | `'bottom-right'` | Görüntü alanı köşesi: `'bottom-right'`, `'bottom-left'`, `'top-right'`, `'top-left'` |

<CodeGroup>
```tsx Light theme (default)
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
/>
```

```tsx Dark theme with custom color
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="dark"
  primaryColor="#8b5cf6"
  title="Ask our AI"
/>
```
</CodeGroup>

Üç ek prop görünüm yerine oturumu özelleştirir -- bir çağrı başladığında tümü oturum isteğine iletilir. Her biri yalnızca widget'ın yayınlanabilir anahtarı **Tarayıcı geçersiz kılmaları** altında buna izin veriyorsa çalışır; aksi takdirde oturum isteği `400 override_not_allowed` ile başarısız olur:

| Prop | Açıklama |
|------|-------------|
| `language` | Oturum başına dil geçersiz kılma -- `en`, `es` veya `fr-FR` gibi bir kod ya da yerel ayar |
| `voice` | Oturum başına ses geçersiz kılma -- `maria` gibi bir ses adı |
| `context` | Ajana iletilen olgusal sayfa veya site bağlamı (sunucu tarafında 12.000 karaktere kısaltılır) |

Prop tablosunun tamamı için [React bileşeni referansına](/tr/widget/react) bakın.

Tamamen özel bir kullanıcı arayüzü için, kendi arayüzünüzü oluştururken sesli oturumu yönetmek üzere [headless hook'u](/tr/widget/headless-hook) kullanın. Hook, sese tepki veren görselleştirmeler oluşturmak için gerçek zamanlı ses seviyelerini sunar.

Her widget görüşmesi bir çağrıdır. Kuruluşunuzun [eşzamanlı çağrı sınırına](/api-reference/introduction#call-limits) (varsayılan olarak devam eden 20 çağrı; telefon ve diğer çağrılarla paylaşılır) ve 25 etkin oturumluk widget sınırına (veya daha yüksekse eşzamanlı çağrı sınırınıza) dahil edilir. Herhangi bir sınıra ulaşıldığında, bir çağrı sona erene kadar yeni bir görüşme başlatılamaz.

---

## Entegrasyon Seçenekleri

Teknoloji yığınınıza uygun entegrasyon yöntemini seçin:

<CardGroup cols={3}>
  <Card title="React Bileşeni" icon="react" href="/tr/widget/react">
    Yerleşik arama kontrolleri ve durum göstergesi içeren hazır kullanıcı arayüzü bileşeni. İçe aktarın, prop'ları iletin, işlem tamam.
  </Card>
  <Card title="Headless Hook" icon="code" href="/tr/widget/headless-hook">
    Kullanıcı arayüzü üzerinde tam kontrol. Siz kendi arayüzünüzü oluştururken `useThunderPhone` hook'u sesli oturumu yönetir.
  </Card>
  <Card title="CDN / Script Etiketi" icon="globe" href="/tr/widget/cdn-script-tag">
    Bundler gerekmez. Statik siteler, WordPress ve React dışındaki diğer ortamlar için widget'ı bir script etiketiyle yükleyin.
  </Card>
</CardGroup>

---

## Stil

Widget, `theme` prop'u ile kontrol edilen yerleşik açık ve koyu temalar ile `primaryColor` prop'u ile kontrol edilen bir vurgu rengi sunar. Daha kapsamlı özelleştirme için CSS özel özelliklerini ve sınıflarını geçersiz kılabilirsiniz. Ayrıntılar için [Stil rehberine](/tr/widget/styling) bakın.

<Note>
  Yardıma mı ihtiyacınız var? [support@thunderphone.com](mailto:support@thunderphone.com) adresinden bizimle iletişime geçin.
</Note>