trackrv0.3.0trackr.casoon.de

Overview

What trackr does, where it stops, and how this documentation is organised.

@casoon/trackr collects pageviews and custom events from a website and stores them on infrastructure you run. It has two halves: a browser client (init(), track()) that sends events with sendBeacon, and a server handler (createHandler()) that filters bots, removes personal data, adds a daily session ID and device details, and passes the event to a storage adapter.

How it works

Focus
How trackr works
How trackr worksThe browser script on your site sends pageviews and events to an endpoint on your own server. The handler there drops bots and personal data and passes the event to the storage you configured: Postgres, a webhook, an HTTP API or GA4. A tracking pixel takes the same path without JavaScript.Browser script → Handler on your server: pageviews, eventsTracking pixel → Handler on your server: pageviewHandler on your server → Storage you chooseStorage you choose → PostgresStorage you choose → WebhookStorage you choose → HTTP APIStorage you choose → GA4pageviews, eventspageviewBrowser script – on your website, no cookiesBrowser scripton your website, no cookiesTracking pixel – email, no JavaScriptTracking pixelemail, no JavaScriptHandler on your server – removes bots and personal dataHandler on your serverremoves bots and personal dataStorage you choose – one, several, or batchedStorage you chooseone, several, or batchedPostgresPostgresWebhookWebhookHTTP APIHTTP APIGA4 – sent from your serverGA4sent from your server

Source: src/client/index.ts, src/server/index.ts, src/server/pixel.ts, src/storage/

Show chart data
Data for How trackr works
StepKindLeads to
Browser scriptstartHandler on your server (pageviews, events)
Tracking pixelstartHandler on your server (pageview)
Handler on your serverstepStorage you choose
Storage you choosestepPostgres, Webhook, HTTP API, GA4
Postgresend
Webhookend
HTTP APIend
GA4external
Focus
How trackr works
How trackr worksThe browser script on your site sends pageviews and events to an endpoint on your own server. The handler there drops bots and personal data and passes the event to the storage you configured: Postgres, a webhook, an HTTP API or GA4. A tracking pixel takes the same path without JavaScript.Browser script → Handler on your server: pageviews, eventsTracking pixel → Handler on your server: pageviewHandler on your server → Storage you chooseStorage you choose → PostgresStorage you choose → WebhookStorage you choose → HTTP APIStorage you choose → GA4pageviews, eventspageviewBrowser script – on your website, no cookiesBrowser scripton your website, no cookiesTracking pixel – email, no JavaScriptTracking pixelemail, no JavaScriptHandler on your server – removes bots and personal dataHandler on your serverremoves bots and personal dataStorage you choose – one, several, or batchedStorage you chooseone, several, or batchedPostgresPostgresWebhookWebhookHTTP APIHTTP APIGA4 – sent from your serverGA4sent from your server

Source: src/client/index.ts, src/server/index.ts, src/server/pixel.ts, src/storage/

Show chart data
Data for How trackr works
StepKindLeads to
Browser scriptstartHandler on your server (pageviews, events)
Tracking pixelstartHandler on your server (pageview)
Handler on your serverstepStorage you choose
Storage you choosestepPostgres, Webhook, HTTP API, GA4
Postgresend
Webhookend
HTTP APIend
GA4external
  1. Browser script. init() sends a pageview on load and on every pushState, replaceState, popstate and hashchange; track() sends custom events. Events go out with sendBeacon, with fetch and keepalive as fallback. The script sets no cookies and uses neither localStorage nor sessionStorage.
  2. Handler. createHandler() answers anything but POST with 405. With botFilter, it answers bots with 200 OK and stores nothing. It checks type, url and ts, then applies the privacy options (stripPii, stripQueryParams), derives the daily session ID from a hash of anonymized IP, User-Agent and date, and detects device, browser and OS. The IP and the full User-Agent are not part of the stored event. Details: Privacy.
  3. Storage. The event goes to storage.save(): Postgres, an HTTP API, an HMAC-signed webhook, or GA4 via the Measurement Protocol. multi() passes it to several adapters, batch() buffers events and flushes by size or time. Details: Storage adapters.

The tracking pixel (createPixelHandler()) applies the same bot filter, privacy options and session ID for pages and emails without JavaScript, but detects no device, browser or OS. See Tracking pixel.

What it covers

  • Pageviews, including navigation in single-page apps, and custom events with properties.
  • UTM parameters (utm_source, utm_medium, utm_campaign, utm_term, utm_content).
  • Device class, browser and operating system, detected from the User-Agent on the server.
  • Storage in Postgres, forwarding to a webhook, an HTTP API or GA4, fan-out and batching.
  • A tracking pixel for contexts without JavaScript.

Where it stops

  • trackr stores events; it does not ship a reporting UI. The Postgres guide has SQL for common reports, and a separate dashboard runs at trackr-dashboard.casoon.dev.
  • The country field exists on events and in the table, but the handler does not fill it.
  • Bot detection is a list of User-Agent patterns plus two header checks, not a bot-management service.

How the docs are organised

The product page is trackr.casoon.de.

Edit this page on GitHub · Docs for v0.3.0