Widget

Nascondere il launcher

Se vuoi controllare quando e come si apre la chat (es. solo da bottoni personalizzati), puoi nascondere l'icona flottante predefinita.

Aggiungi l'oggetto IKIbrainConfig prima dello script di embed:

<script>
window.IKIbrainConfig = { hideLauncher: true };
</script>
<!-- codice embed qui -->

Quando il launcher è nascosto, la chat può essere aperta solo programmaticamente tramite l'API JavaScript descritta di seguito.

Siti multilingua

Se il bot è configurato per più lingue, il widget mostra normalmente un pannello di selezione lingua quando l'utente lo apre. Se su un sito multilingua sai già in che lingua sta navigando l'utente — ad esempio perché sta navigando sulla versione italiana del sito - puoi saltare quel pannello passando lang in IKIbrainConfig:

<script>
window.IKIbrainConfig = { lang: 'it' };
</script>
<!-- codice embed qui -->

Il widget si aprirà direttamente nella lingua specificata, senza mostrare il pannello di selezione.

Come impostare la lingua dinamicamente

Su un sito dove la lingua viene da una variabile PHP, un attributo data- o una costante JS, è sufficiente passarla inline:

<!-- Esempio PHP -->
<script>
window.IKIbrainConfig = { lang: '<?= htmlspecialchars($currentLang) ?>' };
</script>

<!-- Esempio JavaScript -->
<script>
window.IKIbrainConfig = { lang: document.documentElement.lang || 'it' };
</script>

Codici lingua supportati

Apri / Chiudi

Puoi aprire o chiudere la finestra chat programmaticamente:

// Aprire la finestra chat
IKIbrainWidget.openChat();

// Chiudere la finestra chat
IKIbrainWidget.closeChat();

Esempio con bottone personalizzato:

<button onclick="IKIbrainWidget.openChat()">
  Chatta con noi
</button>

Apertura automatica

Di default il widget si carica chiuso e l'utente clicca sul launcher per aprire la chat. Con autoOpen puoi invece mostrare la chat già aperta al caricamento della pagina. Come le altre opzioni, va definita in IKIbrainConfig prima dello script di embed:

<script>
window.IKIbrainConfig = { autoOpen: true };
</script>
<!-- codice embed qui -->

Su mobile la chat aperta occupa l'intero schermo, il che può risultare invasivo al primo caricamento. Se preferisci l'apertura automatica solo su desktop, usa il valore 'desktop':

<script>
window.IKIbrainConfig = { autoOpen: 'desktop' };
</script>
<!-- codice embed qui -->

Valori supportati

Posizione della chat

Di default la finestra chat si apre in basso nella pagina (a destra, a sinistra o — con il launcher a barra — al centro, secondo la configurazione del bot). Se hai nascosto il launcher per usare una tua icona in un altro punto della pagina, con chatPosition puoi far aprire il pannello accanto ad essa:

<script>
window.IKIbrainConfig = {
  hideLauncher: true,
  chatPosition: { bottom: '96px', left: '24px' }
};
</script>
<!-- codice embed qui -->

Proprietà supportate

I valori accettano le unità CSS più comuni (px, %, rem, em, vh, vw) oppure numeri, interpretati come pixel. I valori non validi vengono ignorati. Se specifichi un solo asse, l'altro mantiene il default.

L'animazione di apertura si adatta da sola alla posizione scelta: con ancoraggio in basso il pannello sale dal basso, con top scende dall'alto, e l'origine dell'effetto segue il lato (sinistro o destro) a cui è agganciato.

Contesto di pagina

Il contesto di pagina serve a far capire al bot in che pagina si trova l'utente e di cosa parla quella pagina. È un contesto globale: una volta attivato viene ereditato automaticamente da tutti i messaggi della sessione, quindi non va ripetuto su ogni bottone.

Attivazione

Il contesto di pagina non è attivo di default: questo significa che il bot non sa su quale pagina si trova l'utente. Per attivarlo devi abilitarlo esplicitamente, definendo window.IKIbrainConfig con la chiave pageContext prima dello script di embed:

<script>
  window.IKIbrainConfig = { pageContext: {} };   // ← questa è la riga che attiva il contesto
</script>
<!-- codice embed qui -->

Valori supportati

Puoi anche valorizzare manualmente i campi di pageContext:

