Open in

React Bileşeni

ThunderPhone ses widget

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

Özellikler

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

Özellik	Tür	Zorunlu	Varsayılan	Açıklama
`publishableKey`	`string`	Evet	--	Kontrol panelindeki Web Bileşenleri bölümünden alınan yayımlanabilir API anahtarı (`pk_live_...`). Yapay zeka ajanı, anahtarın bileşen yapılandırmasından otomatik olarak belirlenir.
`theme`	`'light' \| 'dark'`	Hayır	`'light'`	Renk şeması. Bileşen 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 dizgesi (arama düğmesi, dalga formu, etkin göstergeler).
`title`	`string`	Hayır	`'Voice assistant'`	Bileşen çubuğunda görüntülenen metin.
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	Hayır	`'bottom-right'`	Bileşen için sabit görünüm 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 kullanılır. Anahtarın tarayıcı geçersiz kılmaları altında `language` gerektirir.
`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 kullanılır. Anahtarın tarayıcı geçersiz kılmaları altında `voice` gerektirir.
`context`	`string`	Hayır	--	Yapay zeka ajanına iletilen, oturum başına sayfa veya siteye ilişkin olgusal bağlam (örneğin, ziyaretçinin görüntülediği sayfanın ayrıntıları). Sunucu tarafında 12.000 karaktere kısaltılır. Anahtarın tarayıcı geçersiz kılmaları altında `context` gerektirir.
`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	--	Bileşen kapsayıcısına uygulanan ek CSS sınıfı adı.
`ringtone`	`boolean \| string`	Hayır	`false`	Bağlanırken zil sesi çalın. Varsayılan zil sesi için `true` veya özel ses için bir URL dizgesi 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. Kullandığınız her prop'u panodaki widget için Tarayıcı geçersiz kılmaları altında (veya anahtarın allowed_overrides alanında) etkinleştirin. Yeni widget'lar hiçbirini kabul etmez ve kapalı olan bir prop içeren oturum isteği 400 override_not_allowed ile başarısız olur; bkz. Tarayıcı geçersiz kılmaları.

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

Ziyaretçinin bulunduğu sayfa hakkında yapay zeka ajanına olgusal bilgi vermek için context kullanın -- ürün ayrıntıları, fiyatlandırma veya sayfaya özel SSS'ler. Ajan bunu talimat olarak değil, sayfa içeriği olarak değerlendirir. Sunucu tarafında 12.000 karakterle kısaltılı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

<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.