Il widget
Content Security Policy (CSP)
Le origini esatte da consentire per il widget su un sito con una Content-Security-Policy restrittiva, i nonce per i suoi stili, il blocco di una versione con Subresource Integrity e il caricamento al clic.
Se il tuo sito invia un’intestazione Content-Security-Policy, consenti le origini qui sotto. Al widget non serve altro.
Origini da consentire
| Direttiva | Origine | Serve per |
|---|---|---|
script-src | https://widget.iperchat.ai (o il tuo nonce sul tag script) | Lo script del widget |
connect-src | https://api.iperchat.ai | Impostazioni, conversazioni e risposte in streaming |
connect-src | https://identitytoolkit.googleapis.com, https://securetoken.googleapis.com | L’accesso dei visitatori. Non serve con la Modalità solo anonimo (in “Il mio Tenant”) |
style-src | Il tuo nonce, oppure 'unsafe-inline' | Il foglio di stile del widget (vedi sotto) |
img-src | Gli host degli URL del tuo logo e dell’immagine di intestazione | Come impostati in “Configurazioni Agenti” |
img-src | https://storage.googleapis.com | Le immagini della knowledge base mostrate nelle risposte |
media-src | blob:, data: | Le risposte vocali, solo se la riproduzione vocale è attiva |
Il widget non apre frame e non carica web font, quindi non servono voci frame-src o font-src. Usa Inter se la tua pagina lo fornisce, altrimenti il font di sistema.
Un esempio completo, dove {NONCE} è il valore casuale che il tuo server genera per ogni risposta:
Content-Security-Policy:
script-src 'self' https://widget.iperchat.ai 'nonce-{NONCE}';
style-src 'self' 'nonce-{NONCE}';
connect-src 'self' https://api.iperchat.ai https://identitytoolkit.googleapis.com https://securetoken.googleapis.com;
img-src 'self' https://storage.googleapis.com;
frame-src 'none'Stili: un nonce oppure 'unsafe-inline'
Il widget aggiunge il suo foglio di stile come elementi <style>: uno nella sua shadow root, uno in <head> per le proprietà CSS personalizzate e uno per il segnaposto del pulsante mentre la pagina si carica. Una style-src restrittiva li blocca, a meno che tu non:
- usi un nonce (consigliato). Metti il nonce della pagina sul tag script del widget: il widget lo copia sui suoi elementi
<style>. Quando avvii il widget da JavaScript, usa il nonce del tag script che l’ha caricato, oppure quello che passi aIperChat.init({ nonce }). - oppure consenta
'unsafe-inline'instyle-src.
<script
src="https://widget.iperchat.ai/iperchat.iife.js"
nonce="{NONCE}"
data-iperchat-auto-init
data-tenant-id="IL_TUO_TENANT_ID"
></script>Il widget imposta anche alcuni stili direttamente da JavaScript: la CSP li consente senza nonce.
Bloccare una versione con Subresource Integrity
https://widget.iperchat.ai/iperchat.iife.js serve sempre il widget più recente, quindi può cambiare a ogni rilascio di IperChat. Per caricare una build che non cambia mai, usa un URL con versione e il suo hash integrity:
<script
src="https://widget.iperchat.ai/v/1.0.0/iperchat.iife.js"
integrity="sha384-…"
crossorigin="anonymous"
data-iperchat-auto-init
data-tenant-id="IL_TUO_TENANT_ID"
></script>Un file con versione non cambia mai e resta disponibile. https://widget.iperchat.ai/v/manifest.json elenca ogni versione con il suo valore integrity. Una versione bloccata non riceve correzioni né novità: passa a una versione più recente quando sei pronto.
Caricare il widget solo al clic
Questo loader non scarica nulla da IperChat finché il visitatore non clicca il tuo pulsante. Con una script-src restrittiva, servilo come file dal tuo sito e dai al suo tag script il tuo nonce; il loader lo passa allo script del widget:
// chat-loader.js
var nonce = document.currentScript.nonce
document.getElementById('open-chat').addEventListener('click', function () {
if (window.IperChat) {
window.IperChat.open()
return
}
var script = document.createElement('script')
script.src = 'https://widget.iperchat.ai/iperchat.iife.js'
script.nonce = nonce
script.onload = function () {
window.IperChat.init({ tenant_id: 'IL_TUO_TENANT_ID', language: 'it' })
window.IperChat.open()
}
document.body.appendChild(script)
})<button id="open-chat" type="button">Scrivici</button>
<script src="/chat-loader.js" nonce="{NONCE}"></script>