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

De widget stylen

De widget hoort eruit te zien alsof hij bij je website hoort. Dat kan in elk pakket: je past de vormgeving volledig aan met je eigen CSS.

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.

Zie je een wijziging niet meteen, 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.

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.

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 kunt de vragen.ai-branding ook verbergen voor een volledige white-labelweergave.

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.