Docs · Guide

JavaScript SDK

Prefer installing from npm over pasting a script tag? @statlark/weblets you initialize Statlark in code and gives you a typed API for goals, identity and revenue — plus a React provider. It’s a thin wrapper: initStatlark() injects the same hosted tracker and returns a handle that proxies it, so the tracker still owns cookies, first-touch attribution, automatic pageviews and transport. One source of truth.

Install

npm install @statlark/web

Quick start

Call initStatlark() once, with your website id, and you get a handle back. Your site is the sl_… public id from Settings → Install. For parity with DataFast-style snippets you can pass it as websiteId instead.

import { initStatlark } from "@statlark/web";

const statlark = await initStatlark({ site: "sl_xxxx" });

statlark.goal("signup", { plan: "pro" });
statlark.identify({ user_id: "u_123", user_email: "ada@example.com" });
statlark.payment({ amount: 4900, transaction_id: "pi_123", currency: "usd" });

You can start calling methods before the await resolves — calls are buffered and flushed, in order, once the tracker is ready. On the server initStatlark()resolves to a no-op handle, so it’s safe to call during server rendering; the tracker only ever runs in the browser.

Pageviews are automatic

You don’t call pageview() for normal navigation. The tracker records a pageview on load and on every History API navigation (pushState/replaceState/popstate) — which is how Next.js App Router, React Router and most SPA routers move between pages. Call statlark.pageview()yourself only for a view your framework doesn’t route through the History API.

React

Wrap your app in StatlarkProvider at a client root, then reach the handle from any client component with useStatlark(). The provider injects the tracker once; the handle it gives you is callable from the first render.

// app/providers.tsx — a client component at your root
"use client";
import { StatlarkProvider } from "@statlark/web/react";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <StatlarkProvider config={{ site: "sl_xxxx" }}>
      {children}
    </StatlarkProvider>
  );
}

// any client component
"use client";
import { useStatlark } from "@statlark/web/react";

export function UpgradeButton() {
  const statlark = useStatlark();
  return <button onClick={() => statlark.goal("upgrade_click")}>Go Pro</button>;
}

react is an optional peer dependency — the base @statlark/webimport has no React dependency, so it works the same in Vue, Svelte or plain JavaScript. The provider doesn’t fire pageviews itself (the tracker already does), so route changes are counted exactly once.

Configuration

Every option is the camel-cased twin of a data-* snippet attribute — cookieDomain, trackLocalhost, honorDnt, cookieless, disablePayments, debug and the rest. Two are worth calling out:

api — the camel twin of data-api. Set it to your first-party proxy path (e.g. /q3v/e) to route events through your own domain and dodge host-based ad-blockers.
scriptSrc — the one option with no data-* twin, since the SDK injects the tracker itself. Override the tracker URL (defaults to https://statlark.com/script.js) to self-host or version-pin it.

const statlark = await initStatlark({
  site: "sl_xxxx",
  api: "/q3v/e", // your first-party proxy path
});

The handle

The object initStatlark() resolves to — and useStatlark() returns — carries the full tracker contract:

goal(name, props?) — record a conversion. Calling the handle directly, statlark("signup"), is shorthand for this.
event(name, props?) — record a custom event.
identify(opts) — attach a known identity to the visitor.
payment(opts) — record revenue (needs amount and transaction_id).
pageview(path?) — record a pageview (rarely needed; see above).
getVisitorId() — the current visitor id (the _slk_vid cookie), for keying a server-side goal or payment to the same visitor. Returns nullbefore the tracker is ready or when it isn’t running.