@webticks/node

Node.js server-side tracking for WebTicks analytics.

Installation

npm install @webticks/node

Quick Start

import { createServerTracker } from '@webticks/node';

const tracker = createServerTracker({
  serverUrl: 'https://your-api.com/track',
  appId: 'your-app-id'
});

// Use middleware for automatic request tracking (recommended)
app.use(tracker.middleware());

Best Practices: Environment Variables

For security and flexibility, it is highly recommended to source your configuration from environment variables.

const tracker = createServerTracker({
  serverUrl: process.env.WEBTICKS_SERVER_URL,
  appId: process.env.WEBTICKS_APP_ID
});

Express Middleware Integration

The tracker.middleware() helper automatically captures request details (method, path, headers) and batches them for efficient delivery to your WebTicks API.

import express from 'express';
import { createServerTracker } from '@webticks/node';

const app = express();
const tracker = createServerTracker({
  serverUrl: process.env.WEBTICKS_SERVER_URL,
  appId: process.env.WEBTICKS_APP_ID
});

// Captures all requests automatically
app.use(tracker.middleware());

Custom Events + Auto-Tracking

By default, both your custom event AND the server_request are tracked. This gives you complete analytics:

app.post('/api/checkout', (req, res) => {
  tracker.trackEvent('checkout_completed', { total: 99.99 });
  // Both 'checkout_completed' AND 'server_request' are recorded
  res.json({ success: true });
});

Controlling Auto-Tracking

By default, both your custom event AND the server_request are tracked.

To skip auto-tracking (only record your custom event), use isAutoTracked: true:

// Only custom event (auto-tracking skipped)
tracker.trackEvent('checkout', { total: 99.99 }, { isAutoTracked: true, req });

API

createServerTracker(config)

| Option | Type | Description | |--------|------|-------------| | serverUrl | string | Required. URL to send analytics. | | appId | string | Required. Your application ID. | | debug | boolean | Optional. Enable console logging for debugging. Defaults to false. |

[!NOTE] appId and serverUrl are typically provided by the webticks-api project, which you can self-host. Alternatively, you can use any backend that implements the WebTicks ingestion API.

License

MPL-2.0