Lightweight, privacy-first analytics SDK for tgram-analytics.

• Zero dependencies — only browser APIs
• < 2 KB gzipped — won't slow your page down
• TypeScript-first — full type definitions included, no @types package needed
• Privacy-friendly — no cookies, no fingerprinting, respects Do Not Track
• SPA-ready — auto-tracks route changes with React Router, Vue Router, Next.js, etc.

Before using this SDK you need:

1. A running tgram-analytics server. See the server repo for setup instructions.
2. A project API key. Create one by sending /add myapp.com to the Telegram bot. The bot replies with a key that starts with proj_.

npm install tgram-analytics

Host dist/index.iife.js from your server (or a CDN) and load it on your page. It exposes the global TGA object.

<script src="https://your-server.com/sdk/tga.min.js"></script>
<script>
  TGA.init("proj_xxx", { serverUrl: "https://your-server.com" });
</script>

import TGA from "tgram-analytics";

// Step 1 — initialise once, at the top of your app.
TGA.init("proj_abc123", {
  serverUrl: "https://analytics.example.com",
});

// Step 2 — track custom events anywhere in your code.
TGA.track("purchase", { amount: 49, currency: "USD", plan: "pro" });

Pageviews are sent automatically on load and on every SPA route change — no extra code needed.

const { default: TGA } = require("tgram-analytics");

TGA.init("proj_abc123", { serverUrl: "https://analytics.example.com" });
TGA.track("signup");

Initialises the SDK. Call this once, before using any other method.

TGA.init("proj_abc123", {
  serverUrl: "https://analytics.example.com",
  autoPageview: true,
  respectDNT: true,
});

Throws an Error if apiKey is invalid or serverUrl is missing.

Tracks a custom named event.

TGA.track("purchase", { amount: 49, currency: "USD", plan: "pro" });
TGA.track("signup"); // properties are optional

Tracks a pageview. You rarely need this — autoPageview: true (the default) handles it automatically.

// Use defaults (current URL and document.referrer).
TGA.pageview();

// Pass explicit values.
TGA.pageview("/checkout", "https://example.com/cart");

Attaches persistent properties to every subsequent track() call.

// After a user logs in:
TGA.identify({ plan: "pro", locale: "en-US" });

// Every subsequent track() call now includes plan and locale automatically.
TGA.track("purchase", { amount: 49 }); // => properties: { plan, locale, amount }

Per-event properties (passed directly to track()) override identify() properties when keys conflict.

Manually opts the current user in or out of tracking.

// Disable all tracking (e.g. user declined consent banner).
TGA.opt("out");

// Re-enable tracking.
TGA.opt("in");

Note: The opt-out state is not persisted across page loads. If you want persistence, store the preference yourself (e.g. in localStorage) and call TGA.opt("out") on every page load when needed.

Force-sends all buffered events immediately. Only relevant when batch is enabled.

// Ensure no events are lost before a programmatic navigation.
await TGA.flush();
router.push("/thank-you");

Returns Promise<void>.

Starts a new session. Clears the session ID from sessionStorage and generates a fresh one. Also clears all properties set via identify().

function onLogout() {
  TGA.reset();
  // Future events are now attributed to a new anonymous session.
}

All options are passed as the second argument to TGA.init().

When autoPageview is true (the default), the SDK automatically sends a pageview after every distinct URL change — no configuration required. It works with:

• React Router — pushState / popstate
• Vue Router — pushState / replaceState
• Next.js App Router — pushState
• Svelte Kit — pushState
• Any other framework that uses the History API

Consecutive navigations to the same URL are deduplicated, so rapid replaceState calls (e.g. syncing query params) do not generate duplicate pageviews.

Batching is useful when you track many events in a short time (e.g. scroll depth, click heatmaps). Instead of one request per event, the SDK buffers events and sends them together.

TGA.init("proj_xxx", {
  serverUrl: "https://analytics.example.com",
  batch: { maxSize: 20, maxWait: 3000 },
});

The queue flushes automatically when:

• The buffer reaches maxSize events.
• maxWait milliseconds have passed since the first event in the batch.
• The user navigates away from the page (visibilitychange, pagehide).
• You call TGA.flush() manually.

• No cookies. Session IDs are stored in sessionStorage only, which is scoped to a single tab and cleared automatically when the tab closes.
• No fingerprinting. The SDK does not access canvas, WebGL, audio, or any other fingerprinting surface.
• Do Not Track. When respectDNT: true (the default), the SDK checks navigator.doNotTrack on init. If DNT is enabled, all tracking is silently disabled — no requests are sent.
• Write-only API. The server's ingestion endpoints are write-only. No user data can be read back via the API key.

The server enforces a domain allowlist per project. When the allowlist is not empty, requests from origins not on the list are rejected with 403 Forbidden.

To add your domain:

1. Open the Telegram bot.
2. Send /projects and select your project.
3. Tap ⚙️ Settings → Domain allowlist and add your domain.

If you are developing locally, either leave the allowlist empty (allows all origins) or add http://localhost:3000 (or whichever port you use).

The server must also have CORS middleware enabled. If you deployed using the official server image, CORS is configured automatically.

Full type definitions are included in the package — no separate @types package is needed.

import TGA from "tgram-analytics";
import type { TGAOptions, EventProperties } from "tgram-analytics";

const options: TGAOptions = {
  serverUrl: "https://analytics.example.com",
  autoPageview: true,
};

TGA.init("proj_xxx", options);

const props: EventProperties = { amount: 49, plan: "pro" };
TGA.track("purchase", props);

Contributions are welcome! Please open an issue or pull request on GitHub.

git clone https://github.com/tg-analytics/sdk-js
cd sdk-js
npm install

1. Run npm run check — fixes linting and formatting automatically.
2. Run npm test — all tests must pass.
3. Run npm run typecheck — zero TypeScript errors.
4. Run npm run build — the build must succeed.

MIT — see LICENSE.