React komponentas

Komponentas ThunderPhoneWidget pateikia stiklo efekto skambučių juostą su integruotais nutildymo, skambučio baigimo ir ryšio būsenos rodymo valdikliais. Tai greičiausias būdas pridėti balso DI prie React programos.

Diegimas

npm install @thunderphone/widget

Pagrindinis naudojimas

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

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

Savybės

Komponentas priima šias savybes per ThunderPhoneWidgetProps:

Savybė	Tipas	Būtina	Numatytoji reikšmė	Aprašymas
`publishableKey`	`string`	Taip	--	Viešas API raktas (`pk_live_...`) iš Kūrėjų nustatymų. Agentas automatiškai nustatomas pagal rakto valdiklio konfigūraciją.
`theme`	`'light' \| 'dark'`	Ne	`'light'`	Spalvų schema. Valdiklio šakniniam elementui priskiria `tp--light` arba `tp--dark` klasę.
`primaryColor`	`string`	Ne	`'#000000'` (šviesi) / `'#ffffff'` (tamsi)	CSS spalvos eilutė, naudojama kaip akcento spalva (skambučio mygtukas, bangos forma, aktyvūs indikatoriai).
`title`	`string`	Ne	`'Voice assistant'`	Valdiklio juostoje rodomas tekstas.
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	Ne	`'bottom-right'`	Fiksuota valdiklio padėtis peržiūros srityje.
`apiBase`	`string`	Ne	`'https://api.thunderphone.com/v1'`	API bazinio URL pakeitimas.
`language`	`string`	Ne	--	Vienos sesijos kalbos pakeitimas -- kalbos kodas arba lokalė, pvz., `en`, `es` arba `fr-FR`. Kai nenustatyta, taikoma sukonfigūruota agento kalba.
`voice`	`string`	Ne	--	Vienos sesijos balso pakeitimas -- balso pavadinimas, pvz., `maria`. Kai nenustatyta, taikomas sukonfigūruotas agento balsas.
`context`	`string`	Ne	--	Agentui perduodamas vienos sesijos faktinis puslapio arba svetainės kontekstas (pavyzdžiui, informacija apie puslapį, kurį lankytojas peržiūri). Serverio pusėje sutrumpinama iki 12 000 simbolių.
`onConnect`	`() => void`	Ne	--	Iškviečiama, kai balso sesija sėkmingai prisijungia.
`onDisconnect`	`() => void`	Ne	--	Iškviečiama, kai sesija baigiama.
`onError`	`(error) => void`	Ne	--	Iškviečiama įvykus klaidoms. Objektas `error` turi laukus `error` (kodas) ir `message`.
`className`	`string`	Ne	--	Papildomas CSS klasės pavadinimas, priskiriamas valdiklio konteineriui.
`ringtone`	`boolean \| string`	Ne	`false`	Leisti skambėjimo toną, kol užmezgamas ryšys. `true` naudoja numatytąjį skambėjimo toną, o URL eilutė -- pasirinktinį garsą.

Pavyzdžiai

Tamsi tema su pasirinkta spalva

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

Pasirinkta pozicija

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

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

Kalba, balsas ir kontekstas kiekvienai sesijai

Prasidėjus skambučiui, language, voice ir context rekvizitai perduodami sesijos užklausai (POST /widget/session), pakeisdami tam seansui sukonfigūruotas numatytąsias agento reikšmes:

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

Naudokite context, kad suteiktumėte agentui faktinių žinių apie puslapį, kuriame yra lankytojas: produkto informaciją, kainodarą ar konkretaus puslapio dažnai užduodamus klausimus. Serverio pusėje jis sutrumpinamas iki 12 000 simbolių.

Su įvykių atgaliniais iškvietimais

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

Su pasirinktu stiliumi

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

Visas galimas CSS klases ir tinkintas savybes rasite stiliaus vadove.

Su skambėjimo tonu

Kol nustatomas ryšys, leiskite telefono skambėjimo garsą:

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

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

Naudokite pasirinktą skambėjimo toną, perduodami garso failo URL:

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

Skambėjimo tonas kartojamas, kol valdiklio būsena yra connecting, ir sklandžiai nutyla, kai prisijungia agentas.

Su pasirinkta API baze

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

Klaidų tvarkymas

Suveikus onError atgaliniam iškvietimui, jis gauna klaidos objektą su dviem laukais:

Laukas	Tipas	Aprašas
`error`	`string`	Kompiuterio skaitomas klaidos kodas
`message`	`string`	Žmogui suprantamas klaidos aprašas

Dažniausi klaidų kodai apima neleidžiamą domeną, nerastą agentą ir netinkamą API raktą.

Tolesni veiksmai

Headless Hook

Reikia visiškos naudotojo sąsajos kontrolės? Vietoje to naudokite useThunderPhone kablį.

Stilius

Tinkinkite spalvas, dydžius ir išdėstymą naudodami CSS pasirinktines ypatybes.