React Bileşeni - ThunderPhone

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

npm install @thunderphone/widget

Temel Kullanım

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

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

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.

Ö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

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

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:

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

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

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

.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 bakın.

Zil Sesiyle

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

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:

<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

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.

<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

Headless Hook

Arayüz üzerinde tam kontrol mü istiyorsunuz? Bunun yerine useThunderPhone hook’unu kullanın.

Stil Özelleştirme

CSS özel özellikleriyle renkleri, boyutları ve düzeni özelleştirin.

​Kurulum

​Temel Kullanım

​Özellikler

​Örnekler

​Özel Renkli Koyu Tema

​Özel Konum

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

​Olay Geri Çağrılarıyla

​Özel Stille

​Zil Sesiyle

​Özel API Tabanıyla

​Hata İşleme

​Sonraki Adımlar

Headless Hook

Stil Özelleştirme

Kurulum

Temel Kullanım

Özellikler

Örnekler

Özel Renkli Koyu Tema

Özel Konum

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

Olay Geri Çağrılarıyla

Özel Stille

Zil Sesiyle

Özel API Tabanıyla

Hata İşleme

Sonraki Adımlar