Core concepts

Understanding these four building blocks will make every other part of OnRamp click into place.

Events

Everything in OnRamp is driven by events. Every time your app calls OnRamp.step(), it sends one event to OnRamp's servers. An event contains:

Field	What it is
`app_key`	Which app sent it
`step_name`	The milestone name you passed, e.g. `account_created`
`event_type`	Always `step_entered` for `step()` calls; `screen_view` for auto-tracked navigation
`session_id`	Groups events from the same continuous session
`anonymous_id`	Identifies the same device/user across sessions
`properties`	Any custom key-value data you attached
`server_ts`	Server-side timestamp (used for all analytics to prevent clock skew)

Events are immutable once stored. There is no concept of updating or deleting individual events.

Anonymous IDs

OnRamp identifies users with an anonymous ID - a random string generated on first launch and persisted in localStorage (web) or AsyncStorage (React Native). No PII is ever sent by default.

anon_9kxm2p3q7r

The anonymous ID persists across:

App restarts
App updates
Moving between screens

It resets when:

The user explicitly calls OnRamp.newSession() (e.g. on logout)
The user clears app data / uninstalls

Sessions

A session is a continuous period of app use. OnRamp starts a new session when:

The app comes to the foreground after being in the background for more than 30 minutes
OnRamp.newSession() is called explicitly

Within a session, all events share the same session_id. The session timeline in the dashboard shows every event in chronological order within a session, making it easy to see exactly what a user did.

Sessions are stored and queryable even after the user churns - there is no expiry on session data.

Steps & funnels

A step is a named milestone in your product. You define what steps exist - OnRamp has no opinion on naming. By convention, steps use snake_case.

A funnel is an ordered sequence of steps you define in the dashboard. OnRamp counts how many unique users reached each step in the funnel, from first to last, allowing you to calculate:

Conversion rate - percentage of users who reach the final step
Drop-off - which step loses the most users, and by how much
Step-by-step funnel - visualised as a ribbon chart showing volume at each step

A user is counted in a step as soon as they fire that step event, regardless of order within the session. Funnels are not session-scoped by default - a user who completed step 1 on day 1 and step 2 on day 3 is still counted as converted.

Properties

Any call to OnRamp.step() can include a properties object with arbitrary key-value pairs:

OnRamp.step('subscription_started', {
  properties: {
    plan: 'pro',
    billing_period: 'monthly',
    price_usd: 9.99,
  },
})

Properties are stored as JSON and queryable from the dashboard. Numeric properties can be added to funnel trend charts as custom metrics (sum or average over time).

Avoid PII in properties

Do not put email addresses, names, phone numbers, or other personal data in properties. Use opaque identifiers like user IDs if you need to correlate events with users in your own system.

Navigation events

OnRamp automatically tracks screen navigation when you use the built-in navigation adapter. These events use event_type: screen_view and appear in session timelines but are not counted in funnel step conversion.

Auto-tracked events are never used to inflate your event usage count against plan limits.