What's New in Tracker.js

The Agent Analytics tracker just got a major upgrade: richer events from one script tag, clearer privacy defaults, and a public browser smoke test that proves the tracker sends what it should from a real page.

The important bit: the tracker is now more explicit. Your AI agent can still add product instrumentation quickly, but the broader browser signals are opt-in, URL-like values are sanitized before they leave the page, and identity only includes email when you call identify() with an email trait.

Here’s what’s new.

Public Browser Smoke Tests

We added a real-browser smoke suite to the open-source tracker package. It runs in GitHub Actions on every push to main.

The test boots Chromium, serves the built tracker on a local test page, captures real /track and /identify requests, and checks the browser contract end to end:

• page views send from a real page
• URL and referrer drop query strings and hashes
• UTM fields are still preserved
• identify() normalizes explicit email traits and does not send email_hash
• click, outgoing link, download, form, scroll, impression, performance, error, SPA, and 404 tracking only fire in the expected conditions
• duplicate script tags do not double-track
• oversized payloads are bounded
• collector failures do not throw into the host page

You can run the same gate locally:

npm run build
npm test
npm run test:tracker-smoke

That smoke suite is not a replacement for unit tests. It is the production confidence check: does the tracker actually behave on a page the way the docs say it behaves?

Declarative Event Tracking

You can track intentional product events without writing JavaScript. Add data-aa-event to the clickable element:

<button data-aa-event="signup" data-aa-event-plan="pro">
  Sign Up for Pro
</button>

Click the button → a signup event is tracked with {plan: "pro"}. No onclick, no window.aa?.track(), no extra script.

Add properties with data-aa-event-* attributes:

<a href="/pricing"
   data-aa-event="cta_click"
   data-aa-event-id="hero_pricing"
   data-aa-event-section="hero">
  See Pricing →
</a>

This makes it simple for your AI agent to add tracking to the elements that matter.

Privacy Defaults and URL Sanitization

The tracker now has a stricter browser privacy contract:

• page URLs and referrers omit query strings and fragments
• outgoing link, download, and form action URLs are sanitized the same way
• UTM fields are preserved as explicit attribution fields
• form field values are not collected
• browser-side email hashing is gone
• email is sent only when you explicitly pass it to identify()
• oversized string properties are truncated so payloads stay bounded

Example:

window.aa.identify('user_123', {
  email: '[email protected]',
  plan: 'pro',
  role: 'owner'
});

That sends identity through the identify endpoint. Normal event payloads should not infer or scrape email from URLs, text, form fields, or sticky properties.

Outgoing Link Tracking

Want to know when users click links to external sites? Add one attribute to your snippet:

<script src="https://api.agentanalytics.sh/tracker.js"
  data-project="my-site"
  data-token="aat_..."
  data-track-outgoing="true"></script>

Every click on an external link tracks an outgoing_link event with a sanitized URL and destination hostname. Useful for affiliate links, partner referrals, and understanding where users go next.

User Identification

You can link anonymous sessions to real users after signup or login:

// After successful signup/login
window.aa.identify('user_123', {
  email: '[email protected]',
  plan: 'pro'
});

The previous anonymous ID and the new user ID are linked server-side, so you can see what happened before and after signup. Email is explicit; the browser tracker does not infer it.

Safer Declarative Experiment Variants

Declarative experiment rendering now favors safe text replacement instead of arbitrary HTML injection. That means your agent can still test copy variants, but the default path is safer for public pages.

<div data-aa-experiment="hero_test"
     data-aa-variant-b="Ship faster with your AI agent">
  Build better with analytics your agent can read
</div>

Variant B swaps the text content. The control keeps the original content.

Forced Experiment Variants

Preview any experiment variant by adding a URL parameter:

https://my-site.com?aa_variant_hero_test=b

This forces variant B for hero_test — useful for QA, screenshots, and sharing a specific variant with your team before shipping. The forced exposure is tracked with forced: true so it can be handled separately from normal assignment.

Cross-Domain Tracking

Track users across related subdomains — app, docs, blog, and marketing — with the same anonymous ID. Quick setup:

<script src="https://api.agentanalytics.sh/tracker.js"
  data-project="my-site"
  data-token="aat_..."
  data-link-domains="yoursite.com,app.yoursite.com,docs.yoursite.com"></script>

Links between those domains carry the anonymous ID so the same visitor journey can continue across surfaces.

Do Not Track and Site Opt-Out

The tracker can respect browser-level Do Not Track and a per-site opt-out:

<script src="https://api.agentanalytics.sh/tracker.js"
  data-project="my-site"
  data-token="aat_..."
  data-do-not-track="true"></script>

Users can also opt out for the site. The tracker now scopes browser storage by project/token so one site does not accidentally control another site’s tracker state.

Performance Timing

Get real performance metrics for every page load with one attribute:

<script src="https://api.agentanalytics.sh/tracker.js"
  data-project="my-site"
  data-token="aat_..."
  data-track-performance="true"></script>

