CDN / Tag script

La build CDN include React internamente, quindi puoi usare il widget su siti statici, WordPress, Webflow o qualsiasi pagina in cui puoi aggiungere HTML. Non sono necessari npm, bundler o framework.

URL CDN

<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>

<!-- Each stable release also publishes an immutable /widget/vX.Y.Z/ path
     matching the @thunderphone/widget npm version (v1.1.2 at the time of
     writing). If you pin, you own updating the URL for new releases. -->
<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/v1.1.2/style.css" />
<script src="https://cdn.thunderphone.com/widget/v1.1.2/widget.js"></script>

Gli URL latest sono quelli generati dal generatore di snippet di incorporamento della dashboard. Vengono memorizzati nella cache per 5 minuti e includono automaticamente le nuove release stabili. I percorsi /widget/vX.Y.Z/ con versione fissata sono immutabili e memorizzati nella cache a lungo termine — se fissi una versione, assicurati che corrisponda alla release npm @thunderphone/widget su cui sviluppi.

Utilizzo di base

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
</head>
<body>

  <div id="thunderphone"></div>

  <script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
  <script>
    ThunderPhone.mount({
      element: '#thunderphone',
      publishableKey: 'pk_live_your_publishable_key',
    })
  </script>

</body>
</html>

Il widget viene montato nell’elemento di destinazione e viene visualizzato come una barra a posizione fissa in un angolo della viewport (impostazione predefinita bottom-right, controllata dall’opzione position). L’elemento di montaggio è solo la root React — la sua posizione nella pagina non influisce sul punto in cui appare il widget.

Opzioni di montaggio

ThunderPhone.mount() accetta le stesse opzioni del componente React, oltre alla proprietà element:

Opzione	Tipo	Obbligatoria	Predefinito	Descrizione
`element`	`string \| HTMLElement`	Sì	—	Selettore CSS (ad es. `'#thunderphone'`) o riferimento a un elemento DOM.
`publishableKey`	`string`	Sì	—	Chiave API pubblicabile (`pk_live_...`). L’agente viene risolto automaticamente dalla configurazione del widget della chiave.
`theme`	`'light' \| 'dark'`	No	`'light'`	Schema colori.
`primaryColor`	`string`	No	`'#000000'` (chiaro) / `'#ffffff'` (scuro)	Stringa di colore CSS usata come colore di accento.
`title`	`string`	No	`'Voice assistant'`	Testo visualizzato nella barra del widget.
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	No	`'bottom-right'`	Posizione fissa nella viewport.
`apiBase`	`string`	No	`'https://api.thunderphone.com/v1'`	Override dell’URL di base dell’API.
`language`	`string`	No	—	Override della lingua per sessione — un codice lingua o una locale come `en`, `es` o `fr-FR`. Se non impostata, viene applicata la lingua configurata dell’agente.
`voice`	`string`	No	—	Override della voce per sessione — un nome voce come `maria`. Se non impostata, viene applicata la voce configurata dell’agente.
`context`	`string`	No	—	Contesto fattuale della pagina o del sito per sessione passato all’agente. Troncato lato server a 12.000 caratteri.
`onConnect`	`() => void`	No	—	Chiamata quando la sessione vocale si connette.
`onDisconnect`	`() => void`	No	—	Chiamata quando termina la sessione.
`onError`	`(error) => void`	No	—	Chiamata in caso di errori. L’errore contiene i campi `error` (codice) e `message`.
`ringtone`	`boolean \| string`	No	`false`	Riproduci una suoneria durante la connessione. `true` per la suoneria predefinita oppure una stringa URL per audio personalizzato.

Pulizia

ThunderPhone.mount() restituisce un’istanza del widget con metodi di pulizia:

<script>
  var widget = ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
  })

  // Later, when you want to remove the widget:
  widget.unmount()

  // Or equivalently:
  widget.destroy()
</script>

