B Blengi docs

De widget insluiten

Versiebeheer en cache-verversing

De widgetbundel wordt geleverd via /w/widget.js en wordt bij elke release opnieuw opgebouwd. Om te voorkomen dat de cache van browsers of CDN’s op de sites van kopers verouderd raakt, publiceert elke build ook een inhoudsgehasht tweelingbestand op /widget/widget.<hash>.js plus een manifest op /w/manifest.json.

Fragmenten van vóór het neutrale pad blijven gewoon werken: /widget/widget.js reageert met een permanente omleiding (301) naar /w/widget.js , waarbij de query-string intact blijft, zodat ?v= en de tagmanager ?agent= nog steeds worden geladen. De terugkeerpagina’s van het afrekenen leiden op dezelfde manier door, en de oude /widget/manifest.json reageert nog steeds zoals altijd.

Standaard insluiting (automatische update)

Het fragment dat de beheerder ziet bij /app/agents/{id} verwijst naar de stabiele /w/widget.js met een ?v=-cachehint. De route streamt altijd de bundel die in het manifest staat vermeld, dus elke release komt op de pagina terecht zonder dat iemand iets aan de HTML hoeft te veranderen.

<script async src="https://blengi.com/w/widget.js?v=97e3674e6b4d" data-agent-id="YOUR-AGENT-ID"></script>

Manifest-eindpunt

Kopers die de huidige bundel programmatisch willen ophalen, kunnen GET /w/manifest.json aanroepen:

{
  "version": "2.0.0",
  "hash": "abc123abc123",
  "file": "widget.abc123abc123.js",
  "url": "/widget/widget.abc123abc123.js",
  "generated_at": "2026-05-16T07:11:36Z"
}

Het eindpunt stelt Cache-Control: public, max-age=60, must-revalidate in, zodat het manifest zelf nooit lang blijft staan, maar het bundelbestand kan worden geserveerd met langdurige Cache-Control -headers, omdat de URL per release verandert.

Bundelcaching & opstartsnelheid

De niet-gehasht /w/widget.js die snippets laden, wordt geleverd via Cache-Control: public, max-age=300, stale-while-revalidate=86400. Bij herhaalde paginaweergaven wordt de widget direct vanuit de browsercache gestart — geen vertragende roundtrip voordat het script draait — en de browser vernieuwt de bundel op de achtergrond na het venster van vijf minuten. Een nieuwe release bereikt dus alle bezoekers binnen maximaal vijf minuten na de implementatie.

De widget slaat ook de chrome van de agent (thema, tekst, begroeting, startvragen) op in de browser van de bezoeker na elke succesvolle opstart. Bij de volgende paginaweergave verschijnt de balk meteen met die echte, gelokaliseerde interface en wordt hij interactief zodra de nieuwe initialisatie is voltooid — de bezoeker staart nooit naar een lege hoek. Tokens en de gespreksstatus worden op deze manier nooit opgeslagen; die komen altijd uit de nieuwe initialisatie.

Vastzetten op een specifieke versie

Als je de bundel aan de kant van de koper moet vergrendelen (bijv. om een marketingcampagne te coördineren), kopieer dan het veld file uit het manifest en gebruik het letterlijk:

<script async src="https://app.example.com/widget/widget.abc123abc123.js"></script>

Elke build vervangt het vorige gehashte bestand, dus een vastgezette hash blijft slechts geldig tot de volgende release: zet hem vast voor een korte campagneperiode en ga daarna weer terug naar /w/widget.js.

Fallback

Als het manifest ontbreekt (bijvoorbeeld bij een gedeeltelijke implementatie), valt het fragment terug op /w/widget.js?v=<md5-prefix> , zodat kopers nooit een lege src krijgen. We behouden het niet-gehasht widget.js ook als het canonieke artefact.

Build-pijplijn

npm run build:widget voert de Vite-build uit en roept vervolgens bin/widget-postbuild.cjs aan, dat:

  1. public/widget/widget.js leest.
  2. Een SHA-256-prefix van 12 tekens berekent.
  3. De bundel naar public/widget/widget.<hash>.js kopieert.
  4. public/widget/manifest.json schrijft.

Zowel de artefacten als het manifest worden naar de repo gepusht — de host voert npm run build niet uit, de repo is het implementatie-artefact.