De widget insluiten
Toegestane herkomstlanden
Het widget-script is met opzet openbaar — iedereen kan
/widget/widget.js
ophalen. Daardoor vormen de toegestane bronnen
de vertrouwensgrens die voorkomt dat een derde partij jouw snippet
op zijn eigen site insluit en jouw quota opgebruikt.
De afspraak
Elke POST /v1/widget/init leest de
Origin-header van het verzoek (of Referer als back-up) en
vergelijkt die met de allowed_origins-lijst van de agent. De
regels zijn:
- Lege lijst → 403. Overal weigeren. Nieuwe agents beginnen leeg totdat je minstens één herkomst toevoegt.
"*"met jokertekens → toestaan. Opt-in-achterdeurtje voor interne tools en demo’s. Stel dit nooit in als standaard.- Anders → genormaliseerde
scheme://host-overeenkomst, soepel ingesteld zodat je het domein maar één keer hoeft in te voeren:- Een naakt domein zonder schema (
stappsokken.nl) wordt standaard omgezet naarhttps. wwwen niet-wwwzijn hetzelfde — het vermelden vanexample.com,www.example.comofhttps://example.comkomt overeen met zowelhttps://example.comalshttps://www.example.com.- Alle andere subdomeinen blijven apart.
https://example.comstaathttps://app.example.comnog steeds niet toe —wwwis het enige subdomein dat als dezelfde site wordt behandeld.
- Een naakt domein zonder schema (
Bij elke bevoegde aanroep wordt de Origin opnieuw gecontroleerd
Het init-eindpunt is waar de JWT wordt aangemaakt — maar de JWT is
een bearer-token, en bearer-tokens kunnen worden gestolen (gelekte
logbestanden, browser-dev-tools, XSS op een slachtoffersite, MITM op
cleartext). Om te voorkomen dat een gestolen JWT wordt hergebruikt vanuit
attacker.example
, loopt elk bevoegd widget-eindpunt
via de VerifyWidgetOrigin
-middleware,
die bij elke aanroep de Origin van het verzoek opnieuw valideert tegen de aan de JWT gekoppelde
allowed_origins
van de agent:
POST /v1/widget/messagesPOST /v1/widget/messages/stream(SSE)POST /v1/widget/leadsPOST /v1/widget/request-humanPOST /v1/widget/eventsPOST /v1/widget/typingPOST /v1/widget/satisfactionPOST /v1/widget/coupon/applyPOST /v1/widget/conversation/clearGET /v1/widget/conversation/messagesDELETE /v1/widget/me
Het beleid is hetzelfde als bij /v1/widget/init — lege
lijst = weigeren, "*" = toestaan (inclusief no-Origin),
specifieke vermeldingen = exacte genormaliseerde overeenkomst — dus een verzoek dat
init zou hebben goedgekeurd, kan nooit een 403-fout krijgen van de post-init
middleware, en een verzoek dat init zou hebben geweigerd, kan er ook nooit
langs glippen.
Strikte subdomeinvergelijking
Dit is de regel die mensen vaak verrast, dus verdient deze een eigen uitleg:
https://thecodestudio.com opneemt in
allowed_origins, is https://pitchbar.thecodestudio.com niet toegestaan.
Subdomeinen staan
los van elkaar — vermeld ze allemaal expliciet. Dit voorkomt dat een aanvaller
die een subdomein beheert (via DNS of shared hosting) het vertrouwen
van het bovenliggende domein erft. De enige uitzondering is www:
www.example.com en example.com worden behandeld als
dezelfde site, dus je vermeldt ze nooit allebei.
Als je echt extra subdomeinen wilt, vermeld ze dan afzonderlijk
(www
is al opgenomen):
https://example.com
https://app.example.com
https://docs.example.com
Oorsprongen toevoegen
Op het tabblad Website van de AI-medewerker (/app/agents/{id}/website),
heeft het gedeelte Websites waar het kan verschijnen een
tekstveld — één oorsprong per regel. Wijzigingen aan websites worden
onmiddellijk door de agent opgeslagen; nieuwe init-verzoeken gebruiken de nieuwe lijst binnen
enkele seconden.
Je kunt alleen het domein invoeren — het schema wordt standaard ingesteld op https
en www wordt automatisch herkend. Hoe een paar invoergegevens worden geïnterpreteerd:
| Je voert in | Komt overeen met |
|---|---|
example.com | https://example.com en https://www.example.com |
www.example.com | net als hierboven (www en niet-www) |
http://localhost:3000 | http://localhost:3000 — behoud het schema + poort voor lokale http-ontwikkeling |
*.example.com | niets — jokertekens worden niet ondersteund, behalve als een op zichzelf staande "*" |
Lokaal testen
Voeg tijdens de ontwikkeling http://localhost:3000 (of welke
poort je ook gebruikt) toe aan de toegestane bronnen van de agent. Gebruik hiervoor geen
"*" — als je dit per ongeluk in de productieomgeving laat staan,
blijft de agent kwetsbaar.
Wat gebeurt er bij afwijzing
Een verzoek van een niet-toegestane bron krijgt een JSON 403:
{
"error": {
"code": "origin_forbidden",
"message": "Origin is not allowed for this agent."
}
}
De loader van de widget gaat hier soepel mee om — de launcher verdwijnt stilletjes in plaats van een consolefout te geven, zodat bezoekers nooit een kapotte UI te zien krijgen. De 403 wordt aan de platformkant gelogd, zodat je kunt letten op misbruikpatronen.
Hoe zit het met bronnen op dezelfde host?
De controle kijkt naar schema + host, dus http
versus https
zijn verschillend (zoals het hoort). En verschillende poorten zijn verschillende
herkomstbronnen (http://localhost:3000
≠
http://localhost:3001
).
Jokertekens: wanneer wel, wanneer niet
"*"
is bedoeld voor gevallen waarin je de
herkomst echt niet van tevoren weet:
- Interne demo-agents die op de preview-site van elke potentiële klant worden ingebed.
- Sandbox-/preview-omgevingen waar de herkomst dagelijks verandert.
Voor productie-agents: nooit. Het nadeel van het vergeten van "*" is
dat iedereen die je data-agent-id vindt, je
quotum kan opgebruiken. Het nadeel van een expliciete lijst is één minuut per nieuwe herkomst.
Pagina’s waar het verschijnt — de bijbehorende
Websites waar het kan verschijnen
(de toegestane oorsprongen)
trekken de vertrouwensgrens op domeinniveau (alleen
https://shop.example.com
kan de widget laden).
Pagina’s waar het voorkomt
, het volgende gedeelte van het tabblad
Website
, is het zustergedeelte, één niveau lager: op welke paden binnen een toegestane oorsprong
de agent het weergeeft. Eén lijst met patronen, op drie manieren te interpreteren:
| Modus | De agent verschijnt op | Typisch gebruik |
|---|---|---|
| Overal | op elke pagina van de toegestane domeinen; de lijst wordt genegeerd | de standaardinstelling |
| Overal behalve deze paden | elke pagina behalve diegene die aan een patroon voldoen | houd de bot weg van je eigen /admin-, /checkout- of /account-stromen |
| Alleen op deze paden | de pagina's die aan een patroon voldoen, en nergens anders | twee gespecialiseerde agents op één site — de ene alleen op /waterhardheid/*, de andere overal behalve daar |
Elke vermelding is een glob — * is de enige joker, en
komt gulzig overeen over schuine strepen heen. Vergelijking is hoofdletterongevoelig
ten opzichte van window.location.pathname:
| Patroon | Komt overeen | Komt niet overeen |
|---|---|---|
/admin |
/admin, /Admin |
/admin/users (gebruik daarvoor /admin/*) |
/waterhardheid/* |
/waterhardheid, /waterhardheid/, /waterhardheid/gulpen-wittem/ |
/feiten-en-fabels/waterhardheid |
/checkout |
/checkout |
/checkout/confirm |
/account/* |
/account/profile, /account/security |
/Help/account |
Hoe het werkt tijdens het uitvoeren
De path_mode en restricted_paths van de agent
maken gebruik van hetzelfde POST /v1/widget/init-antwoord als de rest
van de configuratie, en de cachekopie waaruit de widget bij een
volgend bezoek tekent, bevat beide, dus een pagina die niet beschikbaar is, laat de
balk nooit een halve seconde flitsen. Als de pagina offline is, wordt de balk nooit geladen,
start de trigger-engine nooit op en vinden er geen verdere HTTP-verzoeken plaats voor die
pagina. De widget roept nu zelfs geen
/v1/widget/init aan als de regels in de cache (die bij elke
pagina waarvoor de agent is ingesteld worden vernieuwd en 7 dagen worden bewaard) al aangeven dat de pagina offline is.
Zonder een kopie in de cache roept hij init aan, en de server past eerst dezelfde
regels toe: op een pagina die offline is, antwoordt hij alleen met de regels —
er wordt geen bezoeker, conversatie, paginaweergave of automatische indexering van die pagina
aangemaakt.
Alleen op deze paden met een lege lijst verschijnt de agent overal in plaats van nergens: het kiezen van de modus voordat je een patroon invoert, mag er niet voor zorgen dat een agent van de hele site verdwijnt.
Twee agents op één website
Geef de sectie-agent ‘Alleen op deze paden met
/waterhardheid/*’, en de algemene agent ‘Overal
behalve op deze paden met hetzelfde patroon’. Beide scripts kunnen dan
op elke pagina worden geïnstalleerd — via het thema of een tagmanager
met een Alle pagina’s-trigger — en elke agent beslist
zelf of deze pagina van hem is. Op een pagina waar de agent van het eerste
script niet actief is, draagt hij de pagina over aan de andere, zodat een bezoeker
één widget ziet en nooit twee, en nooit geen. Eén pagina, één
/init per tag, net als voorheen. Daarvoor is geen padopzoeking in de tagmanager
nodig; zie Install
snippet voor het tagmanager-recept als je liever via die route werkt.
Ontwerpen
Op het tabblad Website heeft de sectie Pagina’s waar het verschijnt (voorheen Waar moet deze agent verschijnen? ) de drie opties en, voor de tweede en derde, een tekstveld met één pad per regel. Maximaal 32 vermeldingen, elk met maximaal 200 tekens. Agents die al beperkte paden hadden voordat deze instelling bestond, zijn automatisch verplaatst naar Overal behalve deze paden , dus voor hen is er niets veranderd.
Waarom dit een aparte instelling is, los van authenticatie
Het platform onderdrukt ook automatisch de marketingdemowidget op
geverifieerde beheerder-/klantroutes via een server-side controle in de
Inertia-rootlay-out — dat is een harde garantie die niet afhankelijk is
van de instellingen van de agent. restricted_paths is de extensie aan de koperskant
: zelfs op een volledig niet-geauthenticeerde marketingsite
zou /checkout niet vol moeten staan met een verkoopchatbot.
Hoe auto-index oorsprongen gebruikt
Auto-index
gebruikt dezelfde
toegestane lijst, maar met een twist als "*"
is ingesteld: de URL van de pagina
die automatisch wordt geïndexeerd, moet overeenkomen met de daadwerkelijke Origin
-header van de bezoeker. Dat voorkomt dat een kwaadaardige pagina willekeurige
domeinen van derden automatisch indexeert via de joker.