Open in

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_...`) van Web Widgets in het dashboard. 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 als accentkleur wordt gebruikt (oproepknop, golfvorm, actieve indicatoren).
`title`	`string`	Nee	`'Voice assistant'`	Tekst die in de widgetbalk wordt weergegeven.
`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 voor de API.
`language`	`string`	Nee	--	Taaloverschrijving per sessie -- een taalcode of landinstelling zoals `en`, `es` of `fr-FR`. Als deze niet is ingesteld, wordt de geconfigureerde taal van de agent toegepast. Vereist `language` onder de browser overrides van de sleutel.
`voice`	`string`	Nee	--	Stemoverschrijving per sessie -- een stemnaam zoals `maria`. Als deze niet is ingesteld, wordt de geconfigureerde stem van de agent toegepast. Vereist `voice` onder de browser overrides van de sleutel.
`context`	`string`	Nee	--	Feitelijke pagina- of sitecontext per sessie die aan de agent wordt doorgegeven (bijvoorbeeld details over de pagina die de bezoeker bekijkt). Aan serverzijde afgekapt tot 12.000 tekens. Vereist `context` onder de browser overrides van de sleutel.
`onConnect`	`() => void`	Nee	--	Wordt aangeroepen wanneer de spraaksessie succesvol verbinding maakt.
`onDisconnect`	`() => void`	Nee	--	Wordt aangeroepen wanneer de sessie eindigt.
`onError`	`(error) => void`	Nee	--	Wordt aangeroepen bij fouten. Het `error`-object heeft de velden `error` (code) en `message`.
`className`	`string`	Nee	--	Aanvullende CSS-klassennaam die op de widgetcontainer wordt toegepast.
`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 doorgestuurd naar het sessieverzoek (POST /widget/session) wanneer een oproep start, en overschrijven de geconfigureerde standaardwaarden van de agent voor die sessie. Schakel elke prop die je gebruikt in onder Browseroverschrijvingen voor de widget in het dashboard (of in de allowed_overrides van de sleutel). Nieuwe widgets accepteren geen overschrijvingen, en een sessieverzoek met een uitgeschakelde overschrijving mislukt met 400 override_not_allowed; zie Browseroverschrijvingen.

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 pagina-specifieke veelgestelde vragen. De agent behandelt dit als pagina-inhoud, niet als instructies. De tekst 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.