<script>
  window.IKIbrainConfig = {
    pageContext: {
      url: 'https://www.esempio.it/sedie/xr-500',
      title: 'Sedia Ergonomica XR-500',
      description: 'Sedia Ergonomica XR-500 - Sedute per Ufficio, schienale regolabile, garanzia 5 anni'
    }
  };
</script>
<!-- codice embed qui -->

Nella maggior parte dei casi è sufficiente description: url e title vengono rilevati automaticamente dalla pagina corrente.

Questi dati aiutano il bot a rispondere meglio in due modi:

1. aiutano a interpretare le domande contestuali dell'utente — ad esempio "di che materiale è fatto?" — che senza contesto non avrebbero un oggetto chiaro;
2. permettono al bot di sapere quale pagina sta guardando l'utente e, quando serve, di adattare la risposta di conseguenza.

Aggiornare il contesto nei siti SPA

SPA sta per Single Page Application: un tipo di sito (tipicamente costruito con React, Vue, Angular, Next.js, Svelte, ecc.) in cui la navigazione tra le pagine avviene senza ricaricare la finestra del browser. L'URL cambia e il contenuto viene sostituito via JavaScript, ma lo script del widget resta caricato dall'inizio della visita.

Questo significa che il pageContext definito in IKIbrainConfig viene letto una sola volta, all'apertura del sito, e non si aggiorna automaticamente al cambio di route. Per aggiornare il contesto quando l'utente naviga, chiama IKIbrainWidget.setPageContext():

// Al cambio di route
router.afterEach(function (to) {
  IKIbrainWidget.setPageContext({
    description: 'Pagina ' + to.meta.productName
  });
});

// Per resettare
IKIbrainWidget.setPageContext(null);

Il nuovo contesto si applica a tutti i messaggi successivi. url e title vengono auto-popolati dalla pagina corrente se non li passi esplicitamente.

function ikiReady(fn) {
  if (window.IKIbrainWidget) { fn(); }
  else { setTimeout(function () { ikiReady(fn); }, 100); }
}

router.afterEach(function (to) {
  ikiReady(function () {
    IKIbrainWidget.setPageContext({ description: 'Pagina ' + to.meta.productName });
  });
});

Apri con domanda

La funzionalità più potente: apre la chat con una domanda predefinita, sfruttando il contesto di pagina. Il bot risponde come se l'utente avesse scritto la domanda, con piena consapevolezza della pagina che sta visitando.

IKIbrainWidget.openWithQuestion(question, context)

Esempio:

<button onclick="IKIbrainWidget.openWithQuestion(
  'Di che materiale è fatto?',
  'Sedia Ergonomica XR-500 - Sedute per Ufficio'
)">Di che materiale è fatto?</button>

Più bottoni, stesso contesto

Se nella stessa pagina hai più bottoni che condividono lo stesso contesto (es. più domande sullo stesso prodotto), invece di ripeterlo in ogni chiamata puoi dichiararlo una volta sola nel contesto di pagina globale: tutti i bottoni lo ereditano e chiami openWithQuestion() con la sola domanda.

<script>
window.IKIbrainConfig = {
  pageContext: {
    description: 'Sedia Ergonomica XR-500 - Arredamento Ufficio'
  }
};
</script>
<!-- codice embed qui -->

<button onclick="IKIbrainWidget.openWithQuestion('Di che materiale è fatto?')">Materiali</button>
<button onclick="IKIbrainWidget.openWithQuestion('Quali dimensioni esistono?')">Dimensioni</button>
<button onclick="IKIbrainWidget.openWithQuestion('Qual è la garanzia?')">Garanzia</button>

Regola di precedenza

Il 2° argomento di openWithQuestion(question, context) ha sempre la priorità sul contesto globale. Se un bottone passa un contesto esplicito non vuoto, quello vince; altrimenti fa da fallback il pageContext globale.

<!-- Globale: "Sedia Ergonomica XR-500" -->

<!-- Usa il globale -->
<button onclick="IKIbrainWidget.openWithQuestion('Quanto pesa?')">Peso</button>

<!-- Sovrascrive con contesto specifico -->
<button onclick="IKIbrainWidget.openWithQuestion(
  'Qual è la politica di reso?',
  'Politica di reso generale del negozio'
)">Reso</button>

Se invece non è impostato né un contesto globale né il parametro context, la domanda viene inviata senza alcun contesto di pagina: il bot riceve solo il testo della domanda e non sa su quale pagina si trovi l'utente. Le domande contestuali (es. "di che materiale è fatto?") rischiano quindi di risultare ambigue, perché manca il riferimento al prodotto o al contenuto della pagina.

