React komponenta

Komponenta ThunderPhoneWidget prikazuje staklastu traku za pozive s ugrađenim kontrolama za isključivanje zvuka, završavanje poziva i prikaz statusa veze. To je najbrži način za dodavanje glasovnog AI-ja u React aplikaciju.

Instalacija

npm install @thunderphone/widget

Osnovna upotreba

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

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

Svojstva

Komponenta prihvaća sljedeća svojstva putem ThunderPhoneWidgetProps:

Svojstvo	Vrsta	Obavezno	Zadano	Opis
`publishableKey`	`string`	Da	--	Javni API ključ (`pk_live_...`) iz postavki za razvojne programere. Agent se automatski određuje iz konfiguracije widgeta tog ključa.
`theme`	`'light' \| 'dark'`	Ne	`'light'`	Shema boja. Primjenjuje klasu `tp--light` ili `tp--dark` na korijenski element widgeta.
`primaryColor`	`string`	Ne	`'#000000'` (svijetla) / `'#ffffff'` (tamna)	CSS niz boje koji se koristi kao naglasna boja (gumb za poziv, valni oblik, aktivni indikatori).
`title`	`string`	Ne	`'Voice assistant'`	Tekst prikazan u traci widgeta.
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	Ne	`'bottom-right'`	Fiksni položaj widgeta u prikazu.
`apiBase`	`string`	Ne	`'https://api.thunderphone.com/v1'`	Nadjačavanje osnovnog URL-a API-ja.
`language`	`string`	Ne	--	Nadjačavanje jezika po sesiji -- jezični kod ili regionalna postavka, kao što su `en`, `es` ili `fr-FR`. Ako nije postavljeno, primjenjuje se konfigurirani jezik agenta.
`voice`	`string`	Ne	--	Nadjačavanje glasa po sesiji -- naziv glasa, kao što je `maria`. Ako nije postavljeno, primjenjuje se konfigurirani glas agenta.
`context`	`string`	Ne	--	Činjenični kontekst stranice ili web-mjesta po sesiji koji se prosljeđuje agentu (na primjer, pojedinosti stranice koju posjetitelj pregledava). Na poslužitelju se skraćuje na 12.000 znakova.
`onConnect`	`() => void`	Ne	--	Poziva se kada se glasovna sesija uspješno poveže.
`onDisconnect`	`() => void`	Ne	--	Poziva se kada sesija završi.
`onError`	`(error) => void`	Ne	--	Poziva se pri pogreškama. Objekt `error` ima polja `error` (kôd) i `message`.
`className`	`string`	Ne	--	Dodatni naziv CSS klase primijenjen na spremnik widgeta.
`ringtone`	`boolean \| string`	Ne	`false`	Reproducira melodiju zvona tijekom povezivanja. `true` za zadanu melodiju zvona ili URL niz za prilagođeni zvuk.

Primjeri

Tamna tema s prilagođenom bojom

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

Prilagođeni položaj

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

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

Jezik, glas i kontekst po sesiji

Svojstva language, voice i context prosljeđuju se zahtjevu za sesiju (POST /widget/session) pri pokretanju poziva te za tu sesiju nadjačavaju zadano konfigurirane postavke agenta:

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

Upotrijebite context da biste agentu pružili činjenične informacije o stranici na kojoj se posjetitelj nalazi -- pojedinosti o proizvodu, cijene ili česta pitanja specifična za stranicu. Na poslužitelju se skraćuje na 12.000 znakova.

S povratnim pozivima događaja

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

S prilagođenim stilom

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

Pogledajte vodič za stiliziranje za sve dostupne CSS klase i prilagođena svojstva.

Sa zvukom zvonjenja

Reproducirajte zvuk zvonjenja telefona tijekom uspostavljanja veze:

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

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

Upotrijebite prilagođeni zvuk zvonjenja prosljeđivanjem URL-a audiodatoteke:

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

Zvuk zvonjenja ponavlja se dok je widget u stanju connecting i postupno se stišava kada se agent poveže.

S prilagođenom osnovom API-ja

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

Rukovanje pogreškama

Kada se aktivira povratni poziv onError, prima objekt pogreške s dvama poljima:

Polje	Vrsta	Opis
`error`	`string`	Strojno čitljiv kôd pogreške
`message`	`string`	Čovjeku čitljiv opis pogreške

Uobičajeni kôdovi pogrešaka uključuju nedopuštenu domenu, agenta koji nije pronađen i nevažeći API ključ.

Sljedeći koraci

Headless Hook

Trebate potpunu kontrolu nad korisničkim sučeljem? Umjesto toga upotrijebite hook useThunderPhone.

Stiliziranje

Prilagodite boje, veličine i raspored pomoću prilagođenih CSS svojstava.