React-komponens - ThunderPhone

A ThunderPhoneWidget komponens egy üvegszerű hívássávot jelenít meg beépített vezérlőkkel a némításhoz, a hívás befejezéséhez és a kapcsolati állapot megjelenítéséhez. Ez a leggyorsabb módja annak, hogy hangalapú AI-t adjon egy React-alkalmazáshoz.

Telepítés

npm install @thunderphone/widget

Alapvető használat

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

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

A widget megfelelő megjelenítéséhez kötelező importálnia a CSS-fájlt. Enélkül a widget formázatlan lesz.

Kellékek

A komponens a következő kellékeket fogadja el a ThunderPhoneWidgetProps segítségével:

Kellék	Típus	Kötelező	Alapértelmezett	Leírás
`publishableKey`	`string`	Igen	—	A Fejlesztői beállításokban található nyilvános API-kulcs (`pk_live_...`). Az AI-ügynök automatikusan meghatározásra kerül a kulcs widgetkonfigurációja alapján.
`theme`	`'light' \| 'dark'`	Nem	`'light'`	Színséma. A `tp--light` vagy `tp--dark` osztályt alkalmazza a widget gyökérelemére.
`primaryColor`	`string`	Nem	`'#000000'` (világos) / `'#ffffff'` (sötét)	Akcentusszínként használt CSS-színkarakterlánc (hívásgomb, hullámforma, aktív jelzők).
`title`	`string`	Nem	`'Voice assistant'`	A widget sávjában megjelenített szöveg.
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	Nem	`'bottom-right'`	A widget rögzített pozíciója a nézetablakban.
`apiBase`	`string`	Nem	`'https://api.thunderphone.com/v1'`	API-alap URL felülbírálása.
`language`	`string`	Nem	—	Munkamenetenkénti nyelvi felülbírálás — nyelvkód vagy területi beállítás, például `en`, `es` vagy `fr-FR`. Ha nincs beállítva, az AI-ügynök konfigurált nyelve érvényes.
`voice`	`string`	Nem	—	Munkamenetenkénti hangfelülbírálás — hangnév, például `maria`. Ha nincs beállítva, az AI-ügynök konfigurált hangja érvényes.
`context`	`string`	Nem	—	Az AI-ügynöknek átadott, munkamenetenkénti tényszerű oldal- vagy webhelykontextus (például a látogató által megtekintett oldal részletei). A szerveroldalon 12 000 karakterre csonkolva.
`onConnect`	`() => void`	Nem	—	Akkor hívódik meg, amikor a hangmunkamenet sikeresen csatlakozik.
`onDisconnect`	`() => void`	Nem	—	Akkor hívódik meg, amikor a munkamenet véget ér.
`onError`	`(error) => void`	Nem	—	Hibák esetén hívódik meg. Az `error` objektum `error` (kód) és `message` mezőkkel rendelkezik.
`className`	`string`	Nem	—	A widget tárolójára alkalmazott további CSS-osztálynév.
`ringtone`	`boolean \| string`	Nem	`false`	Csengőhang lejátszása csatlakozás közben. `true` az alapértelmezett csengőhanghoz, vagy URL-karakterlánc egyéni hanganyaghoz.

Példák

Sötét téma egyéni színnel

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

Egyéni pozíció

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

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

Munkamenetenkénti nyelv, hang és kontextus

A language, voice és context propok a hívás indításakor továbbításra kerülnek a munkamenet-kérelemnek (POST /widget/session), és felülírják az ügynök adott munkamenethez beállított alapértelmezett értékeit:

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

A context segítségével tényszerű információkat adhat az ügynöknek arról az oldalról, amelyen a látogató tartózkodik – például termékadatokat, árakat vagy oldalspecifikus gyakori kérdéseket. A rendszer szerveroldalon 12 000 karakterre csonkítja.

Esemény-visszahívásokkal

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

Egyéni stílussal

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

Az összes elérhető CSS-osztályt és egyéni tulajdonságot a Stílusútmutatóban találja.

Csengőhanggal

Játsszon le telefoncsörgő hangot a kapcsolat létrehozása közben:

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

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

Adjon meg egy hangfájl-URL-t egyéni csengőhang használatához:

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

A csengőhang ismétlődik, amíg a widget connecting állapotban van, és finoman elhalkul, amikor az ügynök kapcsolódik.

Egyéni API-alappal

A apiBase beállítására csak saját üzemeltetésű vagy proxy API-végpont használatakor van szükség. Az alapértelmezett érték a https://api.thunderphone.com/v1 címre mutat.

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

Hibakezelés

Amikor az onError visszahívás lefut, egy két mezőt tartalmazó hibaobjektumot kap:

Mező	Típus	Leírás
`error`	`string`	Géppel olvasható hibakód
`message`	`string`	Ember által olvasható hibaleírás

A gyakori hibakódok közé tartozik a nem engedélyezett domain, a nem található ügynök és az érvénytelen API-kulcs.

Következő lépések

Headless Hook

Teljes irányítást szeretne a felhasználói felület felett? Használja inkább a useThunderPhone hookot.

Stílusok

Szabja testre a színeket, méreteket és az elrendezést CSS egyéni tulajdonságokkal.

​Telepítés

​Alapvető használat

​Kellékek

​Példák

​Sötét téma egyéni színnel

​Egyéni pozíció

​Munkamenetenkénti nyelv, hang és kontextus

​Esemény-visszahívásokkal

​Egyéni stílussal

​Csengőhanggal

​Egyéni API-alappal

​Hibakezelés

​Következő lépések

Headless Hook

Stílusok

Telepítés

Alapvető használat

Kellékek

Példák

Sötét téma egyéni színnel

Egyéni pozíció

Munkamenetenkénti nyelv, hang és kontextus

Esemény-visszahívásokkal

Egyéni stílussal

Csengőhanggal

Egyéni API-alappal

Hibakezelés

Következő lépések