@onramp-sdk/web

OnRamp onboarding funnel analytics for web apps. Track where users drop off during onboarding - works with any JS framework.

getonramp.dev

Installation

npm install @onramp-sdk/web
# or
yarn add @onramp-sdk/web

Setup

1. Initialize

Call OnRamp.init() once at app start:

import { OnRamp } from '@onramp-sdk/web'

OnRamp.init({
  apiKey: 'onr_your_api_key',  // from the OnRamp dashboard
  appVersion: '1.0.0',         // optional - enables version breakdown
  autoTrackScrollDepth: true,  // optional - defaults to true
})

The SDK automatically records real scrolls at 25%, 50%, 75%, and 90% of each page. Scroll events power page-depth analytics and engagement-aware bounce rate; they are not treated as funnel milestones.

2. Track milestones

Call OnRamp.step() at each meaningful moment in your onboarding flow:

// After account creation
OnRamp.step('account_created')

// After completing setup
OnRamp.step('profile_completed')

// After first meaningful action - attach properties for richer breakdowns
OnRamp.step('first_action_done', {
  properties: {
    plan: 'free',
    referrer: 'producthunt',
    items_added: 3,
  },
})

API

OnRamp.init(config)

| Option | Type | Required | Description | |---|---|---|---| | apiKey | string | ✓ | Your app's API key from the OnRamp dashboard | | host | string | | Ingestion API base URL (default: https://ingest.getonramp.dev) | | appVersion | string | | App version string - enables version breakdown in dashboard | | autoTrackScrollDepth | boolean | | Record 25/50/75/90% page depth (default true) |

OnRamp.step(stepName, options?)

| Option | Type | Description | |---|---|---| | stepName | string | Identifier for this milestone - e.g. 'account_created' | | options.properties | Record<string, string \| number \| boolean> | Custom properties - become breakdown dimensions in the dashboard |

OnRamp.newSession()

Force-start a new session (e.g. after logout or page load into a new context).

OnRamp.flush()

Flush the event queue immediately. Called automatically on pagehide and visibilitychange.

How Funnels Work

The SDK records milestones. Funnel definitions live in OnRamp and can be created with the dashboard or @onramp-sdk/cli. If you are a coding agent asked to create a funnel, do not stop after adding OnRamp.step() calls.

npx --yes @onramp-sdk/cli@latest whoami
npx --yes @onramp-sdk/cli@latest funnels create --app-id <project-id> --name "Activation" --steps '[{"step_name":"account_created","display_label":"Account created"},{"step_name":"first_action_done","display_label":"First action"}]'
npx --yes @onramp-sdk/cli@latest funnels get Activation --app-id <project-id>

If the CLI is not connected, run npx --yes @onramp-sdk/cli@latest login and approve the browser authorization. The funnel immediately includes matching historical events, so you can reorder steps later without changing SDK calls. See the CLI guide.

Framework Notes

• Next.js / SSR: Call OnRamp.init() on the client side only (inside useEffect or a client component). The SDK accesses window only; it is safe in SSR environments (access is guarded), but events are only tracked in the browser.
• SPA routing: Call OnRamp.newSession() if you want a new session to start on a specific navigation event (e.g. user logs out and logs back in).

License

MIT