@onramp-sdk/react
v0.9.2
Published
OnRamp Analytics SDK for React & Next.js - track onboarding steps and see where users drop off.
Downloads
387
Maintainers
thebugeaterReadme
@onramp-sdk/react
OnRamp onboarding funnel analytics for React & Next.js. Track where users drop off during onboarding, with hooks and a provider that fit naturally into a React tree.
Installation
npm install @onramp-sdk/react
# or
yarn add @onramp-sdk/reactreact >= 18 is a peer dependency. next >= 13 is an optional peer - only needed for the route tracker in @onramp-sdk/react/next.
Setup
1. Wrap your app in the provider
<OnRampProvider> initializes the SDK once on the client. It's SSR-safe - it no-ops on the server and starts tracking in the browser.
Next.js App Router (app/layout.tsx):
import { OnRampProvider } from '@onramp-sdk/react'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html>
<body>
<OnRampProvider apiKey="onr_your_api_key" appVersion="1.0.0">
{children}
</OnRampProvider>
</body>
</html>
)
}<OnRampProvider> is a client component, so it only opts its own subtree into client rendering - your layout and pages stay server components.
Real scroll depth is tracked automatically at 25%, 50%, 75%, and 90%. These events appear as page engagement in OnRamp and never become funnel milestones.
Plain React (e.g. Vite, CRA): wrap your root the same way.
2. Track milestones
From any client component below the provider:
'use client'
import { useOnRamp } from '@onramp-sdk/react'
export function PlanPicker() {
const { step } = useOnRamp()
return (
<button onClick={() => step('plan_selected', { properties: { plan: 'pro' } })}>
Choose Pro
</button>
)
}Or mark a step the moment a screen renders with useTrackStep:
'use client'
import { useTrackStep } from '@onramp-sdk/react'
export function ProfileSetup() {
useTrackStep('profile_setup_viewed')
return <>...</>
}3. (Next.js) Auto-track route changes - optional
Mount <OnRampRouteTracker /> once inside the provider to record every App Router navigation. These are tagged as navigation events and kept out of your defined funnels - they power the session timeline, not conversion steps.
import { OnRampProvider } from '@onramp-sdk/react'
import { OnRampRouteTracker } from '@onramp-sdk/react/next'
<OnRampProvider apiKey="onr_your_api_key">
<OnRampRouteTracker />
{children}
</OnRampProvider>4. (Next.js) Report AI/search crawlers - optional
OnRampProvider only sees traffic that runs your page's JS. Crawlers like GPTBot, ClaudeBot, PerplexityBot, and Googlebot fetch raw HTML and never execute it, so they never appear in OnRamp no matter how much they crawl your site. withOnRampCrawlerTracking reports them from middleware instead, where the request is seen before any JS runs:
// middleware.ts
import { withOnRampCrawlerTracking } from '@onramp-sdk/react/next'
export default withOnRampCrawlerTracking({ apiKey: 'onr_your_api_key' })
export const config = {
matcher: '/((?!_next/static|_next/image|favicon.ico).*)',
}Pass your existing middleware as the second argument to compose instead of replace it:
export default withOnRampCrawlerTracking({ apiKey: 'onr_your_api_key' }, yourExistingMiddleware)It only fires when the User-Agent matches a known crawler, via event.waitUntil so it never delays the response - human traffic is untouched. Non-Next.js servers can call reportCrawlerVisit / isKnownCrawler from @onramp-sdk/core directly instead.
API
<OnRampProvider>
| Prop | 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 the version breakdown |
| framework | string | | Runtime label on each event (default 'react'; e.g. 'nextjs') |
| sessionTimeoutMs | number | | Idle window before a new session starts (default 30 min) |
| autoTrackScrollDepth | boolean | | Record 25/50/75/90% page depth (default true) |
| autoTrackOutboundLinks | boolean | | Record clicks on links leaving the current site (default true) |
useOnRamp()
Returns { step, newSession, flush }.
step(stepName, { properties? })- track a milestone.newSession()- force-start a new session (e.g. after logout).flush()- flush queued events immediately (also runs automatically on tab hide/close).
useTrackStep(stepName, options?)
Fires a step on mount (and again if stepName changes).
| Option | Type | Description |
|---|---|---|
| properties | Record<string, string \| number \| boolean> | Custom properties for this step |
| enabled | boolean | Skip tracking while false (e.g. gate on a ready state) |
Imperative OnRamp
The same singleton is exported directly for use outside the React tree (e.g. event handlers in non-component modules): import { OnRamp } from '@onramp-sdk/react'. Call OnRamp.init(config) yourself if you don't use the provider.
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 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.
License
MIT