Frameworks

Each kit is a single TypeScript file. Copy it into your project as is.

All kits do the same three things and never block, delay or change a response:

1. Give the visit a first-party aa_sid cookie.
2. Hand the browser tracker a signed key (a meta tag on Workers, an aa_meta cookie on Next.js and Node).
3. After responding, send the request record (path, status, headers, the visitor's address) to the platform, signed with your secret.

Next.jsCopy Anchor Link

Copy next.ts to lib/agent-analytics.ts, then in proxy.ts (Next 16) or middleware.ts (Next 15):

import type { NextFetchEvent, NextRequest } from "next/server"
import { agentAnalytics } from "./lib/agent-analytics"

const analytics = agentAnalytics({ siteId: process.env.AA_SITE_ID!, secret: process.env.AA_SECRET! })

export default function proxy(req: NextRequest, ev: NextFetchEvent) {
  return analytics(req, ev)
}

export const config = { matcher: ["/((?!_next/|api/|favicon.ico|.*\\..*).*)"] }

If you already have a proxy, build your NextResponse first and pass it as the third argument: analytics(req, ev, res).

Then load the tracker in app/layout.tsx:

import Script from "next/script"

<Script src="https://agent-analytics.jacob-4fc.workers.dev/v1/t.js" data-site="site_..." strategy="afterInteractive" />

Cloudflare WorkersCopy Anchor Link

Works with any framework on Workers (Hono, React Router, Astro, plain fetch handlers). Copy edge.ts, then wrap your export:

import { withAgentAnalytics } from "./agent-analytics"

export default withAgentAnalytics({ fetch: app.fetch }, (env) => ({ siteId: env.AA_SITE_ID, secret: env.AA_SECRET }))

Set the secret with wrangler secret put AA_SECRET. The kit adds <meta name="agent-analytics"> to HTML pages for the tracker. In a React app, render <AgentAnalytics siteId="site_..." /> from react.tsx once at the top.

NodeCopy Anchor Link

Copy node.ts, then:

import { agentAnalytics } from "./agent-analytics"

app.use(agentAnalytics({ siteId: process.env.AA_SITE_ID!, secret: process.env.AA_SECRET! }))

Add the script tag to your HTML layout.

Script tag onlyCopy Anchor Link

For static sites, Shopify themes or WordPress, add the tracker to every page and skip the server kit:

<script async src="https://agent-analytics.jacob-4fc.workers.dev/v1/t.js" data-site="site_..."></script>

You still get browser behaviour, device, network and location. You do not see agents that never run JavaScript, which is most HTTP agents and scrapers, so add a server kit when you can.