Docs / Op je website

De widget op je website

Je kiest zelf hoe je de widget aanbiedt aan je bezoekers. Voor de meeste manieren gaat het om één stukje code dat je aan een pagina toevoegt; binnen een kwartier staat het live. Op deze pagina staat alles bij elkaar: hoe je Vragen.ai op je site zet, hoe je het in je huisstijl stylet en hoe je het meeneemt in je Content Security Policy.

Gebruik je WordPress of Drupal? Dan is er een eigen WordPress-plugin die je content synchroniseert én de widget als block plaatst, en een Drupal-module die het zoeken in Drupal vervangt door semantisch zoeken.

Zo bied je de widget aan

Alles begint met een deployment: een variant van de widget die je in het vragen.ai-dashboard aanmaakt. Je kunt er zoveel maken als je wilt, bijvoorbeeld één voor je website en één voor je intranet, elk met eigen voorbeeldvragen, teksten en styling. Voor elke deployment geeft het dashboard je de bijbehorende code of link.

Bij het aanmaken maak je twee keuzes: hoe het venster verschijnt, en hoe je het op je site installeert.

Hoe het venster verschijnt

Dit stel je in op de deployment zelf. Verander je het later, dan hoeft de code op je site niet mee te veranderen; binnen ongeveer vijf minuten zien je bezoekers de nieuwe instelling. Je hebt de keuze uit:

• Op je eigen pagina (inline). Het venster staat gewoon tussen je content, zoals op de homepage van vragen.ai.

• Als overlay. Het venster opent over je pagina heen, bijvoorbeeld na een klik op een knop.

• Als zijpaneel. Het venster schuift in vanaf de zijkant van het scherm.

• Als losse pagina. vragen.ai host een complete pagina met alleen de widget; daar verwijs je met een link naartoe.

• In je bestaande zoekveld. Auto-aanvullen toont suggesties terwijl iemand typt. De Search Add-on zet een AI-samenvatting boven je gewone zoekresultaten.

Hoe je het op je site zet

Een link naar een gehoste pagina. De snelste start, zonder iets te installeren. Kies bij de deployment de vorm "losse pagina"; je krijgt dan een URL die je aan een knop of link op je site koppelt:

<a href="https://jouworganisatie.vragen.ai/deployment/[deployment-naam]" target="_blank">Stel je vraag</a>

Handig als je nog geen toegang hebt tot de templates van je site, voor een demo of voor een link op je intranet.

Een embed-script. Zo zet je het venster rechtstreeks in een pagina. Je plaatst dit script en een leeg div-element op de plek waar het venster moet komen:

<script src="https://jouworganisatie.vragen.ai/embed.js?deployment=[deployment-naam]"></script>
<div id="vragenai-app"></div>

Het script laadt vanaf je eigen vragen.ai-subdomein, en de deployment-parameter bepaalt welke variant verschijnt. Of het venster inline, als overlay of als zijpaneel opent, volgt uit de instellingen van die deployment. Je hebt hiervoor toegang nodig tot de HTML van je pagina.

Als slimme aanvulling op je zoekmachine. Wil je je bestaande zoekveld verbeteren in plaats van een apart venster tonen? Dan koppel je vragen.ai aan je huidige zoekveld met een apart script (embed-autocomplete.js) dat het dashboard voor je klaarzet. Dit hoort bij de vormen "Auto-aanvullen" en "Search Add-on".

Via de API. Voor maatwerk is er een REST API. Je stuurt een vraag met context naar vragen.ai en krijgt een antwoord met bronnen terug. Het live streamen van antwoorden verloopt via het open AG-UI-protocol, dat vragen.ai ondersteunt, zodat je de widget-ervaring in je eigen interface kunt nabouwen. Zo bouw je vragen.ai in een eigen systeem in, bijvoorbeeld een klantportaal, kennisbank of helpdesk.

Voor interne toepassingen kun je een deployment achter een login afschermen, zodat alleen medewerkers de widget kunnen gebruiken.

Parameters op het embed-script

Bijna alles regel je in de instellingen van je deployment, niet in de code op je site. Zo hoeft de embed niet mee te veranderen als je iets aanpast. Een paar dingen geef je wél per pagina mee in de URL van het script. Dit zijn de parameters die je daarvoor nodig hebt:

forcedFilters is bedoeld voor één situatie: je hebt meerdere sites of subsites die uit dezelfde kennisbank werken, en je wilt op iedere site alleen de eigen content laten zien. Dan staat op elke site hetzelfde script en varieert alleen de parameter:

<script src="https://jouworganisatie.vragen.ai/embed.js?deployment=[deployment-naam]&forcedFilters=source:werk.example.nl"></script>

Je filtert op een metadataveld van je documenten, dus het veld moet in je kennisbank bestaan (zie Je kennisbank in de app). Meerdere waarden scheid je met een |, meerdere filters met een komma, en met != sluit je juist iets uit:

forcedFilters=source:a.example.nl|b.example.nl,type!=archief

