Documentation

SmartOnboard Docs

Everything you need to set up, integrate, and get the most out of SmartOnboard.

📖 Table of Contents

How SmartOnboard Works Getting Started (Setup)Event Tracking & API Funnel Analytics Health Score AI Suggestions Onboarding Flows ROI Dashboard Onboarding Audit Tool Pricing & Plan Limits

How SmartOnboard Works

SmartOnboard is an onboarding analytics and optimization platform for SaaS applications. It helps you understand where users drop off, provides AI-powered improvement suggestions, and lets you automatically deploy dynamic onboarding flows — all from one dashboard.

System Architecture

Your App (with tracking snippet)

Users interact with your app. The snippet captures events like page views, clicks, form submissions, and onboarding step completions.

POST /api/events

Events are sent via HTTP POST to our API endpoint, authenticated by your unique API key. Each event includes user ID, session ID, event name, page URL, and device type.

Supabase Events Table

Events are stored in the events table with full context: org_id, event_name, user_id, session_id, page_url, referrer, device_type, properties (JSON), and timestamp.

Dashboard Analytics

Server actions query the events table to compute Funnel Analytics, Health Score, AI Suggestions, and ROI — all in real-time from your actual user data.

Getting Started

Create an Account & Organization

Sign up at /signup using email, GitHub, or Google OAuth. When you create an account, an organization is automatically created for you. Your organization is the container for all your flows, events, and settings.

💡 Tip: You can find your Organization ID in Dashboard → Settings → Organization.

Get Your API Key

Go to Dashboard → Settings → API Keys. Your publishable API key (starts with pk_live_) is shown there. You can copy it or rotate it anytime.

This key identifies your organization and is safe to use in client-side code.

Install the Tracking Snippet

Add this script to the <head> of every page in your application:

<script
  src="https://cdn.smartonboard.io/sb.js"
  data-key="YOUR_API_KEY"
></script>

The snippet automatically captures page views and session data. For custom events (like step completions), you'll use the JavaScript API.

Send Custom Events

Track specific onboarding steps by sending events from your app. These events power every dashboard feature:

// Track onboarding steps
SmartOnboard.track("signup_completed", {
  userId: "user_123",
  properties: { plan: "free" }
});

SmartOnboard.track("profile_setup", {
  userId: "user_123",
  properties: { hasAvatar: true }
});

SmartOnboard.track("first_flow_deployed", {
  userId: "user_123",
  properties: { flowType: "onboarding" }
});

Each event becomes a funnel step. The order and count of users at each step creates your funnel visualization.

View Your Dashboard

Once events start flowing in, your dashboard will populate automatically. Head to /dashboard to see your Funnel, Health Score, AI Suggestions, and ROI metrics — all computed from your real user data.

Event Tracking & API

Events are the foundation of SmartOnboard. Every metric, score, and suggestion is computed from the events your app sends. Here's the technical details:

⏱️

30-Day Raw Event Retention

Raw events are stored for 30 days. Each night, daily summaries (unique users, total events) are automatically archived to a permanent daily_stats table before raw events are purged, so your historical trend charts are never lost.

REST API Endpoint

POST /api/events

Headers

Content-Type: application/json
X-API-Key: pk_live_your_api_key_here

Request Body

