De widget insluiten
Versiebeheer en cache-verversing
YOUR-AGENT-ID.
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:
public/widget/widget.jsleest.- Een SHA-256-prefix van 12 tekens berekent.
- De bundel naar
public/widget/widget.<hash>.jskopieert. public/widget/manifest.jsonschrijft.
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.