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.0

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)
`anonymousIdMaxAgeMs`	`number`	No	`31_536_000_000`	How long before the anonymous ID rotates (default 365 days)
`host`	`string`	No	-	Override ingestion endpoint (for self-hosting)

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 the current anonymousId and sessionId. Pass both to your server when firing backend events so they can be tied to this user's session. Call at the moment of the action - session IDs rotate after inactivity.

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

Storage

Anonymous IDs are stored in localStorage under @onramp/anonymous_id. Session state is stored under @onramp/session. No HTTP cookies are set.

By default the anonymous ID rotates after 365 days:

OnRamp.init({
  apiKey: 'onr_xxxxxxxxxxxx',
  anonymousIdMaxAgeMs: 180 * 24 * 60 * 60 * 1000, // 180 days
})

No HTTP cookies, but consent may still apply

OnRamp uses localStorage, not HTTP cookies, so browser-level cookie blocking won't affect it. However, the EU ePrivacy Directive covers all client-side storage for analytics - EU/UK developers should include OnRamp in their consent flow and initialise the SDK only after consent is granted. See the Privacy & data page for the full breakdown.

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 },
  })
}