Quickstart Integration

Integrate the 1.6 KB lightweight client beacon across Next.js App Router, Pages Router, React, Vite, or static HTML in under 60 seconds.

Next.js 14 / 15 App RouterReact 18 / 19First-Party Proxy Route

Client Beacon Installation

When your custom domain is routed via Tracium’s Edge Proxy, the client beacon is served directly as a first-party asset under the path /tracium/track.js. This guarantees full immunity against browser content-blockers and eliminates third-party DNS lookup overhead.

src/app/layout.tsx

import type { Metadata } from "next";

export const metadata: Metadata = {
  title: "Production Application",
};

return function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        {/* First-party beacon injected via Edge Proxy CNAME */}
        <script src="/tracium/track.js" defer />
      </head>
      <body>{children}</body>
    </html>
  );
}

Direct CDN Fallback (Pre-DNS Migration)

If you have not yet migrated your production DNS CNAME to proxy.tracium.dev, load the beacon from Tracium’s global CDN using your explicit project identifier:

Direct CDN script snippet

<script
  src="https://api.tracium.dev/track.js"
  data-project-id="prj_live_9f83a01bce42"
  defer
></script>

Zero Cross-Origin Blocking with CNAMENetwork Spec

Once your CNAME is activated, migrate from https://api.tracium.dev/track.js to /tracium/track.js. The edge proxy automatically binds your project identity and terminates telemetry in first-party context.

Script Attributes & Runtime Configuration

Field / Attribute	Wire Type	Constraint	Technical Description
data-project-id	string	OPTIONAL	Alphanumeric project ID. Mandatory only when executing via the direct CDN endpoint.
data-auto-track	boolean	OPTIONAL	Defaults to 'true'. Automatically binds to popstate and pushState events for SPA pageviews.
data-respect-dnt	boolean	OPTIONAL	Defaults to 'false'. When 'true', drops beacons if navigator.doNotTrack === '1'.
data-endpoint	string	OPTIONAL	Overrides default ingestion endpoint. Defaults to '/v1/track'.

Verifying Ingestion & Wire Payloads

Verify edge script delivery and telemetry ingestion using curl:

Terminal verification

# 1. Verify first-party script delivery
curl -I https://yourdomain.com/tracium/track.js

# Expected HTTP Response:
# HTTP/2 200 OK
# content-type: application/javascript; charset=utf-8
# cache-control: public, max-age=3600, stale-while-revalidate=86400
# cf-cache-status: HIT

Inspect client beacon ingestion in your browser Network tab:

POST/v1/track

HTTP/2 204 No Content

Content-Type:application/json

Cache-Control:no-store, max-age=0

X-Content-Type-Options:nosniff

{
  "project_id": "prj_live_9f83a01bce42",
  "path": "/pricing",
  "referrer": "https://news.ycombinator.com/",
  "perf": { "ttfb": 42.4, "fcp": 118.2 }
}