Naar de inhoud

Werking van de widget

Wat de widget in de browser doet nadat je de embedcode geplakt hebt. Gebruik deze pagina om de widget vanuit je eigen code aan te sturen, een laadprobleem te onderzoeken, of vragen in een securityreview te beantwoorden.

Het configuratieobject

De code zet window.MIKADO_CHATBOT_CONFIG voordat de loader draait.

  • domain (verplicht) — de Mikabot-app-URL die de widget aanroept. Staat al ingevuld in je code.
  • store_id (verplicht) — je chatbotsleutel, met voorvoegsel st_. Gaat mee met elk verzoek.
  • language (optioneel) — forceert een taal. Laat weg om automatisch te detecteren.
  • container (optioneel) — een CSS-selector. Toont de chat in dat element in plaats van als zwevende bubbel.
  • debugLogging (optioneel) — op true schrijft de widget zijn interne stappen naar de console. Het houdt de widget ook zichtbaar wanneer de bot zichzelf als offline meldt, dus zet het uit voor je live gaat.

Laadvolgorde

  1. Je pagina laadt en definieert MIKADO_CHATBOT_CONFIG.
  2. mikabot-init.js wacht op het load-event van het venster en injecteert dan het hoofdscript van de widget. Er wordt niets opgehaald voordat je eigen pagina klaar is met laden.
  3. De loader controleert eerst of mikabot-script.js al op de pagina staat en doet niets als dat zo is, dus een twee keer geplakte code laadt de widget niet dubbel.
  4. Het hoofdscript voegt de widgetstylesheet toe vanaf je Mikabot-domein, en een icoonstylesheet vanaf cdnjs.cloudflare.com.
  5. Winkelgegevens en je geschreven antwoorden worden opgehaald voor de gedetecteerde taal. Staat de chatbot inactief, is de maandelijkse berichtenlimiet bereikt, of is Mikabot tijdelijk onbeschikbaar, dan wordt er helemaal niets weergegeven.
  6. De bubbel, of je container, verschijnt.

Het hoofdscript wordt opgevraagd met een versieparameter, dus een nieuwe Mikabot-release maakt de gecachete kopie ongeldig. De loader zelf wordt zonder parameter geserveerd.

Taaldetectie

De eerste treffer wint:

  1. language in MIKADO_CHATBOT_CONFIG
  2. Het lang-attribuut op <html>
  3. De browsertaal, uit navigator.language
  4. Engels

Ondersteunde waarden zijn en, nl, fr, de, es en it. Al het andere — ook een regionale code zoals en-US of nl-BE — wordt genegeerd, en de detectie gaat naar de volgende stap.

Wat de widget beschikbaar maakt

Zodra de widget geïnitialiseerd is, zijn deze globals beschikbaar:

  • window.chatbot — de widgetinstantie, handig in de console om de status te bekijken
  • window.trackProductClick(externalId, clickType, event) — registreert een klik op een product dat je zelf rendert
  • window.askAboutProduct(productId, productTitle, externalId) — opent de chat met een vraag over een specifiek product

Roep ze aan vanuit een gebruikersactie, zoals een knop in je eigen productkaart, niet vanuit een script dat draait voordat de widget bestaat.

Wat er in de browser bewaard wordt

De widget gebruikt localStorage en zet geen cookies:

  • mikabot_session_id — de sessie die de berichten van een bezoeker tot één gesprek groepeert
  • mikado_chat_messages — het zichtbare gesprek, zodat het een herlaadbeurt overleeft. Wordt na 24 uur gewist.
  • chatbot-language — de taal die de bezoeker het laatst gebruikte
  • mikabot_popup_tracking — hoe vaak de attentiepopup getoond is, wat hem op twee keer per 24 uur houdt
  • chatbot-debug-logging — of debuguitvoer aan staat voor deze browser

Een nieuw gesprek starten wist de sessie-id en de opgeslagen berichten. De taal, de popupteller en de debugvlag blijven bestaan.

Hostingvereisten

  • De widget moet je Mikabot-domain kunnen bereiken voor scripts, stijlen en API-aanroepen.
  • Met een Content-Security-Policy sta je die host toe in script-src, style-src en connect-src, en cdnjs.cloudflare.com in style-src en font-src.
  • De hostnaam van de pagina moet exact overeenkomen met het veld Domain van de chatbot. Er wordt alleen op hostnaam en poort vergeleken, dus www.jouwshop.be en jouwshop.be zijn verschillende waarden. Een verschil is de meest voorkomende oorzaak van een widget die wel laadt maar nooit antwoordt.

Zie ook