@arthurreira/analytics 0.11.0 → 0.12.0

package/README.md

@@ -1,29 +1,95 @@
 # @arthurreira/analytics
 
-Lightweight analytics SDK for Next.js / React apps. Drop-in component + hook for tracking pageviews, clicks, scrolls, copies, errors, CTAs, and searches — with automatic session management.
+Lightweight analytics SDK with three usage modes:
+
+| Mode | Use when |
+| --- | --- |
+| `<Analytics />` component | Next.js / React apps — zero-config, drop it in the root layout |
+| `useAnalytics` hook | React, need custom events from individual components |
+| Vanilla script tag | Any HTML page — no framework required |
+
+Tracks pageviews, clicks, scroll depth, text copies, JS errors, CTAs, searches, and session duration — with automatic session management and optional real-time presence via WebSocket.
+
+---
 
 ## Installation
 
+### React / Next.js
+
 ```bash
 pnpm add @arthurreira/analytics
 # or
 npm install @arthurreira/analytics
-# or
-yarn add @arthurreira/analytics
 ```
 
 **Peer dependencies:** `react ^18 || ^19`, `next ^14 || ^15 || ^16`
 
+### Vanilla JS (no package manager)
+
+```html
+<script
+  src="https://unpkg.com/@arthurreira/analytics@0.12.0/dist/af-analytics.umd.js"
+  data-api-key="proj_xxx"
+  data-url="https://your-edge-worker.dev"
+></script>
+```
+
+Drops a global `AfAnalytics` object and **auto-initialises on `DOMContentLoaded`** — no other code needed.
+
+### WordPress
+
+#### Option A — `functions.php` (recommended for theme/child-theme)
+
+Add to your theme's `functions.php`:
+
+```php
+function af_analytics_enqueue() {
+    wp_enqueue_script(
+        'af-analytics',
+        'https://unpkg.com/@arthurreira/analytics@0.12.0/dist/af-analytics.umd.js',
+        [],
+        null,
+        true // load in footer
+    );
+    // Attach data attributes after the script tag is output
+    add_filter( 'script_loader_tag', function ( $tag, $handle ) {
+        if ( $handle !== 'af-analytics' ) return $tag;
+        return str_replace(
+            '<script ',
+            '<script data-api-key="proj_xxx" data-url="https://your-edge-worker.dev" ',
+            $tag
+        );
+    }, 10, 2 );
+}
+add_action( 'wp_enqueue_scripts', 'af_analytics_enqueue' );
+```
+
+#### Option B — "Insert Headers and Footers" plugin (no code)
+
+1. Install the [Insert Headers and Footers](https://wordpress.org/plugins/insert-headers-and-footers/) plugin.
+2. Go to **Settings → Insert Headers and Footers**.
+3. Paste the snippet below into the **Scripts in Footer** box and save:
+
+```html
+<script
+  src="https://unpkg.com/@arthurreira/analytics@0.12.0/dist/af-analytics.umd.js"
+  data-api-key="proj_xxx"
+  data-url="https://your-edge-worker.dev"
+></script>
+```
+
+Replace `proj_xxx` with your project API key and `https://your-edge-worker.dev` with your Edge Worker URL. The script auto-tracks pageviews, clicks, scroll depth, and JS errors with no further configuration.
+
 ---
 
 ## Quick start
 
-### Option A — Drop-in `<Analytics />` component (recommended)
+### Option A — `<Analytics />` component (Next.js, recommended)
 
-Add it once in your root layout. It automatically tracks pageviews, clicks, scroll depth milestones (25 / 50 / 75 / 100 %), text copies, and uncaught JS errors with zero extra code.
+Add it once in your root layout. Automatically tracks pageviews, clicks, scroll-depth milestones (25 / 50 / 75 / 100 %), text copies, and uncaught JS errors.
 
 ```tsx
-// app/layout.tsx  (Next.js App Router)
+// app/layout.tsx
 import { Analytics } from '@arthurreira/analytics/client'
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {
@@ -41,9 +107,9 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 }
 ```
 
-### Option B — `useAnalytics` hook (manual control)
+### Option B — `useAnalytics` hook (custom events)
 
-Use the hook directly when you need to fire custom events from your own components.
+Use the hook when you need to fire custom events from your own components.
 
 ```tsx
 'use client'
@@ -65,40 +131,59 @@ export function SearchBar() {
 }
 ```
 
+### Option C — Vanilla JS script tag
+
+Works with any HTML page or server-rendered site. Config is read from `data-*` attributes on the script tag itself.
+
+```html
+<script
+  src="/sdk/af-analytics.umd.js"
+  data-api-key="proj_xxx"
+  data-url="https://your-edge-worker.dev"
+></script>
+```
+
+Auto-tracks the same events as the React component. No configuration code required. Call `AfAnalytics.init()` manually if you need to reinitialise after the script was loaded dynamically.
+
 ---
 
 ## API reference
 
-### `<Analytics apiUrl apiKey />`
+### `<Analytics />` props
 
-| Prop     | Type     | Description                                               |
-| -------- | -------- | --------------------------------------------------------- |
-| `apiUrl` | `string` | Base URL of your af-analytics backend (no trailing slash) |
-| `apiKey` | `string` | Bearer token for your analytics project                   |
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `apiUrl` | `string` | yes | Base URL of your analytics backend (no trailing slash) |
+| `apiKey` | `string` | yes | Project API key |
+| `wsUrl` | `string` | no | WebSocket URL for real-time presence (default: `wss://edge.arthurreira.dev/realtime`) |
 
-Automatically tracks: **pageview**, **click**, **scroll** (depth milestones), **copy**, **error**.
+Auto-tracks: **pageview**, **click**, **scroll** (depth milestones), **copy**, **error**.
 
 ---
 
-### `useAnalytics(apiUrl, apiKey)`
+### `useAnalytics(apiUrl, apiKey, options?)`
 
-Returns an object with the following tracking functions. Events are queued internally until the session is ready, so it is safe to call them immediately on mount.
+| Option | Type | Description |
+| --- | --- | --- |
+| `options.wsUrl` | `string` | Override the default presence WebSocket URL |
 
-| Method          | Signature                                       | Description                                              |
-| --------------- | ----------------------------------------------- | -------------------------------------------------------- |
-| `trackPageview` | `(path: string) => void`                        | Manual pageview (e.g. SPA route changes)                 |
-| `trackClick`    | `(e: MouseEvent, element: HTMLElement) => void` | Click with position + element metadata                   |
-| `trackScroll`   | `(depth: number) => void`                       | Scroll depth percentage (0–100)                          |
-| `trackCopy`     | `() => void`                                    | Text copy event (captures selected text up to 200 chars) |
-| `trackError`    | `(error: Error) => void`                        | JS error with message + stack trace                      |
-| `trackCTA`      | `(ctaId: string, ctaVariant?: string) => void`  | CTA button interaction                                   |
-| `trackSearch`   | `(query: string) => void`                       | Search query                                             |
+Events are queued internally until the session is ready — safe to call immediately on mount.
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `trackPageview` | `(path: string) => void` | Manual pageview (SPA route changes) |
+| `trackClick` | `(e: MouseEvent, element: HTMLElement) => void` | Click with position + element metadata |
+| `trackScroll` | `(depth: number) => void` | Scroll depth percentage (0–100) |
+| `trackCopy` | `() => void` | Text copy event (captures selected text, up to 200 chars) |
+| `trackError` | `(error: Error) => void` | JS error with message + stack trace |
+| `trackCTA` | `(ctaId: string, ctaVariant?: string) => void` | CTA button interaction |
+| `trackSearch` | `(query: string) => void` | Search query |
 
 ---
 
-### Server / build entry
+### Raw API helpers (server / build safe)
 
-The default entry (`@arthurreira/analytics`) exports the raw API helpers — safe to import in server components or build scripts because it contains no browser globals.
+The default entry exports the low-level functions with no browser globals — safe to import in server components or Node.js scripts.
 
 ```ts
 import {
@@ -113,47 +198,89 @@ import {
 } from '@arthurreira/analytics'
 ```
 
+All helpers take `(apiUrl, apiKey, sessionId, ...)` as their first arguments and call your backend directly via `fetch`.
+
 ---
 
-## Session management
+### Presence (real-time WebSocket)
+
+Optional live-visitor presence tracking over WebSocket.
 
-Sessions are created automatically on first load and stored in `localStorage` (`af_session_id`). A session expires after **30 minutes of inactivity**. When the user leaves or hides the tab the SDK fires a `sendBeacon` to close the session gracefully.
+```ts
+import { connectPresence, DEFAULT_WS_URL } from '@arthurreira/analytics'
+import type { PresenceConnection } from '@arthurreira/analytics'
 
-Visitor identity is persisted across sessions via `af_analytics_visitor_id` (a random UUID stored in `localStorage`).
+const conn: PresenceConnection = connectPresence(apiKey, sessionId, DEFAULT_WS_URL)
+
+// later
+conn.disconnect()
+```
+
+The connection retries up to 3 times with exponential back-off on unexpected close. When used via the `<Analytics />` component or `useAnalytics`, presence connects automatically and disconnects on session end.
 
 ---
 
-## Data collected
+## Package exports
 
-On session start the SDK sends:
+| Import path | Format | Contents | Use in |
+| --- | --- | --- | --- |
+| `@arthurreira/analytics` | ESM | Raw API helpers + presence (no browser globals) | Server / Node |
+| `@arthurreira/analytics/client` | ESM | `Analytics` component + `useAnalytics` hook | React client |
+| `dist/af-analytics.umd.js` | IIFE | Self-contained auto-tracking script | Any HTML page |
 
-- Visitor ID, language, timezone
-- Screen / viewport dimensions
-- Referrer URL, landing page
-- UTM parameters (`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`)
+---
 
-On each event:
+## Session management
 
-- `session_id`, `event_type`, `path`, `page_url`
-- Event-specific fields (position, element, scroll depth, error stack, etc.)
+- A session is created on first load and stored in `localStorage` (`af_session_id`).
+- Sessions expire after **30 minutes of inactivity**.
+- On tab hide (`visibilitychange → hidden`) or page unload (`beforeunload`) the SDK calls `navigator.sendBeacon` to close the session gracefully — no events are dropped.
+- Visitor identity persists across sessions via `af_analytics_visitor_id` (a random UUID in `localStorage`).
 
 ---
 
-## Environment variables
+## Data collected
 
-| Variable                    | Description                                             |
-| --------------------------- | ------------------------------------------------------- |
-| `NEXT_PUBLIC_ANALYTICS_URL` | Backend base URL, e.g. `https://analytics.example.com/api` |
-| `NEXT_PUBLIC_ANALYTICS_KEY` | Project API key (Bearer token)                          |
+### On session start
+
+| Field | Description |
+| --- | --- |
+| `visitor_id` | Persistent anonymous UUID |
+| `language` | `navigator.language` |
+| `screen_width / height` | Physical screen resolution |
+| `viewport_width / height` | Current browser viewport |
+| `referrer` | `document.referrer` |
+| `landing_page` | `window.location.pathname` |
+| `timezone` | IANA timezone string |
+| `cpu_threads` | `navigator.hardwareConcurrency` |
+| `memory_gb` | `navigator.deviceMemory` (Chrome only) |
+| `gpu` | WebGL unmasked renderer string |
+| `network_type` | `effectiveType` from Network Information API |
+| `connection_speed_mbps` | `downlink` from Network Information API |
+| `utm_source/medium/campaign/term/content` | UTM parameters from the landing URL |
+
+### On each event
+
+`session_id`, `event_type`, `path`, `page_url`, plus event-specific fields:
+
+| Event | Extra fields |
+| --- | --- |
+| `pageview` | `page_title`, `referrer`, `scroll_depth: 0` |
+| `click` | `x_position`, `y_position`, `element_id`, `element_class`, `element_text` |
+| `scroll` | `scroll_depth` (25 / 50 / 75 / 100) |
+| `copy` | `copied_text` (up to 200 chars) |
+| `error` | `error_message`, `stack_trace` |
+| `cta_click` | `cta_id`, `cta_variant` |
+| `search` | `search_query` |
 
 ---
 
-## Package exports
+## Environment variables (Next.js)
 
-| Import path                      | Contents                                    | Use in            |
-| -------------------------------- | ------------------------------------------- | ----------------- |
-| `@arthurreira/analytics`         | Raw API helpers (no browser globals)        | Server / build    |
-| `@arthurreira/analytics/client`  | `Analytics` component + `useAnalytics` hook | Client components |
+| Variable | Description |
+| --- | --- |
+| `NEXT_PUBLIC_ANALYTICS_URL` | Backend base URL, e.g. `https://analytics.example.com` |
+| `NEXT_PUBLIC_ANALYTICS_KEY` | Project API key |
 
 ---
 
@@ -164,9 +291,17 @@ pnpm install
 pnpm build
 ```
 
+Outputs:
+
+| File | Format | Entry |
+| --- | --- | --- |
+| `dist/index.js` + `dist/index.d.ts` | ESM | `src/index.ts` |
+| `dist/client.js` + `dist/client.d.ts` | ESM | `src/client.ts` |
+| `dist/af-analytics.umd.js` | IIFE/UMD | `src/vanilla.ts` |
+
 ## Publishing
 
-Tag a release (e.g. `v0.5.0`) after adding an `NPM_TOKEN` secret to the repository to trigger the CI publish workflow.
+Tag a release after adding an `NPM_TOKEN` secret to the repository to trigger the CI publish workflow.
 
 ---
 

package/dist/af-analytics.umd.js

@@ -0,0 +1,245 @@
+"use strict";
+var AfAnalytics = (() => {
+  var __defProp = Object.defineProperty;
+  var __defProps = Object.defineProperties;
+  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+  var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+  var __getOwnPropNames = Object.getOwnPropertyNames;
+  var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+  var __hasOwnProp = Object.prototype.hasOwnProperty;
+  var __propIsEnum = Object.prototype.propertyIsEnumerable;
+  var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+  var __spreadValues = (a, b) => {
+    for (var prop in b || (b = {}))
+      if (__hasOwnProp.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    if (__getOwnPropSymbols)
+      for (var prop of __getOwnPropSymbols(b)) {
+        if (__propIsEnum.call(b, prop))
+          __defNormalProp(a, prop, b[prop]);
+      }
+    return a;
+  };
+  var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+  var __export = (target, all) => {
+    for (var name in all)
+      __defProp(target, name, { get: all[name], enumerable: true });
+  };
+  var __copyProps = (to, from, except, desc) => {
+    if (from && typeof from === "object" || typeof from === "function") {
+      for (let key of __getOwnPropNames(from))
+        if (!__hasOwnProp.call(to, key) && key !== except)
+          __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+    }
+    return to;
+  };
+  var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+  // src/vanilla.ts
+  var vanilla_exports = {};
+  __export(vanilla_exports, {
+    init: () => init
+  });
+  var _currentScript = document.currentScript;
+  var SESSION_EXPIRY_MS = 30 * 60 * 1e3;
+  function readConfig() {
+    var _a, _b, _c, _d;
+    const script = _currentScript != null ? _currentScript : document.querySelector("script[data-api-key]");
+    const apiKey = (_b = (_a = script == null ? void 0 : script.dataset.apiKey) == null ? void 0 : _a.trim()) != null ? _b : "";
+    const apiUrl = ((_d = (_c = script == null ? void 0 : script.dataset.url) == null ? void 0 : _c.trim()) != null ? _d : "").replace(/\/$/, "");
+    if (!apiKey || !apiUrl) return null;
+    return { apiKey, apiUrl };
+  }
+  function generateId() {
+    if (typeof crypto !== "undefined" && crypto.randomUUID) {
+      return crypto.randomUUID();
+    }
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+      const r = Math.random() * 16 | 0;
+      const v = c === "x" ? r : r & 3 | 8;
+      return v.toString(16);
+    });
+  }
+  function getVisitorId() {
+    const stored = localStorage.getItem("af_analytics_visitor_id");
+    if (stored) return stored;
+    const id = generateId();
+    localStorage.setItem("af_analytics_visitor_id", id);
+    return id;
+  }
+  function getStoredSession() {
+    const id = localStorage.getItem("af_session_id");
+    const lastActivity = localStorage.getItem("af_session_last_activity");
+    if (!id || !lastActivity) return null;
+    if (Date.now() - parseInt(lastActivity, 10) < SESSION_EXPIRY_MS) return id;
+    return null;
+  }
+  function touchSession() {
+    localStorage.setItem("af_session_last_activity", String(Date.now()));
+  }
+  function clearSession() {
+    localStorage.removeItem("af_session_id");
+    localStorage.removeItem("af_session_last_activity");
+  }
+  function getGpu() {
+    try {
+      const canvas = document.createElement("canvas");
+      const gl = canvas.getContext("webgl");
+      if (!gl) return null;
+      const ext = gl.getExtension("WEBGL_debug_renderer_info");
+      if (!ext) return null;
+      return gl.getParameter(ext.UNMASKED_RENDERER_WEBGL);
+    } catch (e) {
+      return null;
+    }
+  }
+  function send(apiUrl, apiKey, payload) {
+    fetch(`${apiUrl}/events`, {
+      method: "POST",
+      headers: { "X-API-Key": apiKey, "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+      keepalive: true
+    }).catch(() => {
+    });
+  }
+  function baseFields(sessionId, eventType) {
+    return {
+      session_id: sessionId,
+      event_type: eventType,
+      path: window.location.pathname,
+      page_url: window.location.href
+    };
+  }
+  async function createRemoteSession(apiUrl, apiKey, visitorId) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m;
+    const nav = navigator;
+    const conn = (_c = (_b = (_a = nav["connection"]) != null ? _a : nav["mozConnection"]) != null ? _b : nav["webkitConnection"]) != null ? _c : null;
+    const params = new URLSearchParams(window.location.search);
+    const body = {
+      visitor_id: visitorId,
+      language: (_d = navigator.language) != null ? _d : null,
+      screen_width: (_e = screen.width) != null ? _e : null,
+      screen_height: (_f = screen.height) != null ? _f : null,
+      viewport_width: (_g = window.innerWidth) != null ? _g : null,
+      viewport_height: (_h = window.innerHeight) != null ? _h : null,
+      referrer: document.referrer || null,
+      landing_page: window.location.pathname,
+      timezone: (_i = Intl.DateTimeFormat().resolvedOptions().timeZone) != null ? _i : null,
+      cpu_threads: (_j = navigator.hardwareConcurrency) != null ? _j : null,
+      memory_gb: (_k = nav["deviceMemory"]) != null ? _k : null,
+      gpu: getGpu(),
+      network_type: (_l = conn == null ? void 0 : conn["effectiveType"]) != null ? _l : null,
+      connection_speed_mbps: (_m = conn == null ? void 0 : conn["downlink"]) != null ? _m : null,
+      utm_source: params.get("utm_source"),
+      utm_medium: params.get("utm_medium"),
+      utm_campaign: params.get("utm_campaign"),
+      utm_term: params.get("utm_term"),
+      utm_content: params.get("utm_content")
+    };
+    const res = await fetch(`${apiUrl}/sessions`, {
+      method: "POST",
+      headers: { "X-API-Key": apiKey, "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    const data = await res.json();
+    return data.id;
+  }
+  async function getOrCreateSession(apiUrl, apiKey) {
+    const stored = getStoredSession();
+    if (stored) {
+      touchSession();
+      return stored;
+    }
+    const id = await createRemoteSession(apiUrl, apiKey, getVisitorId());
+    localStorage.setItem("af_session_id", id);
+    localStorage.setItem("af_session_last_activity", String(Date.now()));
+    return id;
+  }
+  function trackPageview(apiUrl, apiKey, sessionId) {
+    send(apiUrl, apiKey, __spreadProps(__spreadValues({}, baseFields(sessionId, "pageview")), {
+      page_title: document.title || null,
+      referrer: document.referrer || null,
+      scroll_depth: 0
+    }));
+  }
+  function trackClick(apiUrl, apiKey, sessionId, e) {
+    var _a;
+    const el = e.target;
+    send(apiUrl, apiKey, __spreadProps(__spreadValues({}, baseFields(sessionId, "click")), {
+      x_position: e.clientX,
+      y_position: e.clientY,
+      element_id: el.id || null,
+      element_class: el.className || null,
+      element_text: ((_a = el.innerText) == null ? void 0 : _a.slice(0, 100)) || null
+    }));
+  }
+  function trackScroll(apiUrl, apiKey, sessionId, depth) {
+    send(apiUrl, apiKey, __spreadProps(__spreadValues({}, baseFields(sessionId, "scroll")), { scroll_depth: depth }));
+  }
+  function trackError(apiUrl, apiKey, sessionId, error) {
+    send(apiUrl, apiKey, __spreadProps(__spreadValues({}, baseFields(sessionId, "error")), {
+      error_message: error.message,
+      stack_trace: error.stack || null
+    }));
+  }
+  function init() {
+    const config = readConfig();
+    if (!config) return;
+    const { apiKey, apiUrl } = config;
+    let sessionId = null;
+    const pending = [];
+    let sessionEnded = false;
+    let lastScrollDepth = 0;
+    function enqueue(fn) {
+      if (sessionId) {
+        touchSession();
+        fn(sessionId);
+      } else {
+        pending.push(fn);
+      }
+    }
+    getOrCreateSession(apiUrl, apiKey).then((id) => {
+      sessionId = id;
+      pending.splice(0).forEach((fn) => fn(id));
+    }).catch(() => {
+    });
+    enqueue((id) => trackPageview(apiUrl, apiKey, id));
+    window.addEventListener("click", (e) => {
+      enqueue((id) => trackClick(apiUrl, apiKey, id, e));
+    });
+    window.addEventListener(
+      "scroll",
+      () => {
+        const total = document.documentElement.scrollHeight - window.innerHeight;
+        if (total <= 0) return;
+        const depth = Math.round(window.scrollY / total * 100);
+        for (const milestone of [25, 50, 75, 100]) {
+          if (depth >= milestone && lastScrollDepth < milestone) {
+            lastScrollDepth = milestone;
+            enqueue((id) => trackScroll(apiUrl, apiKey, id, milestone));
+          }
+        }
+      },
+      { passive: true }
+    );
+    window.addEventListener("error", (e) => {
+      enqueue((id) => trackError(apiUrl, apiKey, id, new Error(e.message)));
+    });
+    const endSession = () => {
+      if (!sessionId || sessionEnded) return;
+      sessionEnded = true;
+      navigator.sendBeacon(`${apiUrl}/sessions/${sessionId}/end`);
+      clearSession();
+    };
+    document.addEventListener("visibilitychange", () => {
+      if (document.visibilityState === "hidden") endSession();
+    });
+    window.addEventListener("beforeunload", endSession);
+  }
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", init);
+  } else {
+    init();
+  }
+  return __toCommonJS(vanilla_exports);
+})();

package/package.json

@@ -1,5 +1,5 @@
   {  "name": "@arthurreira/analytics",
-    "version": "0.11.0",
+    "version": "0.12.0",
     "type": "module",
     "scripts": {
       "build": "tsup",