Tracking Script

The TideMeter tracking script (@tidemeter/tracker) is an ultra-lightweight analytics tracker that collects page view data without using cookies or collecting personal information.

Installation

Add the tracking script to your website’s HTML:

<script
  defer
  data-website-id="your-website-id"
  src="https://your-tidemeter-instance.com/t.js"
></script>

Place this just before the closing </body> tag for optimal performance.

How It Works

The tracker:

1. Listens for page load and navigation events
2. Collects anonymous page view data (URL, referrer, screen size, language)
3. Sends a POST request to /api/collect on your TideMeter instance via navigator.sendBeacon() (with fetch + keepalive as fallback)
4. Never creates cookies, uses local storage, or fingerprints visitors

Data Collected

Each page view event includes:

What’s NOT Collected

• IP addresses (not sent by the tracker; hashed server-side then discarded)
• Cookies or local storage values
• User accounts or login info
• Form data or page content
• Mouse movements or keypresses

Configuration Attributes

Example: Custom API Endpoint

<script
  defer
  data-website-id="your-website-id"
  data-host-url="https://analytics.example.com"
  src="https://your-tidemeter-instance.com/t.js"
></script>

Example: Manual Tracking

<script
  defer
  data-website-id="your-website-id"
  data-auto-track="false"
  src="https://your-tidemeter-instance.com/t.js"
></script>
 
<script>
  // Track a page view manually
  tidemeter.track();
</script>

Example: Custom Events

<script>
  // Track a named event with properties
  tidemeter.track("signup", { plan: "pro" });
 
  // Identify a user (links anonymous visitor to known user ID)
  tidemeter.identify("user-id-123");
</script>

Example: Domain Restriction

<script
  defer
  data-website-id="your-website-id"
  data-domains="example.com,app.example.com"
  src="https://your-tidemeter-instance.com/t.js"
></script>

Public API

The tracker exposes a global tidemeter object:

// Track a page view (auto-called on load if data-auto-track is true)
tidemeter.track();
 
// Track a named event with optional properties
tidemeter.track("signup", { plan: "pro" });
 
// Identify a user (links anonymous visitor to a known user ID)
tidemeter.identify("user-id-123");

SPA Support

TideMeter automatically detects Single Page Application (SPA) navigation by listening to the browser’s popstate event and intercepting History.pushState/replaceState methods. No additional configuration needed for:

• Next.js
• React Router
• Vue Router
• SvelteKit
• Any framework using the History API

Bot Detection

The tracker checks navigator.webdriver to skip tracking for automated browsers. Server-side, additional bot detection filters requests based on User-Agent regex patterns matching common bots, crawlers, and spiders.

Performance

The tracker is designed to have zero impact on your site’s performance:

• Size: ~1.5KB gzipped (compared to ~45KB for Google Analytics)
• Loading: Uses defer attribute, never blocks rendering
• Network: Uses navigator.sendBeacon() for non-blocking requests (falls back to fetch with keepalive)
• CPU: Minimal JavaScript execution
• No external dependencies: Self-contained IIFE bundle

Content Security Policy (CSP)

If you use a Content Security Policy, add the following directives:

script-src 'self' https://your-tidemeter-instance.com;
connect-src 'self' https://your-tidemeter-instance.com;

Building the Tracker

To build the tracker from source:

# From the monorepo root
pnpm --filter @tidemeter/tracker build
 
# Watch mode
pnpm --filter @tidemeter/tracker dev

The build uses Rollup with TypeScript and Terser for minification, outputting a single dist/t.js file.

The built script will be available in the packages/tracker/dist/ directory.