---
title: "Στοιχείο React"
description: "Ενσωματώστε το φωνητικό γραφικό στοιχείο ThunderPhone σε μια εφαρμογή React"
---

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

## Εγκατάσταση

```bash
npm install @thunderphone/widget
```

## Βασική χρήση

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

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

<Warning>
  **Πρέπει** να εισαγάγετε το αρχείο CSS ώστε το widget να αποδίδεται σωστά. Χωρίς αυτό, το widget δεν θα έχει στυλ.
</Warning>

---

## Ιδιότητες

Το στοιχείο δέχεται τις παρακάτω ιδιότητες μέσω του `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 για προσαρμοσμένο ήχο. |

---

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

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

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

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

```tsx
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`) όταν ξεκινά μια κλήση, παρακάμπτοντας τις προεπιλεγμένες ρυθμίσεις του πράκτορα για τη συγκεκριμένη συνεδρία:

```tsx
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 χαρακτήρες.

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

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

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

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

```css
.my-custom-widget .tp-button--end {
  background-color: #e74c3c;
}
```

Δείτε τον [οδηγό μορφοποίησης](/el/widget/styling) για όλες τις διαθέσιμες κλάσεις CSS και τις προσαρμοσμένες ιδιότητες.

### Με ήχο κλήσης

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

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

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

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

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

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

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

<Tip>
  Χρειάζεται να ορίσετε το `apiBase` μόνο αν χρησιμοποιείτε αυτοφιλοξενούμενο τελικό σημείο API ή τελικό σημείο API μέσω διακομιστή μεσολάβησης. Η προεπιλογή δείχνει στο `https://api.thunderphone.com/v1`.
</Tip>

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

---

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

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

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

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

---

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

<CardGroup cols={2}>
  <Card title="Headless Hook" icon="code" href="/el/widget/headless-hook">
    Χρειάζεστε πλήρη έλεγχο του UI; Χρησιμοποιήστε αντί αυτού το hook `useThunderPhone`.
  </Card>
  <Card title="Στυλ" icon="palette" href="/el/widget/styling">
    Προσαρμόστε χρώματα, μεγέθη και διάταξη με προσαρμοσμένες ιδιότητες CSS.
  </Card>
</CardGroup>