@myhallpass/analytics

Privacy-first, no-cookie analytics tracking snippet for Hallpass Analytics.

Installation

Script tag (drop-in, no build step)

<script src="https://your-cdn-or-host/hallpass-analytics.iife.js"></script>
<script>
  hallpassAnalytics.init({
    apiKey: 'your-site-api-key',
    apiUrl: 'https://your-analytics-api.com'
  });
</script>

Place before the closing </body> tag.

NPM

npm install hallpass-analytics

import hallpassAnalytics from 'hallpass-analytics';

hallpassAnalytics.init({
  apiKey: 'your-site-api-key',
  apiUrl: 'https://your-analytics-api.com'
});

Configuration

hallpassAnalytics.init({
  apiKey: string;       // Required — your site's API key
  apiUrl: string;       // Required — base URL of the analytics API (no trailing slash)
  trackOnLoad?: boolean // Optional — auto-track pageview on init (default: true)
});

Usage

Automatic pageview tracking

By default, init() tracks a pageview immediately. No additional code needed for standard multi-page sites.

Manual pageview tracking (SPA route changes)

For React, Vue, Next.js, or other SPAs, call trackPageView() after each route change:

// React Router example
router.on('routeChange', () => {
  hallpassAnalytics.trackPageView();
});

// Next.js App Router example
// Call in a useEffect that watches usePathname()
useEffect(() => {
  hallpassAnalytics.trackPageView();
}, [pathname]);

Custom event tracking

// Simple event
hallpassAnalytics.trackEvent('cta_click');

// Event with metadata
hallpassAnalytics.trackEvent('form_submit', {
  formId: 'contact',
  success: true
});

hallpassAnalytics.trackEvent('video_play', {
  videoId: 'intro-tour',
  duration: 120
});

How it works

• Sends data via fetch with keepalive: true — non-blocking, survives page navigation
• No cookies, no localStorage, no fingerprinting on the client side
• Visitor identity is hashed server-side from IP + User-Agent + domain + date
• The hash rotates every UTC midnight — no cross-day tracking

Building from source

npm install
npm run build        # outputs to /dist
npm run build:watch  # watch mode
npm run typecheck    # type check without building

Output files

| File | Format | Use case | |---|---|---| | dist/hallpass-analytics.esm.js | ESM | NPM / modern bundlers | | dist/hallpass-analytics.cjs.js | CJS | Older Node/bundler toolchains | | dist/hallpass-analytics.iife.js | IIFE | Script tag — self-contained | | dist/types/ | .d.ts | TypeScript type definitions |