Widget Integratie

Complete documentatie voor het integreren van FunnelFlow formulieren op externe websites via de FunnelWidget.

Installatie

Voeg de widget script toe aan je HTML pagina:

<script src="https://your-domain.com/widget/widget.umd.js" defer></script>

TIP

Gebruik defer om te zorgen dat het script pas laadt nadat de HTML is geparsed.

Initialisatie Methodes

Er zijn twee manieren om de widget te initialiseren: HTML (declaratief) of JavaScript (programmatisch).

Methode 1: HTML Attributen (Aanbevolen)

De eenvoudigste manier is via data-ff-* attributen op HTML elementen.

Inline Mode

Het formulier wordt direct op de pagina gerenderd binnen het element.

<div 
  data-ff-form="jouw-form-id"
  data-ff-mode="inline"
></div>

Sidebar Mode

Het formulier opent als een slide-in panel vanaf de rechterkant van het scherm.

<!-- Widget container -->
<div 
  data-ff-form="jouw-form-id"
  data-ff-mode="sidebar"
  data-ff-trigger=".open-sidebar-btn"
></div>

<!-- Trigger button -->
<button class="open-sidebar-btn">Open Formulier</button>

Modal Mode

Het formulier opent als een centered popup overlay.

<!-- Widget container -->
<div 
  data-ff-form="jouw-form-id"
  data-ff-mode="modal"
  data-ff-trigger=".open-modal-btn"
></div>

<!-- Trigger button -->
<button class="open-modal-btn">Open Modal</button>

Beschikbare Data Attributen

Attribuut	Verplicht	Beschrijving
data-ff-form	✅ Ja	De unieke form ID
data-ff-mode	❌ Nee	inline (default), sidebar, of modal
data-ff-trigger	❌ Nee	CSS selector voor trigger element(en)
data-ff-reset-on-open	❌ Nee	Reset formulier naar eerste pagina bij openen
data-ff-reset-on-close	❌ Nee	Reset formulier naar eerste pagina bij sluiten
data-ff-dynamic-resize	❌ Nee	Automatisch iframe hoogte aanpassen

Methode 2: JavaScript API

Voor meer controle kun je de widget programmatisch initialiseren.

Auto-initialisatie

// Initialiseert automatisch alle elementen met data-ff-form attributen
FunnelWidget.init();

// Met custom base URL
FunnelWidget.init({
  baseUrl: 'https://forms.example.com'
});

Handmatige Widget Creatie

FunnelWidget.embed({
  formId: 'jouw-form-id',
  target: '#mijn-container',    // CSS selector voor container element
  mode: 'sidebar',              // 'inline' | 'sidebar' | 'modal'
  resetOnOpen: true,            // Optioneel: reset bij openen
  resetOnClose: false,          // Optioneel: reset bij sluiten
  triggerElement: '.mijn-knop'  // Optioneel: CSS selector voor triggers
});

Widget Openen via JavaScript

Basis

// Open een sidebar of modal widget
FunnelWidget.open('jouw-form-id');

Met Extra Parameters

FunnelWidget.open('jouw-form-id', {
  params: {
    source: 'homepage',
    campaign: 'zomer-actie'
  }
});

Met Reset

// Open en forceer reset naar eerste pagina
FunnelWidget.open('jouw-form-id', { reset: true });

Gecombineerd

FunnelWidget.open('jouw-form-id', {
  params: { product: 'prod-123' },
  reset: true
});

Product Openen (Configurator)

Voor configurator formulieren kun je direct een specifiek product openen, zodat de gebruiker meteen bij dat product start.

Via JavaScript

// Open widget met specifiek product
FunnelWidget.open('configurator-form-id', {
  params: {
    product: 'product-uuid-123'
  }
});

// Met meerdere parameters
FunnelWidget.open('configurator-form-id', {
  params: {
    product: 'product-uuid-123',
    variant: 'blauw',
    source: 'productpagina'
  }
});

Via HTML Trigger Attributen

Elk data-ff-* attribuut op een trigger element (behalve data-ff-trigger) wordt automatisch als URL parameter naar het formulier gestuurd.

<!-- Widget container -->
<div 
  data-ff-form="configurator-form-id"
  data-ff-mode="modal"
></div>

