B Blengi docs

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:

  1. Lege lijst → 403. Overal weigeren. Nieuwe agents beginnen leeg totdat je minstens één herkomst toevoegt.
  2. "*" met jokertekens → toestaan. Opt-in-achterdeurtje voor interne tools en demo’s. Stel dit nooit in als standaard.
  3. 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 naar https.
    • www en niet-www zijn hetzelfde — het vermelden van example.com, www.example.com of https://example.com komt overeen met zowel https://example.com als https://www.example.com.
    • Alle andere subdomeinen blijven apart. https://example.com staat https://app.example.com nog steeds niet toe — www is het enige subdomein dat als dezelfde site wordt behandeld.

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/messages
  • POST /v1/widget/messages/stream (SSE)
  • POST /v1/widget/leads
  • POST /v1/widget/request-human
  • POST /v1/widget/events
  • POST /v1/widget/typing
  • POST /v1/widget/satisfaction
  • POST /v1/widget/coupon/apply
  • POST /v1/widget/conversation/clear
  • GET /v1/widget/conversation/messages
  • DELETE /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:

Als je 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 inKomt overeen met
example.comhttps://example.com en https://www.example.com
www.example.comnet als hierboven (www en niet-www)
http://localhost:3000http://localhost:3000 — behoud het schema + poort voor lokale http-ontwikkeling
*.example.comniets — 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:

ModusDe agent verschijnt opTypisch 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:

PatroonKomt overeenKomt 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.