Nightgaunt

A lightweight, self-contained, vanilla JavaScript event tracking library.

Features

• Zero Dependencies: Pure vanilla JS.
• Efficient: Batched event sending with retry logic.
• Reliable: Handles network failures and retries automatically.
• Privacy-Focused: Built-in support for consent management and anonymization.
• Auto-Tracking: Optional automatic tracking for page views, clicks, form submissions, and page performance.
• Session Management: Automatic session tracking with 30-minute inactivity timeout.

Installation

Direct Include (Browser)

Include the script directly in your HTML. You can use the minified version for production.

<script src="dist/nightgaunt.min.js"></script>

NPM / Bundlers

If you are using a bundler like Webpack, Rollup, or Vite:

npm install nightgaunt

import Nightgaunt from 'nightgaunt';

Usage

Initialization

Initialize the tracker with your configuration.

const tracker = new Nightgaunt({
    appId: 'my-app-id',
    namespace: 'marketing-site',
    endpoint: 'https://api.my-analytics.com/events',
    
    // Optional Configuration
    batchSize: 10,           // Flush after 10 events (default: 10)
    flushInterval: 5000,     // Flush every 5 seconds (default: 5000ms)
    consent: true,           // Start with consent granted (default: true)
    anonymize: false,        // Start in anonymous mode (default: false)
    
    // Auto-tracking configuration (default: all true)
    autoTrack: {
        pageView: true,
        buttonClick: true,
        linkClick: true,
        formSubmit: true,
        performance: true
    }
});

Tracking Custom Events

Track specific user actions with custom data.

tracker.track('signup_button_clicked', {
    plan: 'pro',
    source: 'homepage_banner'
});

Note: You can pass a string value instead of an object if needed, though an object is recommended for structured data.

tracker.track('search', 'query_string');

Privacy & Consent

Managing Consent

To comply with GDPR/CCPA, you can disable tracking until the user consents.

// Disable tracking (e.g., user declines cookies)
tracker.setConsent(false);

// Enable tracking (e.g., user accepts cookies)
tracker.setConsent(true);

When consent is revoked (false), the tracker stops processing events, clears the current queue, and will not send any data.

Anonymization

For users who want more privacy or for specific compliance modes, you can enable anonymization.

// Enable anonymous mode
tracker.setAnonymize(true);

In Anonymous Mode:

• User IDs and Session IDs are stored in-memory only.
• No cookies are set.
• No localStorage is used.
• All IDs are lost when the page is reloaded.

Auto-Tracking

Nightgaunt can automatically track common interactions. You can configure this during initialization.

const tracker = new Nightgaunt({
    /* ... other config ... */
    autoTrack: {
        pageView: true,      // Track page loads
        buttonClick: true,   // Track button clicks
        linkClick: true,     // Track link clicks
        formSubmit: true,    // Track form submissions
        performance: true    // Track page load performance metrics (see below)
    }
});

To disable auto-tracking entirely, pass autoTrack: false or omit the keys you don't want.

Performance Tracking

When performance: true, a page_performance event is sent after the page load event fires. The context object contains timing metrics (in milliseconds) derived from the Navigation Timing API:

| Field | Description | |---|---| | dns_lookup | DNS resolution time | | tcp_connect | TCP connection time | | tls_handshake | TLS handshake time (0 for HTTP) | | ttfb | Time to first byte | | content_download | Response body download time | | dom_interactive | Time until DOM is interactive | | dom_complete | Time until DOM is fully parsed | | page_load | Total page load time | | transfer_size | Total transfer size in bytes | | encoded_size | Encoded (compressed) body size in bytes | | decoded_size | Decoded (uncompressed) body size in bytes |

Event Schema

Every event sent to your endpoint will have the following JSON structure:

{
  "EventID": "uuid-v4",
  "CookieID": "uuid-v4",          // Persistent User ID (or memory ID if anonymous)
  "SessionID": "uuid-v4",         // Session ID (rotates after 30m inactivity)
  "DeviceCreated": "ISO-8601",    // Client timestamp when event occurred
  "DeviceSent": "ISO-8601",       // Client timestamp when batch was sent
  "DeviceTimezone": "String",     // e.g., "America/New_York"
  "EventGroup": "String",         // Namespace defined in config
  "EventLabel": "String",         // Event name
  "EventValue": "String",         // Optional primary value
  "ExtraContext": Boolean,        // True if ContextB64 is present
  "ContextB64": "String"          // Base64 encoded JSON context object
}

License

MIT