alphana-sdk 1.6.5 → 1.8.0

package/README.md

@@ -1,24 +1,53 @@
 # alphana-sdk
 
-[![npm](https://img.shields.io/npm/v/alphana-sdk.svg)](https://www.npmjs.com/package/alphana-sdk)
+Client-side analytics SDK for the [Alphana](https://alphana.ir) platform. Collects navigation, time-on-page, heatmap interactions, console errors, and feature-flag evaluations, then batches and sends them to your Alphana backend.
 
-Client-side analytics SDK for React, Next.js, Vite, and vanilla JS/TS. Tracks SPA navigation, time-on-page, heatmaps (with optional path allowlists), console and runtime errors, session heartbeats, **feature flags** (with user targeting), behavioral signals such as **rage clicks** and quick **U-turns**, first/last-touch **UTM attribution**, **revenue events**, and a one-time **`client_context`** snapshot per session (device category, OS, browser, language, viewport, time zone, SDK version) for catalog parity with the dashboard — without third-party scripts.
+**NPM:** `[alphana-sdk](https://www.npmjs.com/package/alphana-sdk)` · **Version:** 0.5.x · **License:** MIT
 
-**Note:** `client_context` does not record DOM for full visual replay; that still requires a dedicated capture pipeline (e.g. rrweb) if you add it later.
+## Features
 
-- **Package:** [alphana-sdk on npm](https://www.npmjs.com/package/alphana-sdk)
-- **Exports:** `alphana-sdk` (core) and `alphana-sdk/react` (provider + hooks)
+- **SPA navigation** — Monitors `history.pushState`, `replaceState`, and `popstate` for automatic page views and U-turn detection (quick bounces).
+- **Time on page** — Cumulative dwell time per path, updated on tab hide and navigation.
+- **Heatmaps** — Sampled mouse moves, clicks, scrolls, and rage-click bursts; coordinates stored as page percentages for resolution-independent replay.
+- **Session identity** — Per-tab session ID plus a persistent `visitorId` in `localStorage`.
+- **Batched ingest** — Events queue locally and flush on batch size, interval, or page unload (`sendBeacon`).
+- **Heartbeats** — Keep-alive pings every 30s; deactivate signal when the tab is hidden.
+- **Error logging** — Patches `console.info/warn/error`, `window.onerror`, and unhandled rejections (optional).
+- **Feature flags** — Evaluate flags server-side with `identify()` targeting (requires `secretKey`).
+- **React bindings** — Optional subpath `alphana-sdk/react` with provider and hooks (React 17+).
+- **Tree-shakeable** — `sideEffects: false`; React is an optional peer dependency.
+- **SSR-safe** — `init()` is a no-op when `window` is undefined.
 
 ## Installation
 
 ```bash
 npm install alphana-sdk
+# or
 pnpm add alphana-sdk
-yarn add alphana-sdk
+# or
 bun add alphana-sdk
 ```
 
----
+For React integration, install React 17+ in your app (peer dependency):
+
+```bash
+npm install react react-dom
+```
+
+## Credentials
+
+Create an app in the Alphana dashboard and copy:
+
+| Value      | Config key  | Usage                            |
+| ---------- | ----------- | -------------------------------- |
+| App ID     | `appId`     | Sent in every request body       |
+| Secret key | `secretKey` | `Authorization: Bearer …` header |
+
+Default API endpoint (cloud):
+
+```
+https://api.alphana.ir/api/events
+```
 
 ## Quick start
 
@@ -35,8 +64,8 @@ createRoot(document.getElementById("root")!).render(
   <StrictMode>
     <UserTrackerProvider
       config={{
-        appId: import.meta.env.VITE_TRACKER_APP_ID,
-        secretKey: import.meta.env.VITE_TRACKER_SECRET,
+        appId: "YOUR_APP_ID",
+        secretKey: "YOUR_SECRET_KEY",
       }}
     >
       <App />
@@ -45,15 +74,25 @@ createRoot(document.getElementById("root")!).render(
 );
 ```
 
-```bash
-# .env.local
-VITE_TRACKER_APP_ID=your_app_id
-VITE_TRACKER_SECRET=your_secret_key
+```tsx
+// Any child component
+import { useTracker, useFeatureFlagEnabled } from "alphana-sdk/react";
+
+export function MyComponent() {
+  const tracker = useTracker();
+  const showBeta = useFeatureFlagEnabled("new-checkout");
+
+  function handleSignup() {
+    tracker?.identify({ email: "user@example.com", plan: "pro" });
+  }
+
+  return showBeta ? <BetaCheckout /> : <Checkout />;
+}
 ```
 
 ### Next.js App Router
 
-Wrap the provider in a Client Component, then use `usePageView` with `usePathname()` so App Router navigations are recorded (History API hooks alone do not always fire).
+The App Router does not trigger `history.pushState` the same way as classic SPAs. Wrap the app in the provider, then track pathname changes manually.
 
 ```tsx
 // app/providers.tsx
@@ -75,6 +114,19 @@ export function Providers({ children }: { children: ReactNode }) {
 }
 ```
 
+```tsx
+// app/navigation-tracker.tsx
+"use client";
+
+import { usePathname } from "next/navigation";
+import { usePageView } from "alphana-sdk/react";
+
+export function NavigationTracker() {
+  usePageView(usePathname());
+  return null;
+}
+```
+
 ```tsx
 // app/layout.tsx
 import { Providers } from "./providers";
@@ -116,7 +168,7 @@ NEXT_PUBLIC_TRACKER_APP_ID=your_app_id
 NEXT_PUBLIC_TRACKER_SECRET=your_secret_key
 ```
 
-### Vanilla JS / TypeScript
+### Vanilla TypeScript / JavaScript
 
 ```ts
 import { UserTracker } from "alphana-sdk";
@@ -126,213 +178,176 @@ const tracker = new UserTracker({
   secretKey: "YOUR_SECRET_KEY",
 });
 
-tracker.init(); // safe no-op during SSR (`window` undefined)
+tracker.init();
 
-tracker.destroy(); // teardown, timers, best-effort final send
+// Optional: tear down on logout or SPA teardown
+// tracker.destroy();
 ```
 
-### Script tag / Google Tag Manager
+## CDN / script tag (IIFE)
 
-Use the CDN build when you cannot install npm packages. Add this to `<head>` or
-as a GTM Custom HTML tag:
+The build also emits a self-contained browser bundle:
 
-```html
-<script
-  async
-  src="https://storage.alphana.ir/cdn/alphana-sdk/latest/alphana-sdk.js"
-  data-app-id="YOUR_APP_ID"
-  data-secret-key="YOUR_SECRET_KEY"
-></script>
 ```
-
-Optional config can also be added as `data-*` attributes on the same script:
+dist/alphana-sdk.global.js  →  window.AlphanaSDK
+```
 
 ```html
-<script
-  async
-  src="https://storage.alphana.ir/cdn/alphana-sdk/latest/alphana-sdk.js"
-  data-app-id="YOUR_APP_ID"
-  data-secret-key="YOUR_SECRET_KEY"
-  data-track-heatmap="true"
-  data-session-replay="false"
-></script>
+<script src="https://your-cdn.example/cdn/alphana-sdk/latest/alphana-sdk.js"></script>
+<script>
+  const tracker = new AlphanaSDK.UserTracker({
+    appId: "YOUR_APP_ID",
+    secretKey: "YOUR_SECRET_KEY",
+  });
+  tracker.init();
+</script>
 ```
 
-After the script loads, manual calls are available through `window.alphana`,
-for example `window.alphana("identify", { email: "user@example.com" })`.
-
----
-
-## Configuration reference
+Publish the bundle with MinIO (see [CDN upload](#cdn-upload) below). The WordPress plugin and other non-bundler sites load this file.
+
+## Configuration
+
+All options are passed to `new UserTracker(config)` or `<UserTrackerProvider config={…} />`.
+
+| Option             | Type              | Default                             | Description                                                               |
+| ------------------ | ----------------- | ----------------------------------- | ------------------------------------------------------------------------- |
+| `endpoint`         | `string`          | `https://api.alphana.ir/api/events` | Events API base URL                                                       |
+| `appId`            | `string`          | —                                   | App identifier from the dashboard                                         |
+| `secretKey`        | `string`          | —                                   | Bearer token for authenticated requests                                   |
+| `sessionId`        | `string`          | auto (`crypto.randomUUID`)          | Override session ID                                                       |
+| `trackNavigation`  | `boolean`         | `true`                              | SPA route / pageview tracking                                             |
+| `trackTime`        | `boolean`         | `true`                              | Time-on-page per path                                                     |
+| `trackHeatmap`     | `boolean`         | `true`                              | Mouse, click, scroll sampling                                             |
+| `trackLogs`        | `boolean`         | `true`                              | Console and uncaught error capture                                        |
+| `mouseSampleRate`  | `number`          | `0.3`                               | Fraction of move/scroll events to record (0–1)                            |
+| `maxHeatmapPoints` | `number`          | `2000`                              | Max in-memory points per page                                             |
+| `batchSize`        | `number`          | `20`                                | Auto-flush when queue reaches this size                                   |
+| `flushInterval`    | `number`          | `5000`                              | Auto-flush interval in ms                                                 |
+| `compressPayloads` | `boolean`         | `true`                              | Gzip-compress large ingest bodies when the browser supports it              |
+| `compressionThresholdBytes` | `number` | `1024`                     | Minimum JSON size (bytes) before gzip is attempted                        |
+| `collectEndpoint`  | `string`          | —                                   | Override unified ingest URL (default: `{apiBase}/collect` from `endpoint`) |
+| `heatmapPages`     | `string[]`        | —                                   | Only capture heatmap data on these paths (from dashboard “Heatmap Pages”) |
+| `onEvent`          | `(event) => void` | —                                   | Synchronous callback for every emitted event                              |
+
+Example with heatmap path allowlist and custom sampling:
 
-| Option             | Type                            | Default                             | Description                                                                                                                                                                                                                                                                  |
-| ------------------ | ------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `appId`            | `string`                        | —                                   | **Required for Alphana Cloud.** App ID from the dashboard; included in batch payloads.                                                                                                                                                                                       |
-| `secretKey`        | `string`                        | —                                   | **Required for Alphana Cloud** (and for feature flags). Sent as `Authorization: Bearer …` on API calls.                                                                                                                                                                      |
-| `endpoint`         | `string`                        | `https://api.alphana.ir/api/events` | Events base URL for Alphana Cloud. Batching uses `{endpoint}/batch`, heartbeats `{endpoint}/heartbeat`, logs derived under the same API prefix.                                                                                                                              |
-| `sessionId`        | `string`                        | auto UUID                           | Optional fixed session id.                                                                                                                                                                                                                                                   |
-| `trackNavigation`  | `boolean`                       | `true`                              | Intercept `pushState` / `replaceState` / `popstate` for SPA routes; also emits U-turn detection.                                                                                                                                                                             |
-| `trackTime`        | `boolean`                       | `true`                              | Cumulative time per path.                                                                                                                                                                                                                                                    |
-| `trackHeatmap`     | `boolean`                       | `true`                              | Mouse move, click, scroll sampling; rage-click bursts.                                                                                                                                                                                                                       |
-| `heatmapPages`     | `string[]`                      | —                                   | Optional client allowlist: heatmap capture is limited to these paths (values are normalized like dashboard rows). If omitted, the SDK may still record moves; the **backend only persists** heatmap points when the app has ≥1 registered heatmap page and the path matches. |
-| `trackLogs`        | `boolean`                       | `true`                              | Patches `console.info/warn/error`, `window.onerror`, `unhandledrejection`; sends to `/logs/ingest`.                                                                                                                                                                          |
-| `mouseSampleRate`  | `number` (0–1)                  | `0.3`                               | Fraction of move/scroll events kept.                                                                                                                                                                                                                                         |
-| `maxHeatmapPoints` | `number`                        | `2000`                              | Max in-memory heatmap points per path in the session snapshot.                                                                                                                                                                                                               |
-| `batchSize`        | `number`                        | `20`                                | Queue size before an automatic flush.                                                                                                                                                                                                                                        |
-| `flushInterval`    | `number` (ms)                   | `5000`                              | Timer-based flush when the queue is non-empty.                                                                                                                                                                                                                               |
-| `onEvent`          | `(event: TrackerEvent) => void` | —                                   | Synchronous callback for every emitted event.                                                                                                                                                                                                                                |
-
-TypeScript marks `appId` / `secretKey` as optional on `TrackerConfig`, but you should always pass them when using the hosted Alphana API.
-
----
+```ts
+const tracker = new UserTracker({
+  appId: "YOUR_APP_ID",
+  secretKey: "YOUR_SECRET_KEY",
+  heatmapPages: ["/", "/pricing", "/dashboard"],
+  mouseSampleRate: 0.2,
+  onEvent: (event) => {
+    if (event.type === "rageclik") {
+      console.debug("Rage click", event.data);
+    }
+  },
+});
+```
 
-## API
+## Core API (`UserTracker`)
 
-### `UserTracker`
+### Lifecycle
 
 ```ts
-import { UserTracker } from "alphana-sdk";
+import { UserTracker, DEFAULT_ENDPOINT } from "alphana-sdk";
 
-const tracker = new UserTracker({ appId: "id", secretKey: "sk" });
-
-tracker.init();
-tracker.destroy();
-
-tracker.trackPageView(path?: string);
-tracker.trackRevenue({
-  eventName: "purchase",
-  amount: 4900,
-  currency: "USD",
-  transactionId: "ord_123",
-  productId: "starter-plan",
-});
+const tracker = new UserTracker({ appId: "…", secretKey: "…" });
 
-tracker.flush(); // POST queued events to `/batch` (fire-and-forget)
-
-tracker.getSession(); // read-only SessionData
-tracker.getPageViews();
-tracker.getTimeSpent(); // Record<path, milliseconds>
-tracker.getHeatmapData(path: string): HeatmapPoint[];
-tracker.getHeatmapData(): Record<string, HeatmapPoint[]>;
-
-tracker.subscribe(fn); // returns unsubscribe
-
-// Feature flags (requires `secretKey` + valid `endpoint`)
-tracker.identify({ email: "u@example.com", plan: "pro" });
-tracker.getFlags();
-tracker.isFeatureEnabled("my-flag");
-tracker.onFlagsChange((flags) => { /* ... */ }); // unsubscribe fn
-void tracker.fetchFlags();
-
-// A/B tests (requires `secretKey` + valid `endpoint`)
-tracker.getAbVariants();
-tracker.getAbVariant("checkout-cta-test");
-tracker.isAbVariant("checkout-cta-test", "variant-b");
-tracker.onAbTestsChange((variants) => { /* ... */ });
-void tracker.fetchAbTests(["checkout-cta-test"]); // optional keys filter
+tracker.init(); // attach listeners; safe on server (no-op)
+tracker.destroy(); // remove listeners, flush queue via sendBeacon
 ```
 
-**Attribution:** Pageviews automatically read `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, plus click IDs (`gclid`, `fbclid`, `ttclid`, `msclkid`) from the current URL. The SDK persists first-touch and last-touch context in localStorage and attaches it to pageview and revenue events.
+`DEFAULT_ENDPOINT` is exported if you need the cloud default URL in your own config layer.
 
-**Revenue:** `trackRevenue(payload)` records purchases, subscriptions, renewals, upgrades, refunds, or custom monetary events. Include a stable `transactionId` for idempotent backend upserts.
+### Manual page views
 
-**Heartbeat:** Every 30s while the tab is visible, a POST is sent to `{endpoint}/heartbeat` with session and visitor ids.
+```ts
+tracker.trackPageView("/products?id=1");
+```
 
-**Deactivate:** On tab hide / `pagehide`, a beacon marks the session inactive and flushes queued analytics via `sendBeacon` when possible.
+Dispatches a `pageview` event and the custom DOM event `tracker:navigate` (used internally by time and heatmap plugins).
 
-**Batching:** Analytics events are POSTed as JSON to `{endpoint}/batch` with `visitorId`, optional `location`, and an `events` array.
+### Session data (in-memory)
 
-### `LogCapture`
+```ts
+tracker.getSession(); // full snapshot: id, visitorId, pageViews, timeSpent, heatmap, location
+tracker.getPageViews(); // PageView[]
+tracker.getTimeSpent(); // Record<path, milliseconds>
+tracker.getHeatmapData("/"); // HeatmapPoint[] for one path
+tracker.getHeatmapData(); // Record<path, HeatmapPoint[]>
+```
 
-Used internally when `trackLogs: true`. Sends structured entries to `{apiBase}/logs/ingest` (API base is derived by stripping the last path segment from your `endpoint`, e.g. `…/api/events` → `…/api`).
+### Subscribing to events
 
 ```ts
-import { LogCapture } from "alphana-sdk";
-
-const capture = new LogCapture({
-  endpoint: "https://api.alphana.ir/api/events",
-  sessionId: "ses_abc123",
-  appId: "YOUR_APP_ID",
-  secretKey: "sk_...",
+const unsub = tracker.subscribe((event) => {
+  console.log(event.type, event.data);
 });
-
-capture.init();
-capture.capture("error", "Something failed", { stack: err.stack });
-capture.destroy();
+unsub();
 ```
 
-### `renderHeatmap`
+### Feature flags
 
-Draws `HeatmapPoint[]` on a `<canvas>` (blue → red).
+Requires `secretKey`. Flags are fetched on `init()` and after each `identify()` call.
 
 ```ts
-import { renderHeatmap } from "alphana-sdk";
+tracker.identify({ email: "user@example.com", plan: "enterprise" });
 
-const canvas = document.getElementById("heatmap") as HTMLCanvasElement;
-canvas.width = 1280;
-canvas.height = 720;
+tracker.getFlags(); // { "flag-key": true, ... }
+tracker.isFeatureEnabled("flag-key"); // boolean
 
-renderHeatmap(canvas, points, {
-  radius: 25,
-  maxOpacity: 0.85,
-  minOpacity: 0,
+const unsub = tracker.onFlagsChange((flags) => {
+  console.log("Flags updated", flags);
 });
-```
-
-### `DEFAULT_ENDPOINT`
+unsub();
 
-```ts
-import { DEFAULT_ENDPOINT } from "alphana-sdk";
-// "https://api.alphana.ir/api/events"
+await tracker.fetchFlags(); // manual refresh
 ```
 
----
-
-## React hooks
+### Error logging (manual)
 
-All hooks are exported from **`alphana-sdk/react`**.
+When `trackLogs` is enabled, `tracker.logCapture` is available after `init()`:
 
-`useTracker()` returns `UserTracker | null` (null outside a provider).
+```ts
+try {
+  riskyOperation();
+} catch (err) {
+  tracker.logCapture?.capture("error", "riskyOperation failed", {
+    stack: err instanceof Error ? err.stack : undefined,
+    meta: { feature: "checkout" },
+  });
+}
+```
 
-| Hook                                | Returns                   | Description                                                                                |
-| ----------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------ |
-| `useTracker()`                      | `UserTracker \| null`     | Tracker from context.                                                                      |
-| `usePageView(path?)`                | `void`                    | When `path` is defined, calls `trackPageView(path)` on change. No-op if `path` is omitted. |
-| `useHeatmapData(path?, refreshMs?)` | `HeatmapPoint[]`          | Live points for a path; optional debounced refresh (default 500 ms).                       |
-| `usePageViews()`                    | `PageView[]`              | Page views in the current session.                                                         |
-| `useTrackRevenue()`                 | `(payload: RevenueEventPayload) => void` | Stable hook for recording purchases/subscriptions/refunds through the current tracker. |
-| `useTimeSpent()`                    | `Record<string, number>`  | Cumulative **milliseconds** per path.                                                      |
-| `useFeatureFlags()`                 | `Record<string, boolean>` | Evaluated flags; updates after `identify()`.                                               |
-| `useFeatureFlagEnabled(key)`        | `boolean`                 | Whether `key` is enabled.                                                                  |
-| `useAbTests()`                      | `Record<string, string \| null>` | Assigned variant per experiment key.                                                |
-| `useAbVariant(experimentKey)`       | `string \| null`          | Variant key for one experiment.                                                            |
-| `useIsAbVariant(experiment, variant)` | `boolean`               | Whether visitor is in that variant.                                                        |
+## React API (`alphana-sdk/react`)
 
-```tsx
-import { useTracker, useTimeSpent, useHeatmapData } from "alphana-sdk/react";
+| Export                              | Description                                                                   |
+| ----------------------------------- | ----------------------------------------------------------------------------- |
+| `UserTrackerProvider`               | Creates one `UserTracker`, calls `init()` on mount, `destroy()` on unmount    |
+| `useTracker()`                      | Returns the tracker instance, or `null` outside a provider                    |
+| `usePageView(path?)`                | Records a page view when `path` changes (use with `usePathname()` in Next.js) |
+| `usePageViews()`                    | Live list of session page views                                               |
+| `useTimeSpent()`                    | Live `Record<path, ms>`                                                       |
+| `useHeatmapData(path?, refreshMs?)` | Live heatmap points for a path (debounced updates, default 500ms)             |
+| `useFeatureFlags()`                 | Live flag map; re-renders on `onFlagsChange`                                  |
+| `useFeatureFlagEnabled(key)`        | Boolean for a single flag                                                     |
 
-export function DebugPanel() {
-  const tracker = useTracker();
-  const timeByPath = useTimeSpent();
-  const points = useHeatmapData();
+`UserTrackerProvider` captures `config` only on the first render; changing props later does not reconfigure the tracker.
 
-  if (!tracker) return null;
+## Event types
 
-  return (
-    <div>
-      <p>Paths tracked: {Object.keys(timeByPath).length}</p>
-      <p>Heatmap points (this page): {points.length}</p>
-      <button type="button" onClick={() => tracker.flush()}>
-        Flush now
-      </button>
-    </div>
-  );
-}
-```
+Events flow through `onEvent`, `subscribe()`, the in-memory session, and the remote batch queue.
 
----
+| `type`      | Description                                                                      |
+| ----------- | -------------------------------------------------------------------------------- |
+| `pageview`  | Path, title, timestamp, referrer                                                 |
+| `timespent` | Milliseconds spent on a path before leaving                                      |
+| `heatmap`   | Mouse move, click, or scroll point (`xPct`, `yPct`, optional `target` on clicks) |
+| `rageclik`  | Rapid repeated clicks in one area                                                |
+| `uturn`     | Left a page within ~5s (bounce signal)                                           |
 
-## TypeScript types
+TypeScript definitions:
 
 ```ts
 import type {
@@ -346,25 +361,62 @@ import type {
   SessionData,
   GeoLocation,
   HeatmapRenderOptions,
-  RageClick,
-  UTurn,
-  RevenueEvent,
-  RevenueEventPayload,
-  RevenueEventStatus,
-  RevenueLineItem,
   LogLevel,
   LogEntry,
 } from "alphana-sdk";
 ```
 
----
+## Heatmap rendering
+
+Use `renderHeatmap` to draw collected points on a `<canvas>` (e.g. in a dashboard preview). Coordinates are percentages of page dimensions, so the overlay scales with canvas size.
+
+```ts
+import { renderHeatmap } from "alphana-sdk";
+
+const canvas = document.getElementById("heatmap") as HTMLCanvasElement;
+const points = tracker.getHeatmapData("/");
+
+renderHeatmap(canvas, points, {
+  radius: 25,
+  maxOpacity: 0.85,
+  minOpacity: 0,
+});
+```
+
+## Network behavior
+
+| Traffic       | Endpoint                                | When                                                        |
+| ------------- | --------------------------------------- | ----------------------------------------------------------- |
+| Collect (SDK ≥ 1.8) | `POST {apiBase}/collect`          | Event batches, heartbeats, and logs (multiplexed envelope)  |
+| Event batch   | `POST {endpoint}/batch`                 | Legacy SDK &lt; 1.8 — still supported on the backend        |
+| Heartbeat     | `POST {endpoint}/heartbeat`             | Legacy SDK &lt; 1.8                                         |
+| Logs          | `POST {apiBase}/logs/ingest`            | Legacy SDK &lt; 1.8                                         |
+| Feature flags | `POST {apiBase}/feature-flags/evaluate` | On init and after `identify()`                              |
+
+All authenticated requests send `Authorization: Bearer {secretKey}`. Analytics failures are silent in production (no thrown errors to end users). Unload uses `navigator.sendBeacon` when available.
 
-## WordPress
+Visitor country/city is resolved asynchronously from IP and attached to batch payloads when available.
 
-For WordPress sites, use the **Alphana Tracker** plugin (ZIP):
+## Package exports
 
-**Download:** [https://storage.alphana.ir/cdn/alphana-tracker.zip](https://storage.alphana.ir/cdn/alphana-tracker.zip)
+```ts
+// Core (framework-agnostic)
+import {
+  UserTracker,
+  DEFAULT_ENDPOINT,
+  LogCapture,
+  renderHeatmap,
+} from "alphana-sdk";
 
-1. In WordPress admin: **Plugins → Add New → Upload Plugin** and choose the ZIP, or unzip into `wp-content/plugins/alphana-tracker/`.
-2. Activate **Alphana Tracker**.
-3. Open **Settings → Alphana Tracker**, enter **App ID** and **Secret Key** from the Alphana dashboard, enable tracking, and save.
+// React (optional)
+import {
+  UserTrackerProvider,
+  useTracker,
+  usePageView,
+  useHeatmapData,
+  usePageViews,
+  useTimeSpent,
+  useFeatureFlags,
+  useFeatureFlagEnabled,
+} from "alphana-sdk/react";
+```