Komponenta React

Komponenta ThunderPhoneWidget prikaže klicno vrstico s steklenim videzom in vgrajenimi kontrolniki za utišanje, končanje klica ter prikaz stanja povezave. To je najhitrejši način za dodajanje glasovne umetne inteligence v aplikacijo React.

Namestitev

npm install @thunderphone/widget

Osnovna uporaba

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

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

Lastnosti

Komponenta prek ThunderPhoneWidgetProps sprejema naslednje lastnosti:

Lastnost	Vrsta	Obvezno	Privzeto	Opis
`publishableKey`	`string`	Da	--	Javni ključ API-ja (`pk_live_...`) iz nastavitev za razvijalce. Agent se samodejno določi iz konfiguracije gradnika ključa.
`theme`	`'light' \| 'dark'`	Ne	`'light'`	Barvna shema. Na korensko mesto gradnika uporabi razred `tp--light` ali `tp--dark`.
`primaryColor`	`string`	Ne	`'#000000'` (svetla) / `'#ffffff'` (temna)	Niz z barvo CSS, uporabljen kot poudarjena barva (gumb za klic, valovna oblika, aktivni indikatorji).
`title`	`string`	Ne	`'Voice assistant'`	Besedilo, prikazano v vrstici gradnika.
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	Ne	`'bottom-right'`	Fiksni položaj gradnika v vidnem polju.
`apiBase`	`string`	Ne	`'https://api.thunderphone.com/v1'`	Preglasitev osnovnega URL-ja API-ja.
`language`	`string`	Ne	--	Preglasitev jezika za posamezno sejo -- koda jezika ali krajevne nastavitve, kot so `en`, `es` ali `fr-FR`. Če ni nastavljeno, se uporabi jezik, konfiguriran za agenta.
`voice`	`string`	Ne	--	Preglasitev glasu za posamezno sejo -- ime glasu, kot je `maria`. Če ni nastavljeno, se uporabi glas, konfiguriran za agenta.
`context`	`string`	Ne	--	Dejanski kontekst strani ali spletnega mesta za posamezno sejo, posredovan agentu (na primer podrobnosti strani, ki jo obiskovalec pregleduje). Na strani strežnika je skrajšan na 12.000 znakov.
`onConnect`	`() => void`	Ne	--	Pokliče se, ko je glasovna seja uspešno povezana.
`onDisconnect`	`() => void`	Ne	--	Pokliče se, ko se seja konča.
`onError`	`(error) => void`	Ne	--	Pokliče se ob napakah. Objekt `error` ima polji `error` (koda) in `message`.
`className`	`string`	Ne	--	Dodatno ime razreda CSS, uporabljeno za vsebnik gradnika.
`ringtone`	`boolean \| string`	Ne	`false`	Med povezovanjem predvaja melodijo zvonjenja. `true` za privzeto melodijo zvonjenja ali niz URL za zvok po meri.

Primeri

Temna tema z barvo po meri

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

Položaj po meri

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 in kontekst za posamezno sejo

Lastnosti language, voice in context se ob začetku klica posredujejo zahtevi seje (POST /widget/session) ter za to sejo preglasijo nastavljene privzete vrednosti glasovnega 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%."
    />
  )
}

Uporabite context, da agentu zagotovite dejansko znanje o strani, na kateri je obiskovalec -- podrobnosti o izdelku, cene ali pogosta vprašanja, značilna za stran. Na strežniški strani je skrajšan na 12.000 znakov.

S povratnimi klici dogodkov

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 oblikovanjem po meri

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

Za vse razpoložljive razrede CSS in lastnosti po meri glejte vodnik za oblikovanje.

Z melodijo zvonjenja

Med vzpostavljanjem povezave predvajajte zvok zvonjenja telefona:

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

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

Melodijo zvonjenja po meri uporabite tako, da podate URL zvočne datoteke:

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

Melodija zvonjenja se ponavlja, ko je gradnik v stanju connecting, in gladko utihne, ko se glasovni agent poveže.

Z osnovnim URL-jem API po meri

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

Obravnava napak

Ko se sproži povratni klic onError, prejme objekt napake z dvema poljema:

Polje	Vrsta	Opis
`error`	`string`	Strojno berljiva koda napake
`message`	`string`	Uporabniku razumljiv opis napake

Pogoste kode napak vključujejo nedovoljeno domeno, agenta ni mogoče najti in neveljaven ključ API.

Naslednji koraki

Brezglavni hook

Potrebujete popoln nadzor nad uporabniškim vmesnikom? Namesto tega uporabite hook useThunderPhone.

Oblikovanje

Prilagodite barve, velikosti in postavitev z lastnostmi CSS po meri.