@smalk/analytics

Smalk AI Analytics for Node.js — Express middleware for server-side AI bot tracking and a React component for client-side tracking.

Installation

npm install @smalk/analytics

Quick Start

1. Server-Side Tracking (Express Middleware)

Add the middleware early in your Express app to track AI bot visits server-side (ChatGPT, Perplexity, Claude, Gemini, etc.):

import express from "express";
import { smalkTracking } from "@smalk/analytics";

const app = express();

// Add Smalk tracking — fires non-blocking requests, zero latency impact
app.use(smalkTracking({
  apiKey: process.env.SMALK_API_KEY,
}));

// ... rest of your app

The middleware:

• Sends a non-blocking POST to the Smalk API on every page request
• Forwards visitor headers (User-Agent, IP, Referer) for bot detection
• Skips static assets (.css, .js, .png, etc.) and health checks automatically
• Never blocks or slows down your response (fire-and-forget with 500ms timeout)

2. Client-Side Tracking (React Component)

Add the SmalkTracker component to inject the Smalk tracker.js script:

import { SmalkTracker } from "@smalk/analytics/react";

function App() {
  return (
    <>
      <SmalkTracker projectKey="your-project-uuid" />
      {/* rest of your app */}
    </>
  );
}

Or add the script tag directly in your HTML:

<script src="https://api.smalk.ai/tracker.js?PROJECT_KEY=your-project-uuid" async></script>

3. Get Your Project Key

Use the fetchWorkspaceInfo helper to retrieve your project key from the API key:

import { fetchWorkspaceInfo } from "@smalk/analytics";

const workspace = await fetchWorkspaceInfo(
  process.env.SMALK_API_KEY,
  "https://api.smalk.ai"
);
console.log(workspace.projectKey); // UUID to use with SmalkTracker

Options

smalkTracking(options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | process.env.SMALK_API_KEY | Your Smalk API key | | apiBaseUrl | string | "https://api.smalk.ai" | API base URL | | timeout | number | 500 | Request timeout in ms | | excludePaths | string[] | [] | Additional path prefixes to skip | | debug | boolean | false | Log tracking errors to console |

<SmalkTracker />

| Prop | Type | Default | Description | |------|------|---------|-------------| | projectKey | string | required | Your Smalk project UUID | | apiBaseUrl | string | "https://api.smalk.ai" | API base URL |

Why Both Server-Side and Client-Side?

• Server-side catches AI agents (ChatGPT, Perplexity, Claude) that don't execute JavaScript
• Client-side provides browser fingerprinting and session tracking for human visitors

Both layers work together to give you complete visibility into AI and human traffic.

License

MIT — Smalk