24 aug 2025·8 min
Hoe je een webapp bouwt voor onboarding met meerdere stappen
Leer hoe je een webapp ontwerpt en bouwt die onboarding met meerdere stappen creëert, bijhoudt en verbetert met duidelijke stappen, datamodellen en tests.
Leer hoe je een webapp ontwerpt en bouwt die onboarding met meerdere stappen creëert, bijhoudt en verbetert met duidelijke stappen, datamodellen en tests.
Een onboarding met meerdere stappen is een begeleide reeks schermen die een nieuwe gebruiker helpt van “aangemeld” naar “klaar om het product te gebruiken” te gaan. In plaats van alles in één keer te vragen, verdeel je de setup in kleinere stappen die in één keer of verspreid over tijd kunnen worden afgerond.
Je hebt multi-step onboarding nodig wanneer de setup meer is dan een enkel formulier — vooral als het keuzes, vereisten of compliance-checks bevat. Als je product context nodig heeft (branche, rol, voorkeuren), verificatie (e-mail/telefoon/identiteit) of initiële configuratie (workspaces, betalingen, integraties), houdt een stap-gewijze flow het overzichtelijk en vermindert het fouten.
Multi-step onboarding is overal omdat het taken ondersteunt die van nature in fasen gebeuren, zoals:
Een goede onboardingflow zijn niet alleen “afgewerkte schermen”, maar gebruikers die snel waarde bereiken. Definieer succes in termen die bij je product passen:
De flow moet ook hervatten en continuïteit ondersteunen: gebruikers kunnen weggaan en terugkomen zonder voortgang te verliezen en moeten landen op de volgende logische stap.
Multi-step onboarding faalt op voorspelbare manieren:
Je doel is dat onboarding voelt als een begeleid pad, niet als een test: duidelijk doel per stap, betrouwbare voortgangsregistratie en een makkelijke manier om op te pakken waar de gebruiker was gebleven.
Voordat je schermen tekent of code schrijft, besluit wat je onboarding wil bereiken — en voor wie. Een multi-step flow is alleen “goed” als die betrouwbaar de juiste mensen naar de juiste eindstatus brengt met minimale verwarring.
Verschillende gebruikers komen binnen met verschillende context, permissies en urgentie. Begin met het benoemen van je primaire entry-persona’s en wat je al van ze weet:
Voor elk type, noteer beperkingen (bijv. “kan bedrijfsnaam niet bewerken”), vereiste data (bijv. “moet workspace kiezen”) en mogelijke shortcuts (bijv. “al geverifieerd via SSO”).
Je onboarding-eindstatus moet expliciet en meetbaar zijn. “Klaar” is niet “alle schermen voltooid”; het is een business-ready status, zoals:
Schrijf de voltooiingscriteria als een checklist die je backend kan evalueren, niet als een vage doelstelling.
Breng in kaart welke stappen verplicht zijn voor de eindstatus en welke optioneel zijn als verbetering. Documenteer daarna afhankelijkheden (“kan teamleden niet uitnodigen voordat workspace bestaat”).
Bepaal ten slotte skip-regels precies: welke stappen kunnen worden overgeslagen, door welk gebruikerstype en onder welke voorwaarden (bijv. “sla e-mailverificatie over als geauthenticeerd via SSO”), en of overgeslagen stappen later in instellingen kunnen worden herzien.
Voordat je schermen of API's bouwt, teken de onboarding als een flowmap: een klein diagram dat elke stap toont, waar een gebruiker daarna heen kan en hoe ze later kunnen terugkeren.
Schrijf de stappen als korte, actiegerichte namen (werkwoorden helpen): “Wachtwoord aanmaken”, “E-mail bevestigen”, “Bedrijfsgegevens toevoegen”, “Nodig teamleden uit”, “Betaling koppelen”, “Klaar”. Houd de eerste versie simpel, voeg daarna details toe zoals vereiste velden en afhankelijkheden (bijv. betaling kan niet vóór planselectie).
Een nuttige check: elke stap moet één vraag beantwoorden — “Wie ben je?” “Wat heb je nodig?” of “Hoe moet het product worden geconfigureerd?” Als een stap probeert alle drie te doen, splits die dan.
De meeste producten profiteren van een grotendeels lineaire ruggengraat met conditionele vertakkingen alleen wanneer de ervaring echt verschilt. Typische regels voor vertakkingen:
Documenteer deze als “if/then”-notities op de map (bijv. “If region = EU → show VAT step”). Dit houdt de flow begrijpelijk en voorkomt dat je een doolhof bouwt.
Maak een lijst van elke plek waar een gebruiker de flow kan binnenkomen:
/settings/onboarding)Elke ingang moet de gebruiker op de juiste volgende stap brengen, niet altijd op stap één.
Ga ervan uit dat gebruikers halverwege vertrekken. Beslis wat er gebeurt als ze terugkeren:
Je map moet een duidelijke “resume”-route tonen zodat de ervaring betrouwbaar, niet fragiel aanvoelt.
Goede onboarding voelt als een begeleid pad, niet als een test. Het doel is besluitmoeheid te verminderen, verwachtingen duidelijk te maken en gebruikers snel te helpen herstellen als iets misgaat.
Een wizard werkt het beste wanneer stappen in volgorde moeten worden afgerond (bijv. identiteit → betaling → permissies). Een checklist past bij onboarding die in willekeurige volgorde kan plaatsvinden (bijv. “Logo toevoegen”, “Team uitnodigen”, “Agenda koppelen”). Guided tasks (in-product tips en callouts) zijn goed als leren gebeurt door te doen, niet door formulieren in te vullen.
Als je twijfelt, begin met een checklist + deep links naar elke taak en zet pas poorten (gates) voor echt verplichte stappen.
Voortgangsfeedback moet antwoord geven op: “Hoeveel is er nog te doen?” Gebruik één van de volgende:
Voeg ook een “Opslaan en later afronden” hint toe, vooral bij langere flows.
Gebruik eenvoudige labels (“Bedrijfsnaam”, niet “Entiteitsidentificator”). Voeg microcopy toe die uitlegt waarom je iets vraagt (“Dit gebruiken we om facturen te personaliseren”). Prefill waar mogelijk met bestaande data en kies veilige standaarden.
Ontwerp fouten als een pad vooruit: markeer het veld, leg uit wat te doen, behoud gebruikersinvoer en focus het eerste ongeldige veld. Bij serverfouten: toon een retry-optie en behoud voortgang zodat gebruikers niet voltooide stappen opnieuw hoeven te doen.
Maak tapdoelen groot, vermijd multi-column formulieren en houd sticky primaire acties zichtbaar. Zorg voor volledige toetsenbordnavigatie, zichtbare focusstaten, gelabelde inputs en screenreader-vriendelijke voortgangstekst (niet alleen een visuele balk).
Een soepele multi-step onboardingflow hangt af van een datamodel dat betrouwbaar drie vragen kan beantwoorden: wat de gebruiker vervolgens moet zien, wat ze al hebben ingevuld, en welke definitie van de flow ze volgen.
Begin met een kleine set tabellen/collecties en breid alleen uit als dat nodig is:
Deze scheiding houdt “configuratie” (Flow/Step) gescheiden van “gebruikersdata” (StepResponse/Progress).
Bepaal vroeg of flows versioned zijn. In de meeste producten is het antwoord ja.
Wanneer je stappen wijzigt (naam, volgorde, verplichte velden), wil je niet dat gebruikers die al bezig zijn plots falen in validatie of hun plek verliezen. Een eenvoudige aanpak is:
id en version (of een onveranderlijk flow_version_id).flow_version_id.Bij het opslaan van voortgang kun je kiezen tussen autosave (opslaan terwijl de gebruiker typt) en expliciet 'Volgende' opslaan. Veel teams combineren: autosave drafts, maar markeer de stap “compleet” alleen bij Next.
Houd tijdstempels bij voor rapportage en troubleshooting: started_at, completed_at en last_seen_at (plus per-stap saved_at). Deze velden voeden onboarding-analytics en helpen supportteams te begrijpen waar iemand vastliep.
Een multi-step onboardingflow is het makkelijkst te begrijpen als je het behandelt als een toestandsmachine: de onboarding-sessie van een gebruiker bevindt zich altijd in één “staat” (huidige stap + status), en je staat alleen specifieke transities toe tussen staten.
In plaats van de frontend naar elke URL te laten springen, definieer je een kleine set statussen per stap (bijvoorbeeld: not_started → in_progress → completed) en een duidelijke set transities (bijvoorbeeld: start_step, save_draft, submit_step, go_back, reset_step).
Dit geeft voorspelbaar gedrag:
Een stap is alleen “voltooid” wanneer beide voorwaarden zijn voldaan:
Sla de serverbeslissing op naast de stap, inclusief foutcodes. Dit voorkomt gevallen waarin de UI denkt dat een stap klaar is maar de backend het niet eens is.
Een makkelijk te missen randgeval: een gebruiker wijzigt een eerdere stap en maakt latere stappen ongeldig. Voorbeeld: het veranderen van “Land” kan “Belastinggegevens” of “Beschikbare plannen” ongeldig maken.
Behandel dit door afhankelijkheden bij te houden en downstream-stappen opnieuw te evalueren na elke submit. Gebruikelijke uitkomsten:
needs_review (of zet terug naar in_progress).“Back” moet worden ondersteund, maar veilig:
Dit maakt de ervaring flexibel en houdt de sessiestaat consistent en afdwingbaar.
Je backend-API is de “bron van waarheid” voor waar een gebruiker zich bevindt in onboarding, wat ze al hebben ingevuld en wat ze vervolgens mogen doen. Een goede API houdt de frontend simpel: die kan de huidige stap renderen, data veilig verzenden en herstellen na refreshes of netwerkproblemen.
Minimaal ontwerp je voor de volgende acties:
GET /api/onboarding → retourneert huidige stapkey, voltooiingspercentage en eventuele opgeslagen draftwaarden die nodig zijn om de stap te renderen.PUT /api/onboarding/steps/{stepKey} met { "data": {…}, "mode": "draft" | "submit" }POST /api/onboarding/steps/{stepKey}/nextPOST /api/onboarding/steps/{stepKey}/previousPOST /api/onboarding/complete (server verifieert dat alle verplichte stappen zijn voldaan)Houd responses consistent. Bijvoorbeeld: na opslaan, retourneer de geüpdatete voortgang plus de door de server bepaalde volgende stap:
{ "currentStep": "profile", "nextStep": "team", "progress": 0.4 }
Gebruikers zullen dubbel klikken, opnieuw proberen bij slechte verbinding of je frontend kan requests opnieuw versturen na een timeout. Maak “opslaan” veilig door:
Idempotency-Key header te accepteren voor PUT/POST requests en deduplicatie te doen op (userId, endpoint, key).PUT /steps/{stepKey} te behandelen als een volledige overschrijving van die stappayload (of duidelijk documenteren wat er gedeeltelijk gemerged wordt).version (of etag) toe te voegen om te voorkomen dat nieuwere data met oude retries wordt overschreven.Retourneer bruikbare messages die de UI naast velden kan tonen:
{
"error": "VALIDATION_ERROR",
"message": "Please fix the highlighted fields.",
"fields": {
"companyName": "Company name is required",
"teamSize": "Must be a number"
}
}
Maak ook onderscheid tussen 403 (not allowed), 409 (conflict / verkeerde stap) en 422 (validatie) zodat de frontend correct kan reageren.
Scheid user- en admin-mogelijkheden:
GET /api/admin/onboarding/users/{userId} of overrides) moeten rol-gated en geaudit zijn.Deze grens voorkomt onbedoelde privilege-lekken en maakt het toch mogelijk voor support/ops om gebruikers te helpen.
De taak van de frontend is onboarding soepel te laten aanvoelen, zelfs bij netwerkklachten. Dat betekent voorspelbare routing, betrouwbaar hervatten en duidelijke feedback tijdens het opslaan.
Één URL per stap (bijv. /onboarding/profile, /onboarding/billing) is meestal het makkelijkst te begrijpen. Het ondersteunt browser back/forward, deep linking vanuit e-mails en maakt refreshes veilig.
Een enkele pagina met interne staat kan werken voor zeer korte flows, maar verhoogt het risico bij refreshes, crashes en “kopieer link om verder te gaan”-scenario’s. Als je deze aanpak gebruikt, zorg dan voor sterke persistentie en zorgvuldige history-management.
Sla stapvoltooiing en de meest recente opgeslagen data op de server op, niet alleen in localStorage. Bij paginalaad: haal de huidige onboardingstatus (huidige stap, voltooide stappen en eventuele draftwaarden) op en render vanaf die staat.
Dit maakt mogelijk:
Optimistische UI kan wrijving verminderen, maar heeft randvoorwaarden:
Wanneer een gebruiker terugkomt, dump ze niet op stap één. Geef iets als: “Je bent 60% klaar—doorgaan waar je was?” met twee acties:
/onboarding)Deze kleine touch verkleint uitval en respecteert gebruikers die nog niet alles willen invullen.
Validatie is waar onboarding soepel of frustrerend aanvoelt. Het doel is fouten vroeg te vangen, gebruikers in beweging te houden en toch je systeem te beschermen wanneer data onvolledig of verdacht is.
Gebruik client-side validatie om voor de hand liggende fouten te voorkomen voordat je een netwerkrequest doet. Dit vermindert frictie en maakt elke stap responsiever.
Typische checks: verplichte velden, lengtebeperkingen, basisformaten (e-mail/telefoon) en eenvoudige cross-field regels (wachtwoordconfirmatie). Houd berichten specifiek (“Voer een geldig werk-e-mailadres in”) en plaats ze naast het veld.
Behandel server-side validatie als de bron van waarheid. Zelfs als de UI perfect valideert, kunnen gebruikers het omzeilen.
Servervalidatie moet afdwingen:
Retourneer gestructureerde veldfouten zodat de frontend precies kan aangeven wat er moet worden hersteld.
Sommige validaties hangen af van externe of vertraagde signalen: e-mail-uniqueness, uitnodigingscodes, fraudesignalen of documentverificatie.
Ga hiermee om met expliciete statussen (bijv. pending, verified, rejected) en een duidelijke UI-toestand. Als een check in behandeling is, laat de gebruiker waar mogelijk doorgaan en geef aan wanneer je ze zult informeren of welke stap dan ontgrendeld wordt.
Multi-step onboarding betekent vaak dat gedeeltelijke data normaal is. Bepaal per stap of je wil:
Een praktische aanpak is “altijd draft opslaan, blokkeren alleen bij stapvoltooiing”. Dit ondersteunt hervatten zonder je datakwaliteitsdrempel te verlagen.
Analytics voor multi-step onboarding moet twee vragen beantwoorden: “Waar blijven mensen steken?” en “Welke wijziging zou de voltooiing verbeteren?” Het belangrijkste is een klein, consistent set events te volgen over elke stap en ze vergelijkbaar te houden zelfs als de flow over tijd verandert.
Volg dezelfde kern-events voor elke stap:
step_viewed (gebruiker zag de stap)step_completed (gebruiker submitte en slaagde voor validatie)step_failed (gebruiker probeerde te submitten maar faalde validatie of serverchecks)flow_completed (gebruiker bereikte de eindstatus)Voeg een minimaal, stabiel contextpayload toe aan elk event: user_id, flow_id, flow_version, step_id, step_index en een session_id (zodat je “in één sessie” kunt scheiden van “verspreid over meerdere dagen”). Als je hervatten ondersteunt, voeg dan ook resume=true/false toe aan step_viewed.
Om uitval per stap te meten, vergelijk step_viewed vs. step_completed tellingen voor dezelfde flow_version. Voor tijd per stap: leg timestamps vast en bereken:
step_viewed → step_completedstep_viewed → volgende step_viewed (nuttig als gebruikers stappen overslaan)Houd tijdmetrics gegroepeerd per versie; anders kunnen verbeteringen verborgen raken doordat oude en nieuwe flows worden gemengd.
Als je A/B-test copy of herordening van stappen doet, behandel dat als onderdeel van analytics-identiteit:
experiment_id en variant_id toe aan elk eventstep_id stabiel zelfs als de zichtbare tekst verandertstep_id gelijk en gebruik step_index voor positieBouw een eenvoudige dashboard die voltooiingspercentage, uitval per stap, mediaan tijd per stap en “top mislukte velden” (uit step_failed metadata) toont. Voeg CSV-exports toe zodat teams voortgang in spreadsheets kunnen bekijken en updates kunnen delen zonder directe toegang tot je analytics-tool.
Een multi-step onboarding-systeem heeft uiteindelijk operationele controle nodig: productwijzigingen, support-excepties en veilige experimentatie. Een kleine interne admin-omgeving voorkomt dat engineering de bottleneck wordt.
Begin met een simpele “flow builder” waarmee bevoegde medewerkers onboardingflows en hun stappen kunnen maken en bewerken.
Elke stap moet bewerkbaar zijn met:
Voeg een previewmodus toe die de stap rendert zoals een eindgebruiker die zou zien. Zo vang je verwarrende copy, ontbrekende velden en gebroken vertakkingen voordat echte gebruikers er last van krijgen.
Vermijd het in-place bewerken van een live flow. Publiceer in plaats daarvan versies:
Rollouts moeten configureerbaar zijn per versie:
Dit vermindert risico en geeft schone vergelijkingen bij het meten van voltooiing en uitval.
Support-teams hebben tools nodig om gebruikers te helpen zonder handmatige database-edits:
Elke admin-actie moet worden gelogd: wie wat veranderde, wanneer en before/after waarden. Beperk toegang met rollen (alleen-lezen, editor, publisher, support-override) zodat gevoelige acties — zoals het resetten van voortgang — gecontroleerd en traceerbaar zijn.
Voordat je een multi-step onboardingflow live zet, ga ervan uit dat gebruikers onverwachte paden nemen en dat er iets misgaat halverwege (netwerk, validatie, permissies). Een goede launch-checklist bewijst dat de flow correct is, beschermt gebruikersdata en geeft vroege waarschuwingen wanneer realiteit afwijkt van je plan.
Begin met unittests voor je workflowlogica (staten en transities). Deze tests moeten verifiëren dat elke stap:
Voeg integratietests toe die je API oefenen: stap-payloads opslaan, voortgang hervatten en ongeldig verklaren van transities. Integratietests vangen vaak “werkt lokaal” issues zoals ontbrekende indexen, serialisatiebugs of versiemismatchen tussen frontend en backend.
E2E-tests moeten ten minste de volgende paden dekken:
Houd E2E-scenario’s klein maar betekenisvol — focus op de paden die de meeste gebruikers en de meeste omzet/activatie beïnvloeden.
Pas least privilege toe: onboarding-admins krijgen niet automatisch volledige toegang tot gebruikersrecords en service-accounts mogen alleen de tabellen/endpoints aanraken die ze nodig hebben.
Versleutel waar het telt (tokens, gevoelige identifiers, gereguleerde velden) en beschouw logs als een risico op datalekken. Vermijd het loggen van ruwe formulierpayloads; log in plaats daarvan stap-ID’s, foutcodes en timing. Als je payloads voor debugging moet loggen, redigeer velden consequent.
Instrumenteer onboarding als productfunnel en als API.
Volg fouten per stap, save-latency (p95/p99) en hervat-fouten. Stel alerts in voor plotselinge dalingen in voltooiingspercentage, pieken in validatiefouten op één stap of verhoogde API-foutpercentages na een release. Zo kun je een kapotte stap repareren voordat supporttickets opstapelen.
Als je een stapgebaseerd onboarding-systeem vanaf nul implementeert, gaat de meeste tijd zitten in dezelfde bouwblokken die hierboven zijn beschreven: staprouting, persistente opslag, validaties, voortgangs- en toestandslogica en een admininterface voor versiebeheer en rollouts. Koder.ai kan je helpen deze onderdelen sneller te prototypen en op te leveren door volledige full-stack webapps te genereren vanuit een chatgestuurde specificatie — typisch met een React-frontend, een Go-backend en een PostgreSQL-datamodel dat netjes aansluit op flows, stappen en step responses.
Omdat Koder.ai broncode-export, hosting/deploy en snapshots met rollback ondersteunt, is het ook handig wanneer je onboardingversies veilig wilt itereren (en snel herstellen als een rollout de voltooiing schaadt).
Gebruik een multi-step flow wanneer de setup meer is dan één formulier — vooral als het voorafvoorwaarden bevat (bijv. het aanmaken van een workspace), verificatie (e-mail/telefoon/KYC), configuratie (betalingen/integraties) of vertakkingen op basis van rol/plan/regio.
Als gebruikers context nodig hebben om vragen correct te beantwoorden, vermindert het opsplitsen in stappen fouten en uitval.
Definieer succes als gebruikers die waarde bereiken, niet het afhandelen van schermen. Veelgebruikte metrics:
Meet ook hervattingssucces (gebruikers kunnen weggaan en doorgaan zonder voortgang te verliezen).
Begin met het opsommen van gebruikerstypen (bijv. self-serve nieuwe gebruiker, uitgenodigde gebruiker, door admin aangemaakt account) en definieer voor elk:
Encodeer daarna skip rules zodat elke persona op de juiste volgende stap terechtkomt, niet altijd op stap één.
Schrijf “done” als backend-controleerbare criteria, niet als UI-voltooiing. Bijvoorbeeld:
Zo kan de server betrouwbaar beslissen of onboarding compleet is — zelfs als de UI verandert.
Begin met een grotendeels lineaire backbone en voeg conditionele vertakkingen alleen toe wanneer de ervaring echt anders moet zijn (rol, plan, regio, gebruiksdoel).
Documenteer vertakkingen als expliciete if/then-regels (bijv. “If region = EU → show VAT step”) en houd stapnamen actiegericht (“Bevestig e-mail”, “Nodig teamleden uit”).
Geef de voorkeur aan één URL per stap (bijv. /onboarding/profile) wanneer de flow uit meer dan een paar schermen bestaat. Het ondersteunt refresh-safety, deep linking (uit e-mails) en browser terug/voor.
Gebruik een enkele pagina met interne state alleen voor heel korte flows — en alleen met sterke persistente opslag om refreshes/crashes te overleven.
Behandel de server als bron van waarheid:
Dit maakt refresh-safe, cross-device voortzetting en stabiliteit bij flow-updates mogelijk.
Een praktisch minimaal datamodel is:
Versiebeheer van je flowdefinities voorkomt dat gebruikers in progress stuklopen wanneer je stappen toevoegt of herschikt. Progress moet verwijzen naar een specifiek .
Behandel onboarding als een toestandsmachine met expliciete transities (bijv. start_step, save_draft, submit_step, go_back).
Een stap is alleen completed wanneer:
Een solide baseline API bevat:
GET /api/onboarding (huidige stap + voortgang + drafts)PUT /api/onboarding/steps/{stepKey} met mode: draft|submitPOST /api/onboarding/complete (server verifieert alle vereisten)Voeg toe (bijv. ) om retries/dubbele clicks te weren en retourneer gestructureerde veldfouten (gebruik 403/409/422 zinvol) zodat de UI juist kan reageren.
flow_version_idWanneer eerdere antwoorden veranderen, evalueer afhankelijkheden opnieuw en markeer downstream-stappen als needs_review of zet ze terug naar in_progress.
Idempotency-Key