Widget per sito web
Incorpora il tuo agente vocale IA su qualsiasi sito così che i visitatori possano avviare una conversazione vocale direttamente dal browser. La scheda Widgets fornisce codici di incorporamento, opzioni di personalizzazione e impostazioni di sicurezza per i domini.
Il Callback Widget funziona in modo molto diverso dai widget descritti in questa pagina — invece di avviare una chiamata vocale nel browser, raccoglie il numero di telefono del visitatore e fa sì che il tuo agente lo richiami. Consulta la pagina dedicata Callback Widget.
Tipi di widget
Hanc.AI offre quattro tipi di widget in-browser, oltre a un Callback Widget separato per le richiamate telefoniche:
| Widget | Nome tag | Descrizione | Ideale per |
|---|---|---|---|
| Floating Widget | hanc-ai-floating-call | Pulsante a sfera che fluttua sopra la pagina | Call-to-action sempre visibile |
| Pill Widget | hanc-ai-pill-call | Pulsante compatto a forma di pillola, inserito inline nei contenuti | Ingombro minimo all'interno di un layout esistente |
| Pill Floating Widget | hanc-ai-pill-float-call | Stessa forma compatta del Pill, ma fluttua con la pagina come il Floating | Quando vuoi un'estetica a pillola che segua il visitatore durante lo scroll |
| Inline Widget | hanc-ai-inline-call | Pulsante di chiamata a dimensione piena incorporato nei contenuti della pagina | Sezioni dedicate "Parla con noi" |
| Callback Widget | hanc-ai-callback | Modulo numero di telefono; l'agente richiama il visitatore | Pagine di lead-gen, landing page ad alta intenzione — vedi Callback Widget |
Attributi comuni
Tutti i tipi di widget supportano questi attributi principali:
| Attributo | Obbligatorio | Descrizione | Predefinito |
|---|---|---|---|
agent-id | Sì | Identificativo univoco del tuo agente | — |
voice-service-url | No | Sovrascrivi l'URL del servizio vocale | Rilevato automaticamente |
api-base-url | No | Sovrascrivi l'URL base dell'API | Rilevato automaticamente |
Attributi di visualizzazione
| Attributo | Descrizione | Valori | Predefinito |
|---|---|---|---|
position | Posizione del widget sulla pagina | bottom-right, bottom-left, top-right, top-left, static | bottom-right |
size | Dimensione del widget in pixel | Numero | 120 |
theme | Nome del tema colore | Vedi Temi colore | default |
Attributi del testo dei pulsanti
| Attributo | Descrizione | Predefinito |
|---|---|---|
button-start-text | Testo mostrato sul pulsante a riposo | "Call" |
button-connecting-text | Testo mostrato durante la connessione | "Connecting..." |
button-end-text | Testo mostrato durante una chiamata attiva | — |
Attributi dei termini
| Attributo | Descrizione | Predefinito |
|---|---|---|
terms-enabled | Abilita la finestra di consenso prima della chiamata | false |
terms-content | Testo di consenso formattato in Markdown | "" |
terms-url | Link alla tua pagina Termini e Condizioni | "https://hanc.ai/terms" |
privacy-url | Link alla tua pagina Informativa sulla privacy | "https://hanc.ai/privacy" |
Gli attributi dei termini impostati sull'elemento HTML vengono sovrascritti dalle impostazioni widget dell'agente recuperate dall'API, a meno che skip-fetch non sia impostato su true.
Attributi dei suoni
| Attributo | Descrizione | Predefinito |
|---|---|---|
sound-enabled | Abilita i suoni di inizio/fine chiamata | true |
sound-volume | Volume degli effetti sonori | 0.25 |
sound-preset | Identificativo del preset sonoro | "1" |
Temi colore
Personalizza l'aspetto del widget con 11 temi colore integrati:
| Tema | Valore |
|---|---|
| Default | default |
| Purple | purple |
| Blue | blue |
| Cyan | cyan |
| Emerald | emerald |
| Amber | amber |
| Tangerine | tangerine |
| Rose | rose |
| Ember | ember |
| Black | black |
| White | white |
Ogni tema ha varianti scure e chiare. Imposta il tema tramite l'attributo theme nel codice di incorporamento, oppure configuralo nelle impostazioni widget dell'agente.
Esempi di incorporamento
Floating Widget
<hanc-ai-floating-call agent-id="YOUR_AGENT_ID"></hanc-ai-floating-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
Floating Widget con tema e posizione
<hanc-ai-floating-call
agent-id="YOUR_AGENT_ID"
theme="emerald"
position="bottom-left"
size="140"
></hanc-ai-floating-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
Pill Widget
<hanc-ai-pill-call agent-id="YOUR_AGENT_ID"></hanc-ai-pill-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
Inline Widget
<hanc-ai-inline-call agent-id="YOUR_AGENT_ID"></hanc-ai-inline-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
L'URL dello script qui sopra carica sempre l'ultima versione rilasciata del widget — il tuo sito riceve automaticamente i miglioramenti. Se hai bisogno di bloccare una versione stabile nota, fissala esplicitamente con https://unpkg.com/hanc-webrtc-widgets@1.4.0 (sostituisci con la versione desiderata). Il tag @latest è quello predefinito quando non viene specificata alcuna versione.
Eventi del widget
I widget emettono eventi che puoi ascoltare in JavaScript:
| Evento | Descrizione |
|---|---|
status-changed | Emesso quando lo stato della chiamata cambia |
connecting | La chiamata si sta stabilendo |
connected | La chiamata è attiva |
idle | Nessuna chiamata attiva |
error | Si è verificato un errore |
audio-track | Ricevuta traccia audio remota (per visualizzazione) |
local-audio-track | Traccia audio locale del microfono (per visualizzazione) |
microphone-enabled | Il microfono è stato abilitato |
microphone-disabled | Il microfono è stato disabilitato |
call-start | Emesso quando una chiamata inizia con successo |
call-end | Emesso quando la chiamata termina |
Esempio: ascolto degli eventi
const widget = document.querySelector('hanc-ai-floating-call');
widget.addEventListener('call-start', () => {
console.log('Call started');
});
widget.addEventListener('call-end', () => {
console.log('Call ended');
});
Requisiti tecnici
I widget richiedono che il browser del visitatore supporti:
- WebGL 2.0 — per il rendering
- Web Audio API — per l'elaborazione audio
- WebRTC — per la comunicazione vocale in tempo reale
Tutti i browser moderni (Chrome, Firefox, Safari, Edge) supportano queste tecnologie.
Restrizioni di dominio
Controlla quali siti web possono incorporare il widget del tuo agente.
Domini sempre consentiti
I seguenti domini sono sempre consentiti indipendentemente dalla configurazione:
hanc.ai(e sottodomini)hanc.me(e sottodomini)localhost
Consenti tutti i domini
Per impostazione predefinita, il tuo widget può essere incorporato su qualsiasi sito. Attiva "Allow all domains" nelle impostazioni widget per limitare questa possibilità.
Limita a domini specifici
Quando è limitato, aggiungi ogni dominio che deve essere consentito:
- Inserisci i nomi di dominio senza
https://(es.,example.com) - I sottodomini richiedono voci separate (es.,
www.example.com,shop.example.com) - Le porte possono essere specificate (es.,
localhost:3000) - Possono essere inseriti in whitelist massimo 50 domini
Per gli agenti in produzione, limita i widget ai tuoi domini per evitare incorporamenti non autorizzati.
Termini e Condizioni
Abilita una finestra di consenso prima che i chiamanti possano iniziare una conversazione.
Configurazione
| Impostazione | Descrizione |
|---|---|
| Enable Terms | Attiva/disattiva la finestra dei termini |
| Terms Content | Testo di consenso formattato in Markdown mostrato agli utenti (max 5.000 caratteri) |
| Terms URL | Link alla tua pagina completa Termini e Condizioni |
| Privacy URL | Link alla tua pagina Informativa sulla privacy |
Quando è abilitato:
- Gli utenti vedono una finestra di consenso prima di iniziare una chiamata
- Devono fare clic su "Agree" per procedere
- Il consenso viene memorizzato localmente nel browser
- Il pulsante Reset Consent cancella il consenso memorizzato per i test
Formattazione del contenuto
Il contenuto dei termini supporta la formattazione Markdown:
- Usa
####per i titoli - Usa
**grassetto**per enfatizzare - Usa interruzioni di riga per la leggibilità
Correlati
- Callback Widget — Richiamate telefoniche per visitatori che preferiscono non parlare nel browser
- Panoramica degli agenti vocali IA
- Impostazioni — Impostazioni dell'agente, inclusa la configurazione del widget
- Integrazioni — Chiavi API e configurazione dei numeri di telefono