@antlytics/analytics

Privacy-first analytics SDK for Next.js and vanilla JS.

• No cookies for identity
• Visit ID in sessionStorage with a 30-minute idle timeout
• Sticky first-touch UTMs + referrer for the visit
• Loads the hosted tracker (/tracker.js) — SPA, engagement, and Antlytics.track() stay current on redeploy

trackingId (Next / tracker) and siteId (client helper) are the same site UUID as ingest tracking_id.

Installation

npm install @antlytics/analytics
# or
pnpm add @antlytics/analytics

Next.js App Router

Drop the <Analytics /> component into your root layout. It loads the hosted tracker via next/script (strategy="afterInteractive").

// app/layout.tsx
import { Analytics } from "@antlytics/analytics/next"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Analytics trackingId="YOUR_TRACKING_ID" />
      </body>
    </html>
  )
}

Your tracking ID is in the Antlytics dashboard under Settings → Getting Started.

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | trackingId | string | — | UUID tracking ID from your Antlytics dashboard | | apiHost | string | https://www.antlytics.com | Override if you use a first-party proxy |

Custom events

import { createAnalyticsClient } from "@antlytics/analytics"

const analytics = createAnalyticsClient({ siteId: "YOUR_TRACKING_ID" })
analytics.track("waitlist_signup", { plan: "pro" })

Or after the tracker loads: Antlytics.track("waitlist_signup") / window.antlytics.track(...).

First-party proxy (optional)

Some ad blockers block requests to third-party analytics domains. Mirror the ingest paths on your origin so pageviews, events, and engagement all forward.

1. Create proxy routes in your Next.js app:

// app/api/ingest/pageview/route.ts
export { GET, OPTIONS, POST } from "@antlytics/analytics/proxy"

// app/api/ingest/event/route.ts
import { event } from "@antlytics/analytics/proxy"
export const { GET, OPTIONS, POST } = event

// app/api/ingest/engagement/route.ts
import { engagement } from "@antlytics/analytics/proxy"
export const { GET, OPTIONS, POST } = engagement

2. Point <Analytics /> at your own domain:

<Analytics
  trackingId="YOUR_TRACKING_ID"
  apiHost="https://your-domain.com"
/>

Each handler forwards to https://www.antlytics.com/api/ingest/{kind} with the browser User-Agent and client IP (X-Antlytics-Client-Ip) and always returns 200 to the tracker.

Legacy app/api/antlytics/pageview/route.ts re-exporting the default POST still works for pageviews only — add event + engagement routes for full parity.

Vanilla / HTML

Prefer the hosted tracker (keeps SPA + idle + engagement current):

<script
  defer
  src="https://www.antlytics.com/tracker.js"
  data-tracking-id="YOUR_TRACKING_ID"
  data-api-host="https://www.antlytics.com"
></script>

Ingest API

Browser clients POST to:

| Path | Purpose | |------|---------| | /api/ingest/pageview | Navigations | | /api/ingest/event | Custom events | | /api/ingest/engagement | Scroll depth + active time |

| Field | Type | Required | Description | |-------|------|---------|-------------| | tracking_id | UUID | yes | Your site's tracking ID | | pathname | string | yes | URL path, e.g. /blog/post | | referrer | string | no | First-touch referrer for the visit | | session_id | UUID | no | Anonymous visit identifier | | utm_* | string | no | Sticky first-touch campaign fields (pageviews) |

Country and device type are detected server-side from request headers — you do not need to send them.

License

MIT © Antlytics