@onramp-sdk/web 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +88 -0
  2. package/dist/index.d.ts +1 -3
  3. package/dist/index.d.ts.map +1 -1
  4. package/dist/index.js +3 -7
  5. package/dist/index.js.map +1 -1
  6. package/package.json +3 -3
package/README.md ADDED
@@ -0,0 +1,88 @@
1
+ # @onramp-sdk/web
2
+
3
+ OnRamp onboarding funnel analytics for web apps. Track where users drop off during onboarding — works with any JS framework.
4
+
5
+ **[onway.dev](https://onway.dev)**
6
+
7
+ ## Installation
8
+
9
+ ```bash
10
+ npm install @onramp-sdk/web
11
+ # or
12
+ yarn add @onramp-sdk/web
13
+ ```
14
+
15
+ ## Setup
16
+
17
+ ### 1. Initialize
18
+
19
+ Call `OnRamp.init()` once at app start:
20
+
21
+ ```typescript
22
+ import { OnRamp } from '@onramp-sdk/web'
23
+
24
+ OnRamp.init({
25
+ apiKey: 'onr_your_api_key', // from the OnRamp dashboard
26
+ host: 'https://your-ingestion-url', // your ingestion API URL
27
+ appVersion: '1.0.0', // optional — enables version breakdown
28
+ })
29
+ ```
30
+
31
+ ### 2. Track milestones
32
+
33
+ Call `OnRamp.step()` at each meaningful moment in your onboarding flow:
34
+
35
+ ```typescript
36
+ // After account creation
37
+ OnRamp.step('account_created')
38
+
39
+ // After completing setup
40
+ OnRamp.step('profile_completed')
41
+
42
+ // After first meaningful action — attach properties for richer breakdowns
43
+ OnRamp.step('first_action_done', {
44
+ properties: {
45
+ plan: 'free',
46
+ referrer: 'producthunt',
47
+ items_added: 3,
48
+ },
49
+ })
50
+ ```
51
+
52
+ ## API
53
+
54
+ ### `OnRamp.init(config)`
55
+
56
+ | Option | Type | Required | Description |
57
+ |---|---|---|---|
58
+ | `apiKey` | `string` | ✓ | Your app's API key from the OnRamp dashboard |
59
+ | `host` | `string` | | Ingestion API base URL (default: `http://localhost:3001`) |
60
+ | `appVersion` | `string` | | App version string — enables version breakdown in dashboard |
61
+
62
+ ### `OnRamp.step(stepName, options?)`
63
+
64
+ | Option | Type | Description |
65
+ |---|---|---|
66
+ | `stepName` | `string` | Identifier for this milestone — e.g. `'account_created'` |
67
+ | `options.properties` | `Record<string, string \| number \| boolean>` | Custom properties — become breakdown dimensions in the dashboard |
68
+
69
+ ### `OnRamp.newSession()`
70
+
71
+ Force-start a new session (e.g. after logout or page load into a new context).
72
+
73
+ ### `OnRamp.flush()`
74
+
75
+ Flush the event queue immediately. Called automatically on `pagehide` and `visibilitychange`.
76
+
77
+ ## How Funnels Work
78
+
79
+ Funnels are defined in the **OnRamp dashboard**, not in the SDK. You call `OnRamp.step()` with a step name — the dashboard lets you pick which steps belong to which funnel and in what order. No SDK changes needed when you iterate on your funnel structure.
80
+
81
+ ## Framework Notes
82
+
83
+ - **Next.js / SSR**: Call `OnRamp.init()` on the client side only (inside `useEffect` or a client component). The SDK accesses `localStorage` and `window` — it is safe in SSR environments (access is guarded), but events are only tracked in the browser.
84
+ - **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).
85
+
86
+ ## License
87
+
88
+ MIT
package/dist/index.d.ts CHANGED
@@ -1,14 +1,12 @@
1
1
  interface InitConfig {
2
2
  apiKey: string;
3
3
  host?: string;
4
- funnelName?: string;
5
4
  appVersion?: string;
6
5
  }
7
6
  export declare const OnRamp: {
8
7
  init(config: InitConfig): void;
9
8
  step(stepName: string, options?: {
10
- funnelName?: string;
11
- stepIndex?: number;
9
+ /** Custom event properties (e.g. { plan: 'free', source: 'invite' }) */
12
10
  properties?: Record<string, string | number | boolean>;
13
11
  }): void;
14
12
  newSession(): void;
package/dist/index.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAyBA,UAAU,UAAU;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAQD,eAAO,MAAM,MAAM;iBACJ,UAAU,GAAG,IAAI;mBA0BlB,MAAM,YACN;QACR,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAA;KACvD,GACA,IAAI;kBAkBO,IAAI;aAKT,OAAO,CAAC,IAAI,CAAC;CAGvB,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAyBA,UAAU,UAAU;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAOD,eAAO,MAAM,MAAM;iBACJ,UAAU,GAAG,IAAI;mBAuBlB,MAAM,YACN;QACR,wEAAwE;QACxE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAA;KACvD,GACA,IAAI;kBAkBO,IAAI;aAKT,OAAO,CAAC,IAAI,CAAC;CAGvB,CAAA"}
package/dist/index.js CHANGED
@@ -28,11 +28,9 @@ function getOrCreateAnonymousId() {
28
28
  let client = null;
29
29
  let currentSessionId = null;
30
30
  let anonymousId = null;
31
- let defaultFunnelName = 'onboarding';
32
31
  let stepCounter = 0;
33
32
  exports.OnRamp = {
34
33
  init(config) {
35
- defaultFunnelName = config.funnelName ?? 'onboarding';
36
34
  anonymousId = getOrCreateAnonymousId();
37
35
  currentSessionId = uuid();
38
36
  stepCounter = 0;
@@ -45,9 +43,7 @@ exports.OnRamp = {
45
43
  });
46
44
  if (typeof window !== 'undefined') {
47
45
  // pagehide fires on tab close and navigation — last chance to flush
48
- window.addEventListener('pagehide', () => {
49
- client?.flush();
50
- });
46
+ window.addEventListener('pagehide', () => { client?.flush(); });
51
47
  document.addEventListener('visibilitychange', () => {
52
48
  if (document.visibilityState === 'hidden')
53
49
  client?.flush();
@@ -62,9 +58,9 @@ exports.OnRamp = {
62
58
  client.track({
63
59
  sessionId: currentSessionId,
64
60
  anonymousId,
65
- funnelName: options?.funnelName ?? defaultFunnelName,
61
+ funnelName: '',
66
62
  stepName,
67
- stepIndex: options?.stepIndex ?? stepCounter++,
63
+ stepIndex: stepCounter++,
68
64
  osVersion: typeof navigator !== 'undefined' ? navigator.userAgent.slice(0, 32) : null,
69
65
  deviceType: 'desktop',
70
66
  properties: options?.properties ?? null,
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@onramp-sdk/web",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "OnRamp onboarding funnel analytics for web apps — track steps, see where users drop off.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -30,8 +30,8 @@
30
30
  }
31
31
  },
32
32
  "dependencies": {
33
- "@onramp-sdk/core": "0.1.0",
34
- "@onramp-sdk/shared": "0.1.0"
33
+ "@onramp-sdk/core": "0.4.0",
34
+ "@onramp-sdk/shared": "0.2.1"
35
35
  },
36
36
  "devDependencies": {
37
37
  "typescript": "^5.5.0"