{
  "events": [
    {
      "event": "signup_completed",
      "userId": "user_123",
      "sessionId": "sess_abc",
      "url": "/signup",
      "referrer": "https://google.com",
      "deviceType": "desktop",
      "properties": {
        "plan": "free",
        "source": "organic"
      },
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ]
}

Response

{ "success": true, "count": 1 }

Event Fields

Field	Type	Required	Description
`event`	string	✅	Name of the event (e.g. 'signup_completed')
`userId`	string	✅	Unique identifier for the user
`sessionId`	string	Optional	Session identifier for grouping
`url`	string	Optional	Page URL where event occurred
`referrer`	string	Optional	Referring URL
`deviceType`	string	Optional	'desktop' or 'mobile'
`properties`	object	Optional	Additional metadata as JSON
`timestamp`	ISO 8601	Optional	Defaults to server time

Funnel Analytics

What It Does

The funnel shows you exactly where users drop off in your onboarding flow. Each event name becomes a funnel step, sorted by the number of unique visitors (most → fewest).

How It's Computed

1. Groups all events by event_name
2. Counts distinct users at each step (not total events)
3. Sorts steps by visitor count (highest first) to form the funnel
4. Computes drop-off rate: (current - next) / current × 100
5. Also tracks avg time, desktop vs mobile split per step

🔒 Plan gating: Free plan users see the funnel bars but the Step Details panel (time, device split) is locked behind Starter+.

Health Score

What It Does

A single 0–100 score that summarizes how effective your onboarding is. Updated in real-time based on your funnel data.

Scoring Formula

The score is calculated from 4 weighted factors:

Completion Rate40%

What % of users who start onboarding finish it

Worst Drop-off25%

Penalized if any single step loses >40% of users

Step Count15%

Too many steps (>7) reduces the score

Mobile Ratio20%

Bonus if mobile experience is optimized (>30% mobile users)

Score Ranges

80–100: Excellent60–79: Good40–59: Needs Work0–39: Critical

🔒 Plan gating: Free plan shows the overall score. Score Breakdown and 30-Day Trend charts require Starter+.

AI Suggestions

What It Does

Analyzes your funnel data and automatically generates actionable improvement suggestions. No manual analysis needed.

How Suggestions Are Generated

1. Identifies the worst drop-off step — the step that loses the most users
2. Checks the mobile vs desktop ratio — flags if mobile users are underserved
3. Analyzes average completion times — flags steps that take too long
4. Generates context-specific tips with priority levels (high/medium/low) and estimated impact

Example Suggestions

[High] "Add a progress indicator to Step 3 — 45% of users drop off here"

[Medium] "Mobile users complete at 60% the rate of desktop. Consider simplifying the mobile onboarding flow."

[Low] "Consider adding a tooltip to explain the 'Import Data' feature — users hesitate here."

🔒 Plan gating: AI Suggestions require the Growth plan ($149/mo) or above.

Onboarding Flows & Product Tours

Complete Guide to Flow Engine

SmartOnboard Flows allow you to build and deploy interactive product tours without writing code. Use tooltips, modals, and overlays to guide users through your complex features, reduce support tickets, and increase feature adoption instantly.

Power Features

AI-Driven Flow Generation
Visual Element Picker (No DevTools!)
Real-time "Preview on Demo"
Advanced URL & Event Targeting

How it works (The SDK)

Our sb.js SDK runs in the background. It fetches active flows matching the current page URL, checks if the user has already seen them, and renders them using a lightweight overlay engine. It automatically tracks every step completion for your analytics.

Step 1: Create & Generate with AI

Stuck on what to say? Click the "Generate with AI" button on the Flows dashboard. Provide a simple prompt like "Create a 3-step tour for a new user setting up their first dashboard". SmartOnboard will use GPT-4o to design a logical sequence of tooltips, write the copy, and even suggest CSS selectors.

Step 2: The Visual Element Picker

The most difficult part of product tours is finding the right CSS selectors. We fixed that.

🎯

Visual Selection Mode

Open your Flow in the editor and click "Preview on Demo". On the demo page, toggle the **🎯 Pick Element** button. Hover any button or text area — we'll highlight it and show you the selector instantly.

✓

Click-to-Copy

Found the right element? Just click it. The exact CSS selector is copied to your clipboard. Switch back to the Flow Editor and paste it. No "Inspect Element" required.

Step 3: Targeting & Trigger Logic

Control exactly when and where your flow appears using the **Targeting** tab in the Flow Editor.

Trigger Modes

First Visit: Shows immediately the first time a user lands on your app.
URL Match: Shows only when the user's URL matches a specific pattern (e.g. /dashboard/*).
Manual: Trigger the flow programmatically via SmartOnboard.startFlow("flow_id").

Completion Persistence

SmartOnboard automatically tracks which users have completed which flows. A user will **never** see the same flow twice unless you manually reset their progress in the dashboard or they use a different UserID.

Step 4: Flow Analytics & Optimization

Every flow has a dedicated **Analytics** tab showing a specialized funnel of its steps.

Metric	Definition
Flow Started	Unique users who saw the first step of the flow.
Step Completion	Retention rate between Step 1, Step 2, etc. Identify exactly where users quit.
Completion Rate	The % of users who reached the final 'Finish' button.

Tooltips

Guided Interaction

Point directly to buttons, menus, or inputs. Highly effective for teaching specific UI actions.

Modals

Broad Context

Centered overlays for welcome messages, new feature announcements, or video embeds.

Checklists

Self-Paced Setup

Persistent progress tracking that encourages users to finish their essential setup tasks.

💡 Pro Tip: Use the "Sandbox Mode" to test your flows safely. When active, it bypasses completion checks so you can view your tour as many times as you like while building.

ROI Dashboard

What It Does

Translates your onboarding improvements into dollar values. Shows how many users you've saved from churning and how much revenue you've recovered.

How ROI Is Calculated

Users Saved

Users who completed onboarding because of your flows

Calculated from flow_analytics completion rates vs baseline

Revenue Recovered

Users Saved × Your ARPU (Average Revenue Per User)

ARPU is set in Dashboard → Settings → Organization

Activation Rate Change

Completion rate improvement over time

Compares current flow performance to initial baseline

🔒 Plan gating: ROI Dashboard requires the Starter plan ($49/mo) or above. Free plan users see a lock screen with upgrade CTA.

Onboarding Audit Tool

What It Does

Enter any app URL and get an instant audit score with specific findings about their onboarding experience. Great for competitor analysis or evaluating your own app before integrating SmartOnboard.

How It Works

1. Enter a URL at /audit
2. The system generates a deterministic audit based on the URL
3. Results include a score (0–100), category ratings (First Impression, Guidance, Progress Tracking, etc.), and specific findings
4. Each finding has a severity level and actionable recommendation

✅ The Audit Tool is available on all plans, including Free.

Pricing & Plan Limits

Feature	Free	Starter $49/mo	Growth $149/mo	Scale $399/mo	Enterprise
MAU Limit	100	1,000	4,000	10,000	Unlimited
Flows	1	3	∞	∞	∞
Funnel (basic)	✅	✅	✅	✅	✅
Step Details	🔒	✅	✅	✅	✅
Health Score	Basic	Full	Full	Full	Full
AI Suggestions	🔒	✅	✅	✅	✅
ROI Dashboard	🔒	✅	✅	✅	✅
Audit Tool	✅	✅	✅	✅	✅
Advanced Analytics	🔒	🔒	🔒	✅	✅

Plan is stored in organizations.subscription_status. Change it in the database to update a user's access level.

API Reference

Deep dive into REST endpoints, authentication, and event schemas.

Try the Audit Tool

Audit any app's onboarding experience instantly — no account needed.

Still have questions?

Our support team is here to help you get the most out of SmartOnboard. We usually respond within a few hours.

Contact Support