@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)

<script
  src="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" });

const checkoutId = 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";

const analyse = 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",
  },
});

await analyse.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

type AnalyseConfig = {
  publicKey: string;        // required
  host?: string;            // ingest base URL, no trailing slash
  autoPageviews?: boolean;  // default true (incl. SPA route changes)
  autoPageLeave?: boolean;  // default true (time_on_page + scroll_depth)
  flushIntervalMs?: number; // default 5000
  maxBatchSize?: 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