Let op: dit filter staat in de URL en is dus voor een bezoeker te zien en aan te passen. Gebruik het om de antwoorden op een pagina relevant te houden, niet om content af te schermen. Moet content écht onbereikbaar blijven voor een groep bezoekers, gebruik dan een aparte deployment met een eigen kennis-scope.

containerSelector heb je nodig als je twee widgets op één pagina zet, bijvoorbeeld een inline venster bij de zoekresultaten en een zijpaneel dat op elke pagina voor je bezoeker klaarstaat. Elke widget zoekt standaard het element #vragenai-app en rendert in het eerste dat hij vindt. Twee widgets met die standaard komen dus in hetzelfde element terecht, en de tweede overschrijft dan de eerste: een van de twee blijft leeg. Geef de tweede widget daarom een eigen element en wijs dat aan in de script-URL. Codeer het hekje als %23, anders leest de browser de rest van de URL als anker en komt de parameter niet aan:

<script src="https://jouworganisatie.vragen.ai/embed.js?deployment=[deployment-naam]&containerSelector=%23vragenai-zijpaneel"></script>
<div id="vragenai-zijpaneel"></div>

Style je die widget met eigen CSS, gebruik dan ook daar dit ID in plaats van #vragenai-app.

Vraagt de API van je omgeving inloggegevens? Dan zijn er extra parameters die de aanroepen van de widget naar een proxy op je eigen domein sturen. Hoe dat werkt, staat in De widget in een afgesloten omgeving.

Bronnen bij een antwoord

Onder ieder antwoord staan de bronnen die de agent heeft geciteerd. Klikt een bezoeker op een bron, dan opent die pagina en is de passage gemarkeerd die de agent heeft gebruikt. Zo ziet iedereen in één klik waar het antwoord vandaan komt.

Het markeren werkt niet op iedere website. Ondersteunt de website het niet, dan opent de pagina zonder markering.

De widget openen vanuit je eigen pagina

Een overlay of zijpaneel hoeft niet alleen via de ingebouwde knop open te gaan. Elke knop of link op je site kan de assistent openen, en er meteen een vraag aan meegeven. Zet bijvoorbeeld naast je aanvraagformulier een knop "Welke documenten heb ik nodig?". Je bezoeker klikt en ziet het antwoord verschijnen, zonder zelf iets te hoeven typen.

Met een attribuut, zonder JavaScript. Opent je deployment via een eigen element op je site (de trigger "CSS-Selector" of "Link / URL"), zet dan data-vragenai-question op dat element. Bij een klik opent het venster en stelt de widget die vraag direct:

<button class="vragenai-trigger" data-vragenai-question="Welke documenten heb ik nodig?">Welke documenten heb ik nodig?</button>

Zonder het attribuut opent hetzelfde element gewoon het venster.

Met je eigen JavaScript. Zodra de widget geladen is, staat er een object window.Vragenai op je pagina met deze functies:

Deze functies bestaan alleen bij de vormen "Overlay" en "Zijpaneel", en pas als de widget geladen is. Controleer daarom eerst of de functie er is:

document.querySelector('#hulp-bij-aanvraag').addEventListener('click', () => {
  if (typeof window.Vragenai?.ask === 'function') {
    window.Vragenai.ask('Welke documenten heb ik nodig?');
  }
});

Staan er twee widgets op de pagina, dan reageert standaard de widget die het laatst geladen is. Wil je er één gericht aansturen, geef dan het element mee waarin die widget rendert, met dezelfde selector als in containerSelector: window.Vragenai.open({ container: '#vragenai-zijpaneel' }), of bij een vraag window.Vragenai.ask('Welke documenten heb ik nodig?', { container: '#vragenai-zijpaneel' }).

De widget stylen

De widget hoort eruit te zien alsof hij bij je website hoort. Kleuren, lettertype en vormgeving pas je aan met je eigen CSS, en dat kan in elk pakket: die regels schrijf je in je eigen stylesheet, dus er zit geen pakketgrens op. Liever vanuit de app? Ook dat kan in elk pakket: in de instellingen van je integratie geef je eigen CSS, HTML of JavaScript mee en verberg je de vragen.ai-branding in de widget.

De widget rendert inline in je pagina, dus niet in een iframe. Alle styling is scoped: de widget lekt geen CSS naar de rest van je site, en je site-CSS haalt de widget niet zomaar overhoop. Wil je iets aanpassen, dan doe je dat bewust met eigen regels. Drie aanknopingspunten:

• Het #vragenai-app-element. Zet dit ID in je selectors; zo winnen jouw regels het van de widget-CSS.

• CSS-variabelen. De widget gebruikt custom properties (zoals --vragenai-color-primary, de primaire kleur) voor kleuren en andere basiswaarden. Zet je die op #vragenai-app, dan kleurt de hele widget mee.

• BEM-classes. Elk onderdeel heeft een eigen class, zoals vragenai-question-form__input voor het invoerveld. Daarmee styl je gericht één onderdeel.

Er is geen gepubliceerde lijst van alle variabelen en classes. Inspecteer de widget in je browser (rechtermuisknop, "Inspecteren") om te zien welke er op een onderdeel van toepassing zijn.

Voorbeeld:

