@analyse.net/sdk

The official Analyse 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.

Install

Script tag (zero-code)

<scriptsrc="https://cdn.jsdelivr.net/npm/@analyse.net/sdk/dist/index.global.js"
data-public-key="pk_live_your_key"
defer></script>

That's it — pageviews and page-leave signals are tracked automatically.

Optional data attributes:

• data-host — override the ingest host (defaults to the hosted Analyse ingest).
• data-auto-pageviews="false" — disable automatic pageview tracking.
• data-auto-page-leave="false" — disable automatic page_leave tracking.

Script-tag users also get standard lifecycle helpers on the global Analyse object (e.g. Analyse.checkoutStarted(...)).

npm

npm install @analyse.net/sdk

import{init,identify,contentViewed,signedUp}from"@analyse.net/sdk";init({publicKey: "pk_live_your_key"});contentViewed({content_id: "post_abc123",content_type: "blog_post",title: "How to track attribution",});identify("user_123");signedUp({method: "email"});

Browser API

Function	Description
init(config)	Initialize the client. Safe to call once.
track(name, properties?)	Record a custom event.
identify(userId, traits?)	Associate the device with a known user.
page()	Manually send a pageview.
reset()	Clear identity/session (e.g. on logout) and flush.

Standard lifecycle events

Typed helpers enforce consistent event names and property shapes across customers. Import from @analyse.net/sdk (browser) or @analyse.net/sdk/events (browser + server helpers).

Event	Browser helper	Server helper
content_viewed	contentViewed()	captureContentViewed()
signup_completed	signedUp()	captureSignedUp()
checkout_started	checkoutStarted()	captureCheckoutStarted()
checkout_cancelled	checkoutCancelled()	captureCheckoutCancelled()
checkout_finished	checkoutFinished()	captureCheckoutFinished()
trial_started	trialStarted()	captureTrialStarted()
trial_ended	trialEnded()	captureTrialEnded()
subscription_cancelled	subscriptionCancelled()	captureSubscriptionCancelled()

Checkout properties

All checkout_* events share a base shape with a required payment_type:

• "one_time" — single charge (no billing_interval)
• "subscription" — requires billing_interval: "month", "year", or "week"

Common optional fields: checkout_id, amount (minor units / cents), currency (ISO 4217), product_id, plan, items_count, coupon.

Use the same checkout_id across checkout_started, checkout_cancelled, and checkout_finished so funnels correlate correctly.

Example: checkout funnel

import{init,identify,checkoutStarted,checkoutCancelled,checkoutFinished}from"@analyse.net/sdk";init({publicKey: "pk_live_your_key"});constcheckoutId=crypto.randomUUID();checkoutStarted({checkout_id: checkoutId,payment_type: "subscription",plan: "pro",billing_interval: "month",amount: 4900,currency: "USD",});// On abandon:checkoutCancelled({checkout_id: checkoutId,payment_type: "subscription",billing_interval: "month",reason: "user_abandoned",step: "payment",});// On success (browser — see trust model below):checkoutFinished({checkout_id: checkoutId,payment_type: "subscription",billing_interval: "month",amount: 4900,currency: "USD",plan: "pro",subscription_id: "sub_123",});

Trust model for checkout_finished

• Browser — fine for prototyping and client-only apps.
• Server (preferred) — capture from Stripe webhooks or billing jobs so revenue data cannot be spoofed.

import{createServerClient,captureCheckoutFinished}from"@analyse.net/sdk/server";constanalyse=createServerClient({publicKey: process.env.ANALYSE_KEY!});captureCheckoutFinished(analyse,{personId: "user_123",properties: {checkout_id: checkoutId,payment_type: "subscription",billing_interval: "month",amount: 4900,currency: "USD",plan: "pro",subscription_id: "sub_123",},});awaitanalyse.flush();

Pair lifecycle events with identify() after signup or login — do not put PII (email, name) in event properties.

Content attribution (blog → signup)

Call 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:

Property (on signup_completed)	Description
first_content_id	First content piece viewed on this device
last_content_id	Most recently viewed content before signup
content_touchpoint_count	Distinct content pieces viewed

Cross-session stitching still uses the anonymous device id plus identify() — content attribution adds the which post layer on top.

import{init,contentViewed,identify,signedUp}from"@analyse.net/sdk";init({publicKey: "pk_live_your_key"});// On your blog post template:contentViewed({content_id: "kb_page_abc123",content_type: "blog_post",title: "How we handle attribution",});// Days later, on signup:identify(user.id);signedUp({method: "email"});// includes first/last content metadata

Use getContentAttribution() if you need the same metadata on custom conversion events.

Server-side (@analyse.net/sdk/server)

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

Method	Description
createServerClient(config)	Create a server client (publicKey, host?, maxBatchSize?).
capture(input)	Buffer an event. Requires personId or anonymousId.
captureSignedUp, captureCheckoutStarted, …	Typed standard lifecycle captures.
identify(personId, { anonymousId?, traits? })	Record an identity association.
flush()	Send buffered events. Rejects on non-2xx (batch is re-buffered for retry).
shutdown()	Alias for flush(); call before a process exits.

Set maxBatchSize: 1 to send every event immediately.

Config

typeAnalyseConfig={publicKey: string;// requiredhost?: string;// ingest base URL, no trailing slashautoPageviews?: boolean;// default true (incl. SPA route changes)autoPageLeave?: boolean;// default true (time_on_page + scroll_depth)flushIntervalMs?: number;// default 5000maxBatchSize?: number;// default 20};

What it collects

Automatically, 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.

• pageview — on load and SPA navigations.
• page_leave — on tab hide/unload, with time_on_page (seconds) and scroll_depth (max %).
• $identify — when identify() is called, for server-side identity stitching.

Custom and standard lifecycle events use track() / typed helpers and appear in the Analyse dashboard, funnels, and conversion KPIs.

License

MIT