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_...) από τα Web Widgets στον πίνακα ελέγχου. Ο πράκτορας προσδιορίζεται αυτόματα από τη διαμόρφωση του 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 στο παράθυρο προβολής. |
apiBase | string | Όχι | 'https://api.thunderphone.com/v1' | Παράκαμψη του βασικού URL του API. |
language | string | Όχι | -- | Παράκαμψη γλώσσας ανά συνεδρία -- κωδικός γλώσσας ή τοπικές ρυθμίσεις, όπως en, es ή fr-FR. Όταν δεν ορίζεται, εφαρμόζεται η διαμορφωμένη γλώσσα του πράκτορα. Απαιτεί language στις παρακάμψεις προγράμματος περιήγησης του κλειδιού. |
voice | string | Όχι | -- | Παράκαμψη φωνής ανά συνεδρία -- όνομα φωνής, όπως maria. Όταν δεν ορίζεται, εφαρμόζεται η διαμορφωμένη φωνή του πράκτορα. Απαιτεί voice στις παρακάμψεις προγράμματος περιήγησης του κλειδιού. |
context | string | Όχι | -- | Πραγματολογικό πλαίσιο σελίδας ή ιστότοπου ανά συνεδρία που μεταβιβάζεται στον πράκτορα (για παράδειγμα, λεπτομέρειες της σελίδας που προβάλλει ο επισκέπτης). Περικόπτεται στον διακομιστή στους 12.000 χαρακτήρες. Απαιτεί context στις παρακάμψεις προγράμματος περιήγησης του κλειδιού. |
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"
/>
)
}Γλώσσα, φωνή και περιβάλλον ανά συνεδρία
Οι ιδιότητες language, voice και context προωθούνται στο αίτημα συνεδρίας (POST /widget/session) όταν ξεκινά μια κλήση, παρακάμπτοντας τις προεπιλογές που έχουν ρυθμιστεί για τον πράκτορα σε αυτή τη συνεδρία. Ενεργοποιήστε κάθε ιδιότητα που χρησιμοποιείτε στις Παρακάμψεις προγράμματος περιήγησης για το widget στον πίνακα ελέγχου (ή στο allowed_overrides του κλειδιού). Τα νέα widget δεν δέχονται καμία και ένα αίτημα συνεδρίας που περιλαμβάνει κάποια απενεργοποιημένη αποτυγχάνει με 400 override_not_allowed; δείτε τις Παρακάμψεις προγράμματος περιήγησης.
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.