@atmosfer/impressions

Lightweight impressions tracker with a small React hook wrapper. The tracker captures page views and custom events, enriches them with basic page/device context, and sends them to a configured endpoint.

Install

npm install @atmosfer/impressions

Peer dependency: React 18+ (for the hook).

Usage (vanilla)

import { createTracker } from "@atmosfer/impressions";

const tracker = createTracker({
  endpoint: "https://example.com/impressions",
  restaurantId: "resto_123",
  tableNo: 12,
  headers: { "x-api-key": "secret" },
  debug: true,
});

// Track a page view
await tracker.page();

// Track a custom event
await tracker.track("menu_opened", { section: "drinks" });

Usage (React)

import { useImpressions } from "@atmosfer/impressions";

export function MenuPage() {
  const tracker = useImpressions({
    endpoint: "https://example.com/impressions",
    restaurantId: "resto_123",
    tableNo: 12,
  });

  return (
    <button onClick={() => void tracker.track("cta_click", { id: "order" })}>
      Order now
    </button>
  );
}

API

createTracker(config)

Creates a tracker instance. In non-browser environments (no window), the tracker becomes a no-op, which keeps SSR safe.

Config fields:

• endpoint (string, required): where events are POSTed.
• restaurantId (string, required): logical tenant identifier.
• tableNo (number, optional): table number context.
• headers (object, optional): extra headers for the POST request.
• debug (boolean, optional): logs events to console when true.
• disable (boolean, optional): start in disabled mode.
• anonIdKey (string, optional): localStorage key for anonymous user id.

Returns a Tracker with:

• page(detail?): send a page_view.
• track(eventType, detail?): send a custom event.
• setContext({ restaurantId, tableNo }): update context.
• disable() / enable(): toggle event sending.

useImpressions(config, options?)

React hook that memoizes a tracker and sends a page_view when the page becomes visible.

Options:

• trackOnMount (boolean, optional): send a single page_view when the page first becomes visible. Defaults to true.
• trackOnPagehide (boolean, optional): send a page_view on pagehide.
• trackOnSpaNavigation (boolean, optional): send a page_view on SPA navigation (pushState, replaceState, popstate).

Event payload

Each event is sent as JSON:

{
  "schema_version": 1,
  "event_id": "uuid",
  "ts": "2025-01-01T00:00:00.000Z",
  "restaurant_id": "resto_123",
  "table_no": 12,
  "event_type": "page_view",
  "event_detail": {
    "path": "/menu?utm_source=qr",
    "referrer": "https://example.com",
    "utm": { "source": "qr", "medium": null, "campaign": null },
    "anon_id": "uuid",
    "language": "en-US",
    "timezone": "Europe/Istanbul",
    "device": { "type": "mobile" },
    "screen": { "w": 390, "h": 844 },
    "page": { "title": "Menu" }
  }
}

Additional detail fields passed to page() or track() are merged into event_detail.

Build

npm run build