<!-- Product knop - opent direct product A -->
<button 
  data-ff-trigger="configurator-form-id"
  data-ff-product="product-uuid-123"
>
  Configureer Product A
</button>

<!-- Product knop met extra parameters -->
<button 
  data-ff-trigger="configurator-form-id"
  data-ff-product="product-uuid-456"
  data-ff-variant="premium"
  data-ff-source="homepage"
>
  Configureer Product B (Premium)
</button>

Volledige Voorbeelden

Voorbeeld 1: Productcatalogus met Configurator Modal

<!DOCTYPE html>
<html>
<head>
  <title>Onze Producten</title>
  <script src="https://forms.example.com/widget/widget.umd.js" defer></script>
</head>
<body>

  <!-- Widget container (onzichtbaar totdat geopend) -->
  <div 
    data-ff-form="mijn-configurator"
    data-ff-mode="modal"
    data-ff-reset-on-open="true"
  ></div>

  <!-- Product Grid -->
  <div class="product-grid">
    
    <div class="product-card">
      <img src="product-a.jpg" alt="Product A">
      <h3>Product A</h3>
      <p>Vanaf € 299,00</p>
      <button 
        data-ff-trigger="mijn-configurator"
        data-ff-product="prod-001"
      >
        Configureren
      </button>
    </div>

    <div class="product-card">
      <img src="product-b.jpg" alt="Product B">
      <h3>Product B</h3>
      <p>Vanaf € 449,00</p>
      <button 
        data-ff-trigger="mijn-configurator"
        data-ff-product="prod-002"
      >
        Configureren
      </button>
    </div>

  </div>

</body>
</html>

Voorbeeld 2: Sidebar met Contact Formulier

<!DOCTYPE html>
<html>
<head>
  <title>Contact</title>
  <script src="https://forms.example.com/widget/widget.umd.js" defer></script>
</head>
<body>

  <!-- Widget container -->
  <div 
    data-ff-form="contact-formulier"
    data-ff-mode="sidebar"
    data-ff-trigger=".contact-btn"
    data-ff-reset-on-close="true"
  ></div>

  <!-- Meerdere trigger buttons -->
  <button class="contact-btn">Contact opnemen</button>
  
  <nav>
    <a href="#" class="contact-btn">Contact</a>
  </nav>

</body>
</html>

Voorbeeld 3: JavaScript Integratie met Custom Logic

<!DOCTYPE html>
<html>
<head>
  <title>Custom Integratie</title>
  <script src="https://forms.example.com/widget/widget.umd.js" defer></script>
</head>
<body>

  <div id="widget-container"></div>
  
  <button id="btn-basic">Open Formulier</button>
  <button id="btn-product-a">Product A Configureren</button>
  <button id="btn-product-b">Product B Configureren</button>

  <script>
    document.addEventListener('DOMContentLoaded', () => {
      
      // Initialiseer widget programmatisch
      FunnelWidget.embed({
        formId: 'mijn-configurator',
        target: '#widget-container',
        mode: 'sidebar',
        resetOnOpen: true
      });

      // Basic open
      document.getElementById('btn-basic').addEventListener('click', () => {
        FunnelWidget.open('mijn-configurator');
      });

      // Open met Product A
      document.getElementById('btn-product-a').addEventListener('click', () => {
        FunnelWidget.open('mijn-configurator', {
          params: { product: 'prod-001' }
        });
      });

      // Open met Product B + extra tracking
      document.getElementById('btn-product-b').addEventListener('click', () => {
        FunnelWidget.open('mijn-configurator', {
          params: { 
            product: 'prod-002',
            source: 'custom-button',
            campaign: 'winter-sale'
          }
        });
      });

    });
  </script>

</body>
</html>

Voorbeeld 4: Dynamisch Gegenereerde Product Knoppen

// Product data (bijv. van API)
const products = [
  { id: 'prod-001', name: 'Widget Pro', price: 299 },
  { id: 'prod-002', name: 'Widget Max', price: 449 },
  { id: 'prod-003', name: 'Widget Ultra', price: 599 }
];

// Container element
const container = document.getElementById('product-buttons');

