Events

Every interaction Clamp records is an event. Pageviews are tracked automatically. Custom events are anything you define with track().

Pageviews

Pageviews are collected automatically when you install the SDK. Each navigation (including SPA route changes) sends a pageview event with the page path, referrer, and UTM parameters.

No additional code needed. No cookies, no consent banner required.

Custom events

Track any action that matters to your product. Custom events have a name and optional properties.

import { track } from "@clamp-sh/analytics"

track("signup", { plan: "pro", source: "pricing_page" })
track("feature_used", { name: "csv_export" })

import { track } from "@clamp-sh/analytics/server"

await track("subscription_created", {
  anonymousId: "anon_abc123",
  properties: { plan: "pro", interval: "monthly" },
})

Server events require an anonymousId to link them to a browser visitor. See SDK for how to pass the ID from browser to server.

Sessions

A session groups events from a single visit. Sessions expire after 30 minutes of inactivity. The SDK manages sessions automatically.

Session data drives the bounce rate (sessions with only one pageview) and average duration metrics in the overview.

Anonymous IDs

Each browser visitor gets a random anonymous ID stored in localStorage. This ID persists across page loads but is not a cookie, not linked to any personal data, and not shared with third parties.

You can retrieve it with getAnonymousId() to link browser and server events:

import { getAnonymousId } from "@clamp-sh/analytics"

const anonId = getAnonymousId()
// Pass to your API, then use in server-side track() calls

Properties

Event properties are flat string → string maps. Nested objects, arrays, and non-string values are rejected at the API level.

What counts as an event

Every pageview and every track() call counts as one event toward your plan limit.

When you hit your event limit, new events are dropped until the next billing cycle. Existing data stays queryable regardless.

Enrichment

The API enriches each event before storage. You don't need to send any of this manually:

• Country — derived from the request IP (the IP itself is never stored)
• Device type, browser, OS — parsed from the User-Agent header
• Channel — classified from the referrer (organic_search, direct, referral, paid, email, organic_social)
• UTM parameters — extracted from the page URL query string