Embed-widget live zetten

Embed-widget live zetten

Wat je precies live zet

De Fynd embed-widget is een script dat je op je webshop plaatst. Bezoekers zien een launcher (blob) en kunnen een gesprek openen met je AI-productadviseur. Antwoorden komen uit je gekoppelde catalogus (sitemap, feed, Catalog API) en custom knowledge. De widget praat met Fynd via je embed-key: een publieke sleutel die in HTML mag staan, net als een analytics-sitekey.

Dit artikel is een operationele handleiding: waar je het script plaatst, welke attributen je instelt, hoe je PDP versus listingpagina's benadert, en welke fouten teams het vaakst maken vóór go-live.

Voorbereiding: checklist vóór je code kopieert

Zorg dat deze stappen af zijn voordat je het snippet op productie plakt:

1. Kennis staat klaar: minstens één sync met producten of chunks (controleer in Kennis of in de playground: "Live kennis actief").
2. Bot is ingericht: persona, welkomsttekst, disclaimer en voorgestelde prompts zijn ingevuld.
3. Playground-tests zijn geslaagd: zie het aparte artikel over testen vóór live.
4. Domein is geconfigureerd: onder Shop-instellingen: primair domein en toegestane domeinen.
5. Embed builder is doorgelopen: positie, launcher en bot-slug staan goed.

Zonder kennis laadt de widget wel, maar antwoorden blijven leeg of generiek. Zonder juist domein krijg je op productie Origin not allowed.

Het script-snippet: veld voor veld

Open in het Fynd-dashboard Embed builder (Embed-code). Daar kies je bot, positie en launcher; het systeem genereert een kant-en-klaar snippet. Een typisch voorbeeld:

<script
  src="https://jouw-fynd-domein/widget/fynd.js"
  data-key="pk_live_…"
  data-bot="default"
  data-position="right"
  data-launcher="💬"
  async>
</script>

src: Laadt fynd.js vanaf je Fynd-installatie. Gebruik altijd HTTPS en het officiële domein van je Fynd-omgeving, geen lokale kopie tenzij je bewust ontwikkelt.

data-key: Je embed-key. Koppel chatverkeer aan jouw shop. Kopieer hem uit Shop-instellingen of de embed-pagina. Verwar hem niet met een Catalog API-key (sk_live_…); die hoort nooit in de browser.

data-bot: De slug van de bot-persona die bezoekers spreken. Standaard vaak default. Elke extra bot heeft een eigen slug (bijv. outdoor, zakelijk). Een verkeerde slug geeft een andere persona, andere prompts of zelfs geen bot.

data-position: right (standaard) of left. Bepaalt waar de launcher en het chatpaneel verschijnen.

data-launcher: Emoji of kort label (max. 8 tekens) op de launcher-knop. Voorbeelden: 💬, Help, AI.

data-launcher-icon (optioneel), URL naar een icoonafbeelding. Vervangt het emoji-label wanneer je een merkicoon wilt tonen.

async: Laadt het script zonder de pagina te blokkeren. Aanbevolen op elke productiepagina.

Optioneel kun je in ontwikkeling data-api zetten als je tegen een andere API-base test; op productie laat je dit weg.

Waar het script plaatsen

Plak het snippet vóór </body> op elke pagina waar de adviseur beschikbaar moet zijn. Veel shops laden het site-wide via:

• een thema-footer (WooCommerce, Shopify theme.liquid, Magento layout)
• een tag manager (Google Tag Manager); let op dat consent tooling het script niet permanent blokkeert
• een CMS "custom code"-veld

Site-wide versus per paginatype

Site-wide (aanbevolen startpunt): Eén snippet in footer of global layout. De widget verschijnt overal met dezelfde bot. Fynd stuurt bij elk bericht de huidige pagina-URL mee (window.location.href), zodat RAG context van "waar de bezoeker staat" kan gebruiken.

Alleen productpagina's (PDP): Sommige teams starten bewust op product detail pages (PDP) om focus te houden tijdens een pilot. Plaats het script dan alleen in het PDP-template. Nadeel: bezoekers op categorie- of homepagina's zien geen adviseur.

Listing- en categoriepagina's: Handig wanneer shoppers vergelijken of nog geen specifiek product hebben gekozen. Dezelfde embed werkt; test vragen als "Wat past bij beginners?" of "Verschil tussen model A en B?".

Checkout en account: Meestal niet embedden tenzij je bewust pre-sale advies daar wilt. De launcher kan anders naast betaalknoppen of cookiebanners vallen. Test altijd op mobiel.

Er is geen apart "PDP-modus" in het script. Het verschil zit in waar je het laadt en welke URL de bezoeker heeft wanneer hij typt.

Open versus gesloten standaard

Op een live webshop start de widget gesloten: bezoekers zien alleen de launcher-blob; het chatpaneel opent na een klik. Dat is de standaard en meest gebruikte instelling, weinig storend, lage drempel.

In de playground opent de widget inline en direct, zodat je snel kunt testen. Dat gedrag hoort niet op productie na te bootsen tenzij je bewust FyndWidget.mount() gebruikt met open: true via custom JavaScript. Voor normale embeds via script-tag: reken op gesloten by default.

Overwegingen:

• Gesloten: Minder visuele druk; geschikt voor brede rollout.
• Programmatisch open: Alleen via custom integratie; niet nodig voor standaard shops.

Themakleuren en uiterlijk

Kleuren staan per bot onder Thema: primair, accent, achtergrond, tekst. Standaardwaarden zijn blauw/oranje op wit; pas ze aan op je huisstijl.