The tracker captures DNS lookup time, TCP connection time, TTFB, DOM interactive, DOM complete, and full page load time as a $performance event.

Time-on-Page Tracking

Know how long users actually spend on each page. Enable it with the heartbeat attribute:

<script src="https://api.agentanalytics.sh/tracker.js"
  data-project="my-site"
  data-token="aat_..."
  data-heartbeat="30"></script>

The tracker sends $time_on_page when users navigate away. It pauses while the tab is hidden and resumes when visible.

JS Error Tracking

Catch JavaScript errors automatically for basic error awareness:

<script src="https://api.agentanalytics.sh/tracker.js"
  data-project="my-site"
  data-token="aat_..."
  data-track-errors="true"></script>

Uncaught errors and unhandled promise rejections become $error events. They are capped and deduped so a broken page does not flood your analytics.

Global Properties (aa.set)

Set properties that attach to subsequent events:

// After login, tag later events with the user's plan
window.aa.set({ plan: 'pro', team: 'acme-corp' });

// Clear a property
window.aa.set({ plan: null });

Useful for segmenting analytics by user type, plan, team, or any dimension you care about.

Consent Management

For regions that require consent before tracking, the tracker has built-in consent management:

<script src="https://api.agentanalytics.sh/tracker.js"
  data-project="my-site"
  data-token="aat_..."
  data-require-consent="true"></script>

When enabled, events wait until consent is granted:

window.aa.grantConsent();
window.aa.revokeConsent();

Consent state is scoped and persisted. Revocation stops tracking and clears the queue.

Scroll Depth Tracking

Know how far users actually scroll:

<script src="https://api.agentanalytics.sh/tracker.js"
  data-project="my-site"
  data-token="aat_..."
  data-track-scroll-depth="true"></script>

A $scroll_depth event records the maximum scroll percentage for the page.

Content Impression Tracking

Track when specific sections become visible using data-aa-impression:

<div data-aa-impression="pricing_section"
     data-aa-impression-plan="pro">
  <!-- pricing content -->
</div>

When the element scrolls into view, an $impression event fires once for that element.

Web Vitals

Track Core Web Vitals — LCP, CLS, and INP — with:

<script src="https://api.agentanalytics.sh/tracker.js"
  data-project="my-site"
  data-token="aat_..."
  data-track-vitals="true"></script>

A $web_vitals event reports real user metrics when the browser exposes them.

File Download Tracking

Track downloadable links:

<script src="https://api.agentanalytics.sh/tracker.js"
  data-project="my-site"
  data-token="aat_..."
  data-track-downloads="true"></script>

A $download event includes the sanitized URL, filename, and extension.

Form Submission Tracking

Track form submissions without collecting field values:

<script src="https://api.agentanalytics.sh/tracker.js"
  data-project="my-site"
  data-token="aat_..."
  data-track-forms="true"></script>

A $form_submit event includes form metadata like id, name, sanitized action, method, and classes.

404 Page Tracking

Detect 404 pages and track them:

<script src="https://api.agentanalytics.sh/tracker.js"
  data-project="my-site"
  data-token="aat_..."
  data-track-404="true"></script>

Works with <meta name="aa-status" content="404"> or the navigation response status.

Visitor Intelligence

Every event includes built-in visitor context:

• Session count — is this their 1st visit or their 10th?
• Days since first visit — how long have they been around?
• First-touch attribution — which UTM source originally brought them?

Your agent can segment funnels by new vs. returning visitors or see which acquisition channels bring users who come back.

Campaign Attribution

UTM parameters persist across the session and first-touch UTMs are stored. If a user arrives via ?utm_source=reddit, navigates around, and converts later, the conversion can still carry the campaign context.

Dev Mode

The tracker auto-detects local development hosts and switches to dev mode, logging events to the browser console instead of sending them to the API:

[aa-dev] track page_view {path: "/pricing", ...}
[aa-dev] track cta_click {id: "hero_signup", ...}

No test data polluting production analytics.

All From One Script Tag

Everything is configured through HTML attributes. Start small and opt into the browser signals you want:

<script src="https://api.agentanalytics.sh/tracker.js"
  data-project="my-site"
  data-token="aat_your_token"
  data-track-outgoing="true"
  data-track-performance="true"
  data-track-vitals="true"
  data-track-errors="true"
  data-track-downloads="true"
  data-track-forms="true"
  data-track-404="true"
  data-track-scroll-depth="true"
  data-heartbeat="30"
  data-link-domains="yoursite.com"
  data-do-not-track="true"></script>

One script tag, explicit opt-ins, and data your AI agent can use.

Get Started

Already using Agent Analytics? You’re already on the new tracker — it updates automatically.

New here?

• Sign up at app.agentanalytics.sh
• Install the skill from ClawHub
• Read the docs at docs.agentanalytics.sh

---

Previously: Funnels: See Where Users Drop Off · A/B Testing Your AI Agent Can Actually Use · Set Up Agent Analytics with OpenClaw