Open in

Στοιχείο React

Ενσωματώστε το φωνητικό γραφικό στοιχείο ThunderPhone σε μια εφαρμογή React

Το στοιχείο ThunderPhoneWidget αποδίδει μια γυάλινη γραμμή κλήσης με ενσωματωμένα χειριστήρια για σίγαση, τερματισμό της κλήσης και εμφάνιση της κατάστασης σύνδεσης. Είναι ο ταχύτερος τρόπος να προσθέσετε φωνητική τεχνητή νοημοσύνη σε μια εφαρμογή React.

Εγκατάσταση

npm install @thunderphone/widget

Βασική χρήση

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

Ιδιότητες

Το στοιχείο δέχεται τις παρακάτω ιδιότητες μέσω του ThunderPhoneWidgetProps:

Ιδιότητα	Τύπος	Απαιτείται	Προεπιλογή	Περιγραφή
`publishableKey`	`string`	Ναι	--	Δημοσιεύσιμο κλειδί API (`pk_live_...`) από τις ρυθμίσεις προγραμματιστών. Ο πράκτορας προσδιορίζεται αυτόματα από τη διαμόρφωση widget του κλειδιού.
`theme`	`'light' \| 'dark'`	Όχι	`'light'`	Συνδυασμός χρωμάτων. Εφαρμόζει την κλάση `tp--light` ή `tp--dark` στη ρίζα του widget.
`primaryColor`	`string`	Όχι	`'#000000'` (ανοιχτό) / `'#ffffff'` (σκούρο)	Συμβολοσειρά χρώματος CSS που χρησιμοποιείται ως χρώμα έμφασης (κουμπί κλήσης, κυματομορφή, ενεργές ενδείξεις).
`title`	`string`	Όχι	`'Voice assistant'`	Κείμενο που εμφανίζεται στη γραμμή του widget.
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	Όχι	`'bottom-right'`	Σταθερή θέση του widget στο viewport.
`apiBase`	`string`	Όχι	`'https://api.thunderphone.com/v1'`	Παράκαμψη του βασικού URL του API.
`language`	`string`	Όχι	--	Παράκαμψη γλώσσας ανά συνεδρία — ένας κωδικός γλώσσας ή τοπικές ρυθμίσεις, όπως `en`, `es` ή `fr-FR`. Όταν δεν ορίζεται, εφαρμόζεται η διαμορφωμένη γλώσσα του πράκτορα.
`voice`	`string`	Όχι	--	Παράκαμψη φωνής ανά συνεδρία — ένα όνομα φωνής, όπως `maria`. Όταν δεν ορίζεται, εφαρμόζεται η διαμορφωμένη φωνή του πράκτορα.
`context`	`string`	Όχι	--	Πραγματολογικό περιβάλλον σελίδας ή ιστότοπου ανά συνεδρία που μεταβιβάζεται στον πράκτορα (για παράδειγμα, λεπτομέρειες της σελίδας που προβάλλει ο επισκέπτης). Περικόπτεται στην πλευρά του διακομιστή στους 12.000 χαρακτήρες.
`onConnect`	`() => void`	Όχι	--	Καλείται όταν η φωνητική συνεδρία συνδέεται επιτυχώς.
`onDisconnect`	`() => void`	Όχι	--	Καλείται όταν λήγει η συνεδρία.
`onError`	`(error) => void`	Όχι	--	Καλείται σε σφάλματα. Το αντικείμενο `error` έχει πεδία `error` (κωδικός) και `message`.
`className`	`string`	Όχι	--	Πρόσθετο όνομα κλάσης CSS που εφαρμόζεται στο κοντέινερ του widget.
`ringtone`	`boolean \| string`	Όχι	`false`	Αναπαραγωγή ήχου κλήσης κατά τη σύνδεση. `true` για τον προεπιλεγμένο ήχο κλήσης ή μια συμβολοσειρά URL για προσαρμοσμένο ήχο.

Παραδείγματα

Σκούρο θέμα με προσαρμοσμένο χρώμα

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

Προσαρμοσμένη θέση

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

Γλώσσα, φωνή και περιβάλλον ανά συνεδρία

Τα props language, voice και context προωθούνται στο αίτημα συνεδρίας (POST /widget/session) όταν ξεκινά μια κλήση, παρακάμπτοντας τις προεπιλεγμένες ρυθμίσεις του πράκτορα για τη συγκεκριμένη συνεδρία:

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

Χρησιμοποιήστε το context για να παρέχετε στον πράκτορα πραγματολογική γνώση σχετικά με τη σελίδα που προβάλλει ο επισκέπτης — λεπτομέρειες προϊόντος, τιμολόγηση ή συχνές ερωτήσεις ειδικές για τη σελίδα. Περικόπτεται στην πλευρά του διακομιστή στους 12.000 χαρακτήρες.

Με επανακλήσεις συμβάντων

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

Με προσαρμοσμένη μορφοποίηση

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

Δείτε τον οδηγό μορφοποίησης για όλες τις διαθέσιμες κλάσεις CSS και τις προσαρμοσμένες ιδιότητες.

Με ήχο κλήσης

Αναπαραγάγετε έναν ήχο κουδουνίσματος τηλεφώνου ενώ δημιουργείται η σύνδεση:

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

Χρησιμοποιήστε προσαρμοσμένο ήχο κλήσης περνώντας ένα URL αρχείου ήχου:

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

Ο ήχος κλήσης επαναλαμβάνεται όσο το widget βρίσκεται στην κατάσταση connecting και εξασθενεί ομαλά όταν συνδέεται ο πράκτορας.

Με προσαρμοσμένη βάση API

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

Διαχείριση σφαλμάτων

Όταν ενεργοποιείται η επανάκληση onError, λαμβάνει ένα αντικείμενο σφάλματος με δύο πεδία:

Πεδίο	Τύπος	Περιγραφή
`error`	`string`	Κωδικός σφάλματος αναγνώσιμος από μηχανή
`message`	`string`	Περιγραφή σφάλματος αναγνώσιμη από άνθρωπο

Οι συνήθεις κωδικοί σφάλματος περιλαμβάνουν μη επιτρεπόμενο τομέα, πράκτορα που δεν βρέθηκε και μη έγκυρο κλειδί API.

Επόμενα βήματα

Headless Hook

Χρειάζεστε πλήρη έλεγχο του UI; Χρησιμοποιήστε αντί αυτού το hook useThunderPhone.

Στυλ

Προσαρμόστε χρώματα, μεγέθη και διάταξη με προσαρμοσμένες ιδιότητες CSS.