#vragenai-app {
  --vragenai-color-primary: #1d4ed8; /* jouw merkkleur */
  font-family: "Jouw huisstijlfont", sans-serif;
}

#vragenai-app .vragenai-question-form__input {
  font-size: 1.0625rem;
}

Zo doen we het zelf ook: de widget op de homepage van vragen.ai is met dit soort CSS in onze eigen huisstijl gezet, tot en met een merkverloop als rand om het invoerveld.

De teksten in het vraagvenster aanpassen

Je stelt de teksten per integratie in:

• De interfacetaal. Kies per integratie in welke taal de knoppen, labels en placeholder verschijnen, bijvoorbeeld Nederlands, Engels, Duits, Frans, Turks of Arabisch. Je kunt de taal ook meegeven in de embed-URL met de parameter locale.

• Eigen teksten. Wil je een specifieke tekst anders formuleren, zoals de tekst in het invoerveld ("Waar kan ik je mee helpen?") of de tekst als er geen antwoord is? Die overschrijf je in de instellingen van je integratie, per taal.

• Voorbeeldvragen. De suggesties die een bezoeker als eerste ziet, stel je in bij de integratie. Het aantal ligt niet vast: voeg toe of verwijder wat je wilt.

Een wijziging staat binnen ongeveer vijf minuten bij je bezoekers: zo lang mag de browser het embed-script bewaren. Wil je het zelf eerder zien, ververs de pagina dan met een harde refresh.

De taal van de antwoorden

De taal van de interface staat los van de taal van de antwoorden. De assistent antwoordt standaard in de taal waarin de vraag gesteld is. Twijfelt hij over de taal, dan valt hij terug op het Nederlands.

Content Security Policy

Veel organisaties, zeker in de overheid en de zorg, beveiligen hun website met een Content Security Policy (CSP): een header die bepaalt welke externe bronnen de browser mag laden. De widget is daar makkelijk in mee te nemen, omdat hij maar één domein nodig heeft.

Alles komt van je eigen vragen.ai-subdomein. Concreet:

• Scripts: embed.js en de JavaScript-bundel van de widget

• Stylesheet: één CSS-bestand

• API-verzoeken: het stellen van vragen en het streamen van antwoorden

• Afbeeldingen: beelden die de widget toont komen eveneens van je eigen subdomein

Er zijn geen externe CDN's, fonts, trackers of iframes. De widget zet wel op enkele onderdelen inline styles; daar houdt het voorbeeld hieronder rekening mee.

Vervang jouworganisatie.vragen.ai door je eigen subdomein en voeg deze bronnen toe aan je bestaande policy:

script-src  'self' https://jouworganisatie.vragen.ai;
style-src   'self' https://jouworganisatie.vragen.ai 'unsafe-inline';
connect-src 'self' https://jouworganisatie.vragen.ai;
img-src     'self' https://jouworganisatie.vragen.ai;

De 'unsafe-inline' in style-src is nodig voor de inline styles van de widget. Wil je die niet site-breed toestaan, gebruik dan de fijnmazigere style-src-attr-richtlijn. frame-src is niet nodig: de widget rendert direct in je pagina, zonder iframe.

Werk je met een nonce?

Gebruikt je policy nonces in plaats van 'unsafe-inline', dan geef je die nonce mee op het embed-script. De widget zet hem daarna zelf op het script en de stylesheet die hij toevoegt, dus die passeren je policy zonder dat je 'unsafe-inline' hoeft te openen:

<script src="https://jouworganisatie.vragen.ai/embed.js?deployment=[deployment-naam]"
        data-script-nonce="NaN"
        data-style-nonce="NaN"></script>

Is het dezelfde waarde voor beide, dan volstaat één data-nonce. Staat de nonce al als gewoon nonce-attribuut op het script, dan gebruikt de widget die.

Eén ding blijft: de widget zet op enkele elementen ook een style-attribuut, en een nonce geldt niet voor attributen. Houd daarvoor style-src-attr 'unsafe-inline' aan; dat is een stuk enger dan 'unsafe-inline' op je hele style-src.

Blokkeert je CSP toch iets? Dat zie je als fout in de browserconsole (F12). Mail de foutmelding naar service@vragen.ai; we reageren binnen één werkdag.

Veelgestelde vragen

Kan ik meerdere widgets op één pagina gebruiken?
Ja, met aparte deployments, elk met een eigen configuratie. Geef elke widget wel een eigen element op de pagina met de parameter containerSelector (zie "Parameters op het embed-script" hierboven); anders renderen ze allebei in hetzelfde element en blijft er één leeg.

Kunnen we zelf het design aanpassen?
Ja. In elk pakket style je de widget met eigen CSS: kleuren, lettertype en meer (zie "De widget stylen" hierboven). Je eigen CSS kun je ook vanuit de app meegeven, en daar verberg je ook de vragen.ai-branding voor een volledige white-labelweergave. Dat kan in elk pakket.

Wat als we nog geen toegang hebben tot onze site?
Begin dan met de link naar een gehoste pagina. Je kunt later altijd overstappen op een embed.

Hulp nodig?
Ons team helpt je stap voor stap. Mail naar service@vragen.ai of plan een integratiecall in.