nanalytics-tracker

Privacy-respecting, self-hosted analytics tracker using Context VM and Nostr.

Overview

This is a lightweight browser tracker that sends page view events to your own Context VM backend via Nostr relays. All data is end-to-end encrypted using NIP-44.

Key features:

• Self-hosted - you control your analytics data
• Privacy-respecting - no cookies, no personal data
• End-to-end encrypted via NIP-44
• ~79KB browser bundle

Prerequisites

Before using this tracker, you need:

1. A Context VM backend running the nanalytics server
2. Your CVM's public key (64 character hex string)
3. A Site UUID - generate one for each website you want to track

Installation

Script Tag (easiest)

Add this before </body> on every page you want to track:

<script
  src="https://unpkg.com/nanalytics-tracker/dist/index.global.js"
  data-site-uuid="YOUR_SITE_UUID"
  data-cvm-pubkey="YOUR_CVM_PUBKEY"
></script>

With Custom Relays

If you're running your own Nostr relays:

<script
  src="https://unpkg.com/nanalytics-tracker/dist/index.global.js"
  data-site-uuid="YOUR_SITE_UUID"
  data-cvm-pubkey="YOUR_CVM_PUBKEY"
  data-relays="wss://your-relay.com,wss://backup-relay.com"
></script>

NPM (for bundled apps)

npm install nanalytics-tracker

import { init, trackPageView } from 'nanalytics-tracker';

init({
  siteUuid: 'YOUR_SITE_UUID',
  cvmPubkey: 'YOUR_CVM_PUBKEY',
  relays: ['wss://your-relay.com'], // optional
  onTrack: (success) => console.log('Tracked:', success) // optional
});

// For SPAs, manually track route changes:
trackPageView('/new-route');

Configuration

Option	Required	Description
data-site-uuid / siteUuid	Yes	Unique identifier for your website (UUID format)
data-cvm-pubkey / cvmPubkey	Yes	Your Context VM server's public key (64 hex chars)
data-relays / relays	No	Comma-separated relay URLs (defaults to wss://relay.contextvm.org, wss://cvm.otherstuff.ai)
onTrack	No	Callback fired after each track attempt (JS API only)

What's Tracked

Each page view sends:

Field	Description
siteUuid	Your site identifier
pagePath	Current page pathname (e.g., /, /about)
deviceType	desktop, mobile, or tablet

Not tracked: IP addresses, cookies, personal data, referrer (planned for future)

How It Works

1. On page load, the tracker collects the page path and device type
2. Generates an ephemeral keypair (discarded after use)
3. Creates a JSON-RPC record_visit tool call
4. Encrypts the message using NIP-44 (gift wrap)
5. Publishes to configured Nostr relays
6. Your CVM backend receives and decrypts the event

Features

• Auto-tracks on page load - no code required for static sites
• Debounces duplicates - ignores rapid refreshes (5s window)
• Fire-and-forget - doesn't block page rendering
• End-to-end encrypted - only your CVM can read the data
• No cookies - compliant with privacy regulations

Self-Hosting Guide

See docs/install_on_your_site.md for detailed setup instructions.

License

MIT