Sia unmount() sia destroy() eseguono la stessa operazione: disconnettono qualsiasi sessione vocale attiva e rimuovono il widget dal DOM. Usa quello che risulta più leggibile nel tuo codice.

Esegui sempre la pulizia del widget quando navighi altrove nelle applicazioni a pagina singola o quando l’elemento contenitore viene rimosso. Questo garantisce che le sessioni vocali attive vengano disconnesse correttamente.

Esempi

Tema scuro con colore personalizzato

<div id="thunderphone"></div>

<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
<script>
  ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
    theme: 'dark',
    primaryColor: '#8b5cf6',
    title: 'Talk to our AI',
  })
</script>

Posizione personalizzata

<div id="thunderphone"></div>

<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
<script>
  ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
    position: 'bottom-left',
  })
</script>

Con callback di evento

<div id="thunderphone"></div>

<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
<script>
  ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
    onConnect: function () {
      console.log('Call started')
    },
    onDisconnect: function () {
      console.log('Call ended')
    },
    onError: function (error) {
      console.error('Widget error:', error.error, error.message)
    },
  })
</script>

Con suoneria

<div id="thunderphone"></div>

<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
<script>
  ThunderPhone.mount({
    element: '#thunderphone',
    publishableKey: 'pk_live_your_publishable_key',
    ringtone: true, // or a custom URL: 'https://example.com/ringtone.mp3'
  })
</script>

Utilizzo di un riferimento a un elemento DOM

<div id="thunderphone"></div>

<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>
<script>
  var container = document.getElementById('thunderphone')

  ThunderPhone.mount({
    element: container,
    publishableKey: 'pk_live_your_publishable_key',
  })
</script>

Integrazione WordPress / CMS

Aggiungi questo a un blocco HTML personalizzato o al footer del tuo tema:

<link rel="stylesheet" href="https://cdn.thunderphone.com/widget/latest/style.css" />
<script src="https://cdn.thunderphone.com/widget/latest/widget.js"></script>

<div id="thunderphone-widget"></div>
<script>
  ThunderPhone.mount({
    element: '#thunderphone-widget',
    publishableKey: 'pk_live_your_publishable_key',
  })
</script>

Il <div> può essere inserito ovunque: è solo il punto di montaggio. Il widget viene visualizzato come sovrapposizione fissa in un angolo della viewport (impostato dall’opzione position) e non segue il flusso del contenuto circostante.

Risoluzione dei problemi

Il widget non viene visualizzato

ThunderPhone non è definito

Lo script non è ancora stato caricato. Assicurati che il tag <script> per widget.js compaia prima della chiamata di montaggio oppure racchiudi la chiamata di montaggio in un listener DOMContentLoaded.

Errore: dominio non consentito

Aggiungi il tuo dominio all’elenco dei domini consentiti nelle impostazioni Sviluppatori su app.thunderphone.com. Ricorda che localhost è sempre consentito.

Widget

URL CDN

Utilizzo di base

Opzioni di montaggio

Pulizia

Esempi

Tema scuro con colore personalizzato

Posizione personalizzata

Con callback di evento

Con suoneria

Utilizzo di un riferimento a un elemento DOM

Integrazione WordPress / CMS

Risoluzione dei problemi

Passaggi successivi

Stile

Componente React

​URL CDN

​Utilizzo di base

​Opzioni di montaggio

​Pulizia

​Esempi

​Tema scuro con colore personalizzato

​Posizione personalizzata

​Con callback di evento

​Con suoneria

​Utilizzo di un riferimento a un elemento DOM

​Integrazione WordPress / CMS

​Risoluzione dei problemi

​Passaggi successivi

Stile

Componente React

URL CDN

Utilizzo di base

Opzioni di montaggio

Pulizia

Esempi

Tema scuro con colore personalizzato

Posizione personalizzata

Con callback di evento

Con suoneria

Utilizzo di un riferimento a un elemento DOM

Integrazione WordPress / CMS

Risoluzione dei problemi

Passaggi successivi