{"_id":"@analyse.net/sdk","_rev":"2-3d9de516870d70c7c9c6ff38afd102cc","name":"@analyse.net/sdk","dist-tags":{"latest":"1.0.0"},"versions":{"0.1.0":{"name":"@analyse.net/sdk","version":"0.1.0","keywords":["analytics","tracking","sdk","web-analytics","analyse"],"license":"MIT","_id":"@analyse.net/sdk@0.1.0","maintainers":[{"name":"vertcode","email":"wesley@vertcodedevelopment.com"}],"dist":{"shasum":"561fd7850a270cb44f3999a0e05bc98c60c24695","tarball":"https://registry.npmjs.org/@analyse.net/sdk/-/sdk-0.1.0.tgz","fileCount":23,"integrity":"sha512-A/weqq+rMU5g72OwVrHhRg+fN6Fjdr+hwUa1SpafpxDKctfwTFKFQ5Il2FZg3IxJ9An7L9Q+9hkanDgFVwIx8A==","signatures":[{"sig":"MEQCIHpNNgXgkmL+7ZEwDdMBl/BawXd6GDfaPlO9Tj/nh93dAiBECpNmqEvy6UU3RgilJs1pA4pBF5WYMp2qHDvPBp8uvg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":379066},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","unpkg":"./dist/index.global.js","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./events":{"types":"./dist/events.d.ts","import":"./dist/events.js","require":"./dist/events.cjs"},"./server":{"types":"./dist/server.d.ts","import":"./dist/server.js","require":"./dist/server.cjs"}},"gitHead":"04cc2e3c6101076c4d2b583753dab7a3718bf98b","scripts":{"dev":"tsup --watch","test":"pnpm test:events && pnpm test:content","build":"tsup","typecheck":"tsc --noEmit","test:events":"tsx src/events/normalize.test.ts","test:content":"tsx src/content-touchpoints.test.ts"},"_npmUser":{"name":"vertcode","email":"wesley@vertcodedevelopment.com"},"jsdelivr":"./dist/index.global.js","_npmVersion":"10.8.2","description":"Analyse web analytics browser SDK","directories":{},"sideEffects":false,"_nodeVersion":"20.19.4","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","tsup":"^8.5.0","typescript":"^6.0.3","@types/node":"^25.9.4"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.0_1783014266279_0.9860475003232354","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@analyse.net/sdk","publishConfig":{"access":"public"},"version":"1.0.0","description":"Analyse web analytics browser SDK","repository":{"type":"git","url":"git+https://github.com/track/web.analyse.net.git","directory":"packages/tracker"},"license":"MIT","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","unpkg":"./dist/index.global.js","jsdelivr":"./dist/index.global.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./server":{"types":"./dist/server.d.ts","import":"./dist/server.js","require":"./dist/server.cjs"},"./events":{"types":"./dist/events.d.ts","import":"./dist/events.js","require":"./dist/events.cjs"}},"sideEffects":false,"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","test:events":"tsx src/events/normalize.test.ts","test:content":"tsx src/content-touchpoints.test.ts","test:campaign":"tsx src/campaign-touchpoints.test.ts","test":"pnpm test:events && pnpm test:content && pnpm test:campaign"},"keywords":["analytics","tracking","sdk","web-analytics","analyse"],"devDependencies":{"@types/node":"^25.9.4","tsup":"^8.5.0","tsx":"^4.21.0","typescript":"^6.0.3"},"gitHead":"b1d9c902e38c92155f71bf4494c2dff50ac308ba","_id":"@analyse.net/sdk@1.0.0","bugs":{"url":"https://github.com/track/web.analyse.net/issues"},"homepage":"https://github.com/track/web.analyse.net#readme","_nodeVersion":"22.23.1","_npmVersion":"11.18.0","dist":{"integrity":"sha512-x9RRmyuzQiCSEr85uXEIm76SmF/O/L8thXGD9MOa5WjS3IXvtzQMw4kC9ZNtpzL0yPTJT7WmVTjZ4wtB9yxB6g==","shasum":"d55fd43c80653e4317592a37ef5481e390482550","tarball":"https://registry.npmjs.org/@analyse.net/sdk/-/sdk-1.0.0.tgz","fileCount":23,"unpackedSize":444359,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDnhQk5kKwPGeOUSmowr0iWxbzgpKnOdWjazc4IduUD+gIhANN+yt2USwUmUKX0p2ElZulR5/8XmUj6ROMlJyUbZTSZ"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:c38be7f1-0548-42ab-8007-3051fe50a258"}},"directories":{},"maintainers":[{"name":"vertcode","email":"wesley@vertcodedevelopment.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_1.0.0_1783245493199_0.7168317221824603"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-02T17:44:26.063Z","modified":"2026-07-05T09:58:13.526Z","0.1.0":"2026-07-02T17:44:26.426Z","1.0.0":"2026-07-05T09:58:13.330Z"},"license":"MIT","keywords":["analytics","tracking","sdk","web-analytics","analyse"],"description":"Analyse web analytics browser SDK","maintainers":[{"name":"vertcode","email":"wesley@vertcodedevelopment.com"}],"readme":"# @analyse.net/sdk\n\nThe official [Analyse](https://analyse.net) web analytics browser SDK. Lightweight, dependency-free, and privacy-friendly. Collects pageviews, session, and engagement signals (time on page, scroll depth) and batches them to the Analyse ingest endpoint.\n\n## Install\n\n### Script tag (zero-code)\n\n```html\n<script\n  src=\"https://cdn.jsdelivr.net/npm/@analyse.net/sdk/dist/index.global.js\"\n  data-public-key=\"pk_live_your_key\"\n  defer\n></script>\n```\n\nThat's it — pageviews and page-leave signals are tracked automatically.\n\nOptional data attributes:\n\n- `data-host` — override the ingest host (defaults to the hosted Analyse ingest).\n- `data-auto-pageviews=\"false\"` — disable automatic pageview tracking.\n- `data-auto-page-leave=\"false\"` — disable automatic `page_leave` tracking.\n\nScript-tag users also get standard lifecycle helpers on the global `Analyse` object (e.g. `Analyse.checkoutStarted(...)`).\n\n### npm\n\n```bash\nnpm install @analyse.net/sdk\n```\n\n```ts\nimport { init, identify, contentViewed, signedUp } from \"@analyse.net/sdk\";\n\ninit({ publicKey: \"pk_live_your_key\" });\n\ncontentViewed({\n  content_id: \"post_abc123\",\n  content_type: \"blog_post\",\n  title: \"How to track attribution\",\n});\n\nidentify(\"user_123\");\nsignedUp({ method: \"email\" });\n```\n\n## Browser API\n\n| Function | Description |\n| --- | --- |\n| `init(config)` | Initialize the client. Safe to call once. |\n| `track(name, properties?)` | Record a custom event. |\n| `identify(userId, traits?)` | Associate the device with a known user. |\n| `page()` | Manually send a `pageview`. |\n| `reset()` | Clear identity/session (e.g. on logout) and flush. |\n\n## Standard lifecycle events\n\nTyped helpers enforce consistent event names and property shapes across customers. Import from `@analyse.net/sdk` (browser) or `@analyse.net/sdk/events` (browser + server helpers).\n\n| Event | Browser helper | Server helper |\n| --- | --- | --- |\n| `content_viewed` | `contentViewed()` | `captureContentViewed()` |\n| `signup_completed` | `signedUp()` | `captureSignedUp()` |\n| `checkout_started` | `checkoutStarted()` | `captureCheckoutStarted()` |\n| `checkout_cancelled` | `checkoutCancelled()` | `captureCheckoutCancelled()` |\n| `checkout_finished` | `checkoutFinished()` | `captureCheckoutFinished()` |\n| `trial_started` | `trialStarted()` | `captureTrialStarted()` |\n| `trial_ended` | `trialEnded()` | `captureTrialEnded()` |\n| `subscription_cancelled` | `subscriptionCancelled()` | `captureSubscriptionCancelled()` |\n\n### Checkout properties\n\nAll `checkout_*` events share a base shape with a required `payment_type`:\n\n- `\"one_time\"` — single charge (no `billing_interval`)\n- `\"subscription\"` — requires `billing_interval`: `\"month\"`, `\"year\"`, or `\"week\"`\n\nCommon optional fields: `checkout_id`, `amount` (minor units / cents), `currency` (ISO 4217), `product_id`, `plan`, `items_count`, `coupon`.\n\nUse the same `checkout_id` across `checkout_started`, `checkout_cancelled`, and `checkout_finished` so funnels correlate correctly.\n\n### Example: checkout funnel\n\n```ts\nimport { init, identify, checkoutStarted, checkoutCancelled, checkoutFinished } from \"@analyse.net/sdk\";\n\ninit({ publicKey: \"pk_live_your_key\" });\n\nconst checkoutId = crypto.randomUUID();\n\ncheckoutStarted({\n  checkout_id: checkoutId,\n  payment_type: \"subscription\",\n  plan: \"pro\",\n  billing_interval: \"month\",\n  amount: 4900,\n  currency: \"USD\",\n});\n\n// On abandon:\ncheckoutCancelled({\n  checkout_id: checkoutId,\n  payment_type: \"subscription\",\n  billing_interval: \"month\",\n  reason: \"user_abandoned\",\n  step: \"payment\",\n});\n\n// On success (browser — see trust model below):\ncheckoutFinished({\n  checkout_id: checkoutId,\n  payment_type: \"subscription\",\n  billing_interval: \"month\",\n  amount: 4900,\n  currency: \"USD\",\n  plan: \"pro\",\n  subscription_id: \"sub_123\",\n});\n```\n\n### Trust model for `checkout_finished`\n\n- **Browser** — fine for prototyping and client-only apps.\n- **Server (preferred)** — capture from Stripe webhooks or billing jobs so revenue data cannot be spoofed.\n\n```ts\nimport { createServerClient, captureCheckoutFinished } from \"@analyse.net/sdk/server\";\n\nconst analyse = createServerClient({ publicKey: process.env.ANALYSE_KEY! });\n\ncaptureCheckoutFinished(analyse, {\n  personId: \"user_123\",\n  properties: {\n    checkout_id: checkoutId,\n    payment_type: \"subscription\",\n    billing_interval: \"month\",\n    amount: 4900,\n    currency: \"USD\",\n    plan: \"pro\",\n    subscription_id: \"sub_123\",\n  },\n});\n\nawait analyse.flush();\n```\n\nPair lifecycle events with `identify()` after signup or login — do not put PII (email, name) in event properties.\n\n### Content attribution (blog → signup)\n\nCall `contentViewed()` on blog or doc pages with a stable `content_id` from your CMS or knowledge base (not just the URL slug). The SDK stores first-party touchpoints in `localStorage` and attaches first-touch / last-touch metadata to `signedUp()` automatically:\n\n| Property (on `signup_completed`) | Description |\n| --- | --- |\n| `first_content_id` | First content piece viewed on this device |\n| `last_content_id` | Most recently viewed content before signup |\n| `content_touchpoint_count` | Distinct content pieces viewed |\n\nCross-session stitching still uses the anonymous device id plus `identify()` — content attribution adds the *which post* layer on top.\n\n```ts\nimport { init, contentViewed, identify, signedUp } from \"@analyse.net/sdk\";\n\ninit({ publicKey: \"pk_live_your_key\" });\n\n// On your blog post template:\ncontentViewed({\n  content_id: \"kb_page_abc123\",\n  content_type: \"blog_post\",\n  title: \"How we handle attribution\",\n});\n\n// Days later, on signup:\nidentify(user.id);\nsignedUp({ method: \"email\" }); // includes first/last content metadata\n```\n\nUse `getContentAttribution()` if you need the same metadata on custom conversion events.\n\n## Server-side (`@analyse.net/sdk/server`)\n\nFor trusted, backend-generated events (Stripe webhooks, API-side conversions). Runs in Node 18+ — all identity and context are supplied explicitly; there is no automatic tracking. Buffer events and `flush()` before the handler returns.\n\n| Method | Description |\n| --- | --- |\n| `createServerClient(config)` | Create a server client (`publicKey`, `host?`, `maxBatchSize?`). |\n| `capture(input)` | Buffer an event. Requires `personId` or `anonymousId`. |\n| `captureSignedUp`, `captureCheckoutStarted`, … | Typed standard lifecycle captures. |\n| `identify(personId, { anonymousId?, traits? })` | Record an identity association. |\n| `flush()` | Send buffered events. Rejects on non-2xx (batch is re-buffered for retry). |\n| `shutdown()` | Alias for `flush()`; call before a process exits. |\n\nSet `maxBatchSize: 1` to send every event immediately.\n\n### Config\n\n```ts\ntype AnalyseConfig = {\n  publicKey: string;        // required\n  host?: string;            // ingest base URL, no trailing slash\n  autoPageviews?: boolean;  // default true (incl. SPA route changes)\n  autoPageLeave?: boolean;  // default true (time_on_page + scroll_depth)\n  flushIntervalMs?: number; // default 5000\n  maxBatchSize?: number;    // default 20\n};\n```\n\n## What it collects\n\nAutomatically, per event: anonymous device id (first-party `localStorage`), session id (30-min inactivity window), URL/path/hostname, referrer, UTM parameters, and screen size. Device/browser/OS are derived server-side from the User-Agent — the SDK stays tiny and ships no UA-parsing code.\n\n- `pageview` — on load and SPA navigations.\n- `page_leave` — on tab hide/unload, with `time_on_page` (seconds) and `scroll_depth` (max %).\n- `$identify` — when `identify()` is called, for server-side identity stitching.\n\nCustom and standard lifecycle events use `track()` / typed helpers and appear in the Analyse dashboard, funnels, and conversion KPIs.\n\n## License\n\nMIT\n","readmeFilename":"README.md","homepage":"https://github.com/track/web.analyse.net#readme","repository":{"type":"git","url":"git+https://github.com/track/web.analyse.net.git","directory":"packages/tracker"},"bugs":{"url":"https://github.com/track/web.analyse.net/issues"}}