Je kunt kleuren ook finetunen in de playground onder "Uiterlijk". Opslaan schrijft naar de bot én embed-instellingen (launcher, positie, avatar). Controleer contrast: lichte tekst op lichte achtergrond maakt disclaimers onleesbaar.

Avatar URL: Foto of logo in de chatheader. Launcher icoon URL: Vervangt emoji op de blob. Host afbeeldingen op HTTPS met CORS-toegang; gebroken URLs vallen terug op initialen.

Fynd-branding: Op Starter en Growth staat branding in de chat aan tenzij je upgrade naar Pro (verbergen op Pro). Stel dit in via Embed builder.

Welkomstbericht, disclaimer en voorgestelde prompts

Deze velden staan bij Bot-persona → Widgettekst, niet in het script.

Welkomstbericht: Eerste zin in de chat. Leg kort uit wat de bot doet en nodig uit tot een vraag. Vermijd "Ik ben een mens" als het een bot is.

Disclaimer: Korte waarschuwing onder de header (bijv. dat antwoorden op catalogusdata berusten en fouten kunnen bevatten). Geen medische of juridische claims tenzij formeel goedgekeurd.

Voorgestelde prompts: Maximaal acht, één per regel. Chips die bezoekers kunnen tikken. Gebruik echte shopperformuleringen: "Welke maat past bij…?", "Verschil tussen X en Y?", "Wat is jullie retourbeleid?"

Fallback bij ontbrekende kennis: Tekst wanneer RAG niets vindt. Houd het eerlijk; verwijs naar support indien nodig.

Sla persona op en herlaad de widget op je shop om wijzigingen te zien. Browsercache of CDN kan oude fynd.js-config vertraagd tonen; hard refresh na grote wijzigingen.

Mobiel testen

De widget is responsive: paneel schaalt naar schermbreedte, productslider scrollt horizontaal. Controleer op echte devices:

• Bedekt de launcher je sticky "Bestellen"-knop of cookiebanner?
• Is de composer bereikbaar met toetsenbord open (iOS Safari)?
• Zijn voorgestelde prompts leesbaar zonder horizontaal scrollen?
• Werkt de productslider met touch?

Test ook landscape op telefoon. Links (data-position="left") kan beter als je rechts al een chat-knop van WhatsApp hebt.

Domein en beveiliging

Onder Shop → Toegang & embed:

Primair domein: Referentie voor page-URL in playground en context.

Toegestane domeinen: Kommagescheiden lijst (bijv. shop.nl, www.shop.nl). Fynd controleert Origin/Referer. Staat je productiedomein er niet bij, faalt de widget met Origin not allowed. Voor lokaal ontwikkelen kun je localhost toevoegen; * of leeg staat alles toe (alleen voor dev, niet productie.

Wijzig je domein na migratie (www → apex, nieuw TLD)? Update allowed domains vóór je DNS omzet.

Go-live checklist

Gebruik deze lijst op de dag van lancering:

• Embed-key in snippet komt overeen met actieve shop
• data-bot slug bestaat en is de bedoelde persona
• Toegestane domeinen bevatten productie-hostname(s)
• Script laadt op PDP, categorie, home en mobiel (Network-tab: 200 op fynd.js)
• Geen dubbele script-tags (dubbele launchers)
• Consent/cookie tool blokkeert script niet na acceptatie
• Welkomsttekst, disclaimer en prompts zijn gecontroleerd
• Ten minste vijf echte productvragen getest op productie (niet alleen playground)
• Productlinks in antwoorden openen juiste PDP
• Lead capture (indien aan) vraagt geen overbodige velden
• APP_DEBUG uit op Fynd-server; geen stack traces zichtbaar voor bezoekers
• Analytics (Growth+); noteer startdatum voor latere vergelijking

Veelvoorkomende fouten

Verkeerd domein: Staging-key op productie of omgekeerd; of allowed domains vergeten na launch. Symptoom: widget zichtbaar maar berichten falen. Fix: domains + key controleren.

Debug-modus verwarren: Retrieval-debug zie je in de playground, niet op de live shop. Als iemand per ongeluk denkt dat shoppers debug zien: dat is niet standaard. Wel: zet nooit Catalog API-keys in theme code "om te testen".

Verkeerde bot-slug: Typo in data-bot (defualt) of oude slug na bot-rename. Symptoom: verkeerde persona, lege kennis of 404 op bot-config. Fix: slug in Bots-overzicht vergelijken met snippet.

Dubbele embed: Script twee keer in footer + GTM. Dubbele launchers, dubbele events. Fix: één bron van waarheid.

Geen kennis: Widget live terwijl sync nog loopt. Fix: wacht op sync, test opnieuw.

Launcher bedekt UI: Positie wisselen naar links of launcher-label korter maken.

Thema-update verwijdert snippet: Documenteer embed-locatie in je runbook; test na elke theme deploy.

Vergeten Pro vs branding: Verwachting "white label" terwijl plan branding toont. Fix: plan controleren of branding-optie in embed builder.

Na go-live: eerste week

• Bekijk analytics (opens, berichten, productkliks, leads, onbeantwoorde vragen) dagelijks de eerste week.
• Voeg FAQ's toe voor vragen die de bot niet beantwoordt.
• Herhaal playground-scenario's na cataloguswijzigingen (nieuwe collectie, prijswijziging).
• Noteer embed-snippet, bot-slug per taal/markt en sync-eigenaar in interne documentatie.

De embed is bewust eenvoudig: één script, duidelijke attributen, sterke afhankelijkheid van goede kennis en domeinconfiguratie. Wie dat strak regelt, krijgt een betrouwbare adviseur op elke pagina waar shoppers om hulp vragen.