Esempio: Pagina prodotto e-commerce

In una pagina prodotto, dichiara il contesto una volta e aggiungi bottoni contestuali che pongono domande comuni su quel prodotto:

<script>
window.IKIbrainConfig = {
  hideLauncher: true,
  pageContext: {
    description: 'Sedia Ergonomica XR-500 - Arredamento Ufficio'
  }
};
</script>

<!-- Prodotto: Sedia Ergonomica XR-500 -->
<div class="product-questions">
  <button onclick="IKIbrainWidget.openWithQuestion('Di che materiale è fatto?')">Materiali</button>
  <button onclick="IKIbrainWidget.openWithQuestion('Esiste in altre dimensioni?')">Dimensioni</button>
  <button onclick="IKIbrainWidget.openWithQuestion('Qual è la garanzia di questo prodotto?')">Garanzia</button>
</div>

Esempio: Annuncio immobiliare

<button onclick="IKIbrainWidget.openWithQuestion(
  'Quanto costa l\'affitto mensile?',
  'Trilocale, Via Roma 15, Milano - Rif. APT-2024-089'
)">Chiedi sull'affitto</button>

<button onclick="IKIbrainWidget.openWithQuestion(
  'C\'è un garage disponibile?',
  'Trilocale, Via Roma 15, Milano - Rif. APT-2024-089'
)">Chiedi sul parcheggio</button>

Esempio: Pagina servizi

<button onclick="IKIbrainWidget.openWithQuestion(
  'Quanto costa questo servizio?',
  'Audit SEO & Ottimizzazione - Servizi di Marketing Digitale'
)">Chiedi sul prezzo</button>

<button onclick="IKIbrainWidget.openWithQuestion(
  'Quanto tempo ci vuole?',
  'Audit SEO & Ottimizzazione - Servizi di Marketing Digitale'
)">Tempistiche</button>

Riferimento API

Oggetto di configurazione

window.IKIbrainConfig = {
  hideLauncher: true,    // Nasconde l'icona chat flottante
  autoOpen: true,        // Apre la chat al caricamento (true oppure 'desktop')
  chatPosition: {        // Posizione del pannello chat (default: angolo in basso)
    bottom: '96px', left: '24px'
  },
  lang: 'it',           // Salta la selezione lingua (bot multilingua)
  pageContext: {         // Contesto globale di pagina (ereditato da tutti i messaggi)
    description: 'Sedia Ergonomica XR-500'
  },
  serviceContext: {...}  // Contesto servizio esterno (avanzato)
};

L'oggetto IKIbrainConfig deve essere definito prima che lo script di embed venga caricato.

serviceContext (avanzato)

Se il tuo sito ha una propria applicazione — account utente, carrelli, ordini — l'assistente può ricevere da essa i dati di sessione, così che le sue azioni si adattino all'utente o alla sessione corrente (ad esempio: abilitare determinate azioni solo per gli utenti loggati, oppure funzionalità legate al carrello).

È una funzionalità a livello di integrazione: i dati effettivamente passati e il modo in cui vengono usati si configurano insieme a noi e dipendono dalla tua installazione. Serve ad alimentare le azioni dell'assistente, non per l'autenticazione dell'utente.

Dettagli comportamento

Gestione sessione

• Ogni chiamata a openWithQuestion() avvia una nuova sessione pulita
• Se la chat è già aperta, la sessione corrente viene resettata prima di iniziare quella nuova
• Il flusso di onboarding (privacy notice, selezione lingua, OTP, form pre-chat) viene eseguito normalmente prima dell'invio della domanda

Bottoni multipli

• Se l'utente clicca più bottoni rapidamente, solo l'ultimo vince
• Ogni bottone può usare domande diverse ma condividere lo stesso contesto, o viceversa

Suggerimenti per il contesto

• Sii descrittivo — includi il nome del prodotto/servizio, la categoria e un eventuale identificativo unico
• Sii conciso — punta a 10-50 parole. Non serve una descrizione completa della pagina, basta quanto serve al bot per capire cosa sta guardando l'utente
• Usa nomi coerenti — utilizza la stessa terminologia presente nella knowledge base per ottenere risultati migliori

Compatibilità

• Funziona su tutti i browser moderni (Chrome, Firefox, Safari, Edge)
• Il comportamento standard del widget è completamente preservato quando hideLauncher non è impostato
• Tutte le funzionalità esistenti (multilingua, form pre-chat, OTP per bot privati) funzionano normalmente