// Genereer knoppen
products.forEach(product => {
  const button = document.createElement('button');
  button.textContent = `Configureer ${product.name}`;
  button.className = 'product-btn';
  
  button.addEventListener('click', () => {
    FunnelWidget.open('configurator-form', {
      params: { 
        product: product.id,
        source: 'dynamic-catalog'
      },
      reset: true
    });
  });
  
  container.appendChild(button);
});

API Reference

FunnelWidget.init(options?)

Initialiseert alle widgets op de pagina met data-ff-form attributen.

Parameters:

Optie	Type	Default	Beschrijving
baseUrl	string	Auto-detect	Base URL voor de formulieren

Voorbeeld:

FunnelWidget.init();
FunnelWidget.init({ baseUrl: 'https://forms.example.com' });

FunnelWidget.embed(options)

Maakt een widget op een specifiek DOM element.

Parameters:

Optie	Type	Verplicht	Beschrijving
formId	string	✅	De unieke form ID
target	string	✅	CSS selector voor container element
mode	string	❌	'inline', 'sidebar', of 'modal'
resetOnOpen	boolean	❌	Reset formulier naar begin bij openen
resetOnClose	boolean	❌	Reset formulier naar begin bij sluiten
triggerElement	string	❌	CSS selector voor trigger element(en)

Voorbeeld:

FunnelWidget.embed({
  formId: 'mijn-form',
  target: '#container',
  mode: 'modal',
  resetOnOpen: true,
  triggerElement: '.open-btn'
});

FunnelWidget.open(formId, options?)

Opent een widget programmatisch (alleen voor sidebar en modal modes).

Parameters:

Parameter	Type	Beschrijving
formId	string	De form ID van de widget om te openen
options.params	object	URL parameters om door te geven aan het formulier
options.reset	boolean	Forceer reset naar eerste pagina

Voorbeelden:

// Basis
FunnelWidget.open('mijn-form');

// Met parameters
FunnelWidget.open('mijn-form', {
  params: { product: 'prod-123', source: 'homepage' }
});

// Met reset
FunnelWidget.open('mijn-form', { reset: true });

// Gecombineerd
FunnelWidget.open('mijn-form', {
  params: { product: 'prod-123' },
  reset: true
});

Ondersteunde URL Parameters

De volgende URL parameters worden door het formulier herkend:

Parameter	Beschrijving
product	Product ID - opent direct dit product in een configurator
source	Tracking - bron van de bezoeker
campaign	Tracking - campagne naam
*	Alle custom parameters worden doorgegeven aan het formulier

Reset Gedrag

Reset bij Openen (resetOnOpen)

Wanneer ingeschakeld, wordt het formulier altijd naar de eerste pagina gereset wanneer de widget wordt geopend. Handig voor:

• Productcatalogussen waar elke knop een ander product opent
• Situaties waar je niet wilt dat gebruikers halverwege terugkomen

Reset bij Sluiten (resetOnClose)

Wanneer ingeschakeld, wordt het formulier gereset wanneer de widget wordt gesloten. Handig voor:

• Privacy: formulierdata wordt gewist na sluiten
• Fresh start bij volgende opening

Hybrid Reset (Automatisch)

Bij het openen met nieuwe parameters (bijv. ander product) wordt automatisch een "hard reset" uitgevoerd waarbij het iframe volledig opnieuw laadt. Bij openen zonder nieuwe parameters wordt een "soft reset" uitgevoerd via postMessage (sneller).

Tips & Best Practices

Reset bij producten

Gebruik data-ff-reset-on-open="true" wanneer je meerdere producten hebt die elk hun eigen configuratie starten.

Trigger selectors

Je kunt classes (.btn), IDs (#open-btn), of attribute selectors ([data-action="open"]) gebruiken.

Meerdere widgets

Je kunt meerdere widgets op één pagina hebben, elk met een unieke formId.

Tracking

Gebruik data-ff-source en data-ff-campaign op triggers voor conversie tracking.

Troubleshooting

Widget opent niet

• Controleer of het script correct is geladen
• Controleer of de formId correct is
• Check de browser console voor errors

Formulier laadt niet

• Controleer of de base URL correct is
• Check of het formulier gepubliceerd is
• Controleer CORS settings

Reset werkt niet

• Zorg dat resetOnOpen of resetOnClose is ingeschakeld
• Bij programmatisch openen: gebruik { reset: true }