React-component

Sluit de ThunderPhone-spraakwidget in een React-applicatie in

De component ThunderPhoneWidget rendert een glasmorfische oproepbalk met ingebouwde bedieningselementen voor dempen, het beëindigen van de oproep en het weergeven van de verbindingsstatus. Dit is de snelste manier om spraak-AI aan een React-app toe te voegen.

Installatie

npm install @thunderphone/widget

Basisgebruik

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
    />
  )
}

Props

De component accepteert de volgende props via ThunderPhoneWidgetProps:

Prop	Type	Vereist	Standaard	Beschrijving
`publishableKey`	`string`	Ja	--	Publiceerbare API-sleutel (`pk_live_...`) uit de Ontwikkelaarsinstellingen. De agent wordt automatisch bepaald op basis van de widgetconfiguratie van de sleutel.
`theme`	`'light' \| 'dark'`	Nee	`'light'`	Kleurenschema. Past de klasse `tp--light` of `tp--dark` toe op de hoofdcontainer van de widget.
`primaryColor`	`string`	Nee	`'#000000'` (licht) / `'#ffffff'` (donker)	CSS-kleurtekenreeks die wordt gebruikt als accentkleur (oproepknop, golfvorm, actieve indicatoren).
`title`	`string`	Nee	`'Voice assistant'`	Tekst die wordt weergegeven in de widgetbalk.
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	Nee	`'bottom-right'`	Vaste viewportpositie voor de widget.
`apiBase`	`string`	Nee	`'https://api.thunderphone.com/v1'`	Overschrijving van de basis-URL van de API.
`language`	`string`	Nee	--	Taaloverschrijving per sessie -- een taalcode of landinstelling zoals `en`, `es` of `fr-FR`. Wanneer deze niet is ingesteld, wordt de geconfigureerde taal van de agent gebruikt.
`voice`	`string`	Nee	--	Spraakoverschrijving per sessie -- een spraaknaam zoals `maria`. Wanneer deze niet is ingesteld, wordt de geconfigureerde stem van de agent gebruikt.
`context`	`string`	Nee	--	Feitelijke pagina- of sitecontext per sessie die aan de agent wordt doorgegeven (bijvoorbeeld details van de pagina die de bezoeker bekijkt). Server-side afgekapt tot 12.000 tekens.
`onConnect`	`() => void`	Nee	--	Aangeroepen wanneer de spraaksessie succesvol verbinding maakt.
`onDisconnect`	`() => void`	Nee	--	Aangeroepen wanneer de sessie eindigt.
`onError`	`(error) => void`	Nee	--	Aangeroepen bij fouten. Het object `error` heeft de velden `error` (code) en `message`.
`className`	`string`	Nee	--	Extra CSS-klassennaam die wordt toegepast op de widgetcontainer.
`ringtone`	`boolean \| string`	Nee	`false`	Speel een beltoon af tijdens het verbinden. `true` voor de standaardbeltoon, of een URL-tekenreeks voor aangepaste audio.

Voorbeelden

Donker thema met aangepaste kleur

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

Aangepaste positie

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      position="bottom-left"
    />
  )
}

Taal, stem en context per sessie

De props language, voice en context worden bij het starten van een oproep doorgestuurd naar het sessieverzoek (POST /widget/session) en overschrijven voor die sessie de geconfigureerde standaardwaarden van de agent:

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

Gebruik context om de agent feitelijke kennis te geven over de pagina waarop de bezoeker zich bevindt: productdetails, prijzen of veelgestelde vragen die specifiek zijn voor de pagina. Deze wordt aan serverzijde afgekapt op 12.000 tekens.

Met eventcallbacks

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

Met aangepaste styling

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

Zie de stylinggids voor alle beschikbare CSS-klassen en aangepaste eigenschappen.

Met beltoon

Speel een telefoongerinkel af terwijl de verbinding tot stand wordt gebracht:

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function PhoneWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      ringtone={true}
    />
  )
}

Gebruik een aangepaste beltoon door een URL van een audiobestand door te geven:

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

De beltoon wordt herhaald terwijl de widget de status connecting heeft en vervaagt soepel wanneer de agent verbinding maakt.

Met aangepaste API-basis

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

Foutafhandeling

Wanneer de callback onError wordt aangeroepen, ontvangt deze een foutobject met twee velden:

Veld	Type	Beschrijving
`error`	`string`	Machineleesbare foutcode
`message`	`string`	Leesbare foutbeschrijving

Veelvoorkomende foutcodes zijn onder meer domein niet toegestaan, agent niet gevonden en ongeldige API-sleutel.

Volgende stappen

Headless Hook

Wil je volledige controle over de UI? Gebruik dan de useThunderPhone-hook.

Styling

Pas kleuren, formaten en lay-out aan met aangepaste CSS-eigenschappen.