Web / JavaScript SDK

Use OnRamp in any non-React web app - Vue, Svelte, Angular, or plain JavaScript.

Building with React or Next.js?

Use @onramp-sdk/react instead. It exports OnRampProvider, useOnRamp, and useTrackStep. This page covers the framework-agnostic @onramp-sdk/web singleton only.

Installation

bash

npm install @onramp-sdk/web@0.7.4

Setup

Call OnRamp.init() once when your app boots. It is a no-op on the server (SSR-safe).

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

OnRamp.init({
  apiKey: 'onr_xxxxxxxxxxxx',
  appVersion: '2.4.1',
})

Your API key is on the Settings page of each app in the dashboard.

`OnRamp.init()` options

Option	Type	Required	Default	Description
`apiKey`	`string`	Yes	-	Your API key from Settings
`appVersion`	`string`	No	-	Version string, e.g. `"2.4.1"` - shows in the version breakdown
`sessionTimeoutMs`	`number`	No	`1_800_000`	Idle time (ms) before a new session starts (default 30 min)
`autoTrackScrollDepth`	`boolean`	No	`true`	Record page depth at 25%, 50%, 75%, and 90%
`host`	`string`	No	`https://ingest.getonramp.dev`	Override ingestion endpoint (for self-hosting)

Scroll depth

OnRamp automatically records real scrolls at 25%, 50%, 75%, and 90% of each page. Scroll-depth events power page engagement and bounce-rate reporting, but are kept out of funnels and milestone counts. Set autoTrackScrollDepth: false in OnRamp.init() to disable collection.

Tracking steps

`OnRamp.step(name, options?)`

Records a funnel milestone. Safe to call anywhere - events are batched and sent automatically.

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

// Basic
OnRamp.step('account_created')

// With custom properties
OnRamp.step('subscription_started', {
  properties: {
    plan: 'pro',
    billing_period: 'annual',
  },
})

Options

Option	Type	Description
`properties`	`Record<string, string \| number \| boolean>`	Custom key-value data attached to the event

Property values must be primitives - strings, numbers, or booleans. Nested objects are not supported.

Identifying users

`OnRamp.identify(traits)`

Associates the current anonymous user with known identity traits. Call once after sign-in so integrations (Stripe, RevenueCat) can match the user to external records.

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

// After the user signs in
OnRamp.identify({ email: user.email, userId: user.id })

identify() is entirely optional. Omit it if you have no integrations connected, or if your users prefer not to share identity traits. All funnel and retention features work without it.

Session management

`OnRamp.newSession()`

Force-starts a new session - useful after logout so the next user gets a clean session.

async function handleLogout() {
  await signOut()
  OnRamp.newSession()
}

`OnRamp.getIds()`

Returns per-page client placeholders. In anonymous web mode these are replaced by the ingestion service and must not be stored or used for server-side correlation. Use identify() and your own authenticated account ID for server-side events that need a durable association.

const { anonymousId, sessionId } = OnRamp.getIds()

Storage

The web SDK writes no analytics ID or session state to cookies, localStorage, or sessionStorage. The ingestion service derives a daily pseudonymous ID from the request and keeps a server-side session for up to 30 minutes. Calling identify() sends personal traits and is the app developer's responsibility to disclose and govern.

TypeScript

The SDK ships full TypeScript types. No @types/ package needed.

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

function trackPayment(amountCents: number): void {
  OnRamp.step('payment_completed', {
    properties: { amount_cents: amountCents },
  })
}