@metrone-io/sdk

Browser SDK for Metrone — the analytics backend for humans and AI agents.

Lightweight tracking with automatic pageviews, custom events, conversions, AI interaction tracking, batching, retries, and DNT/consent support. No HTTP cookies — uses sessionStorage for session continuity and optionally reads localStorage for consent state. Events go to an event store pinned to your project's region (US or EU).

Install with your coding agent

The fastest path is the one written for agents: in your project, run (or tell your agent to run)

npx @metrone-io/cli init

It detects your framework, creates a project in the region you choose, writes the key to your env file (never to git), wires this SDK and sends a test event — no account needed before the first event. The full agent-readable guide is metrone.io/install.md (site summary for LLMs: metrone.io/llms.txt).

Install by hand

npm install @metrone-io/sdk

Usage

import { Metrone } from '@metrone-io/sdk'

const analytics = new Metrone({
  apiKey: process.env.METRONE_API_KEY,          // metrone_live_…
  // endpoint defaults to https://api.metrone.io/v1/events, which routes to your project's region.
  // Use your project's regional ingest_url from `npx @metrone-io/cli init` (e.g. https://eu.api.metrone.io/v1/events)
  // or your first-party CNAME (https://data.yourdomain.com/v1/events) instead.
})

analytics.pageview()
analytics.track('button_click', { button_id: 'cta' })
analytics.conversion('purchase', 49.99)

Script tag

The ingestion host serves the same bundle at /m.js; data-key + data-api initialise it without any code:

<script defer src="https://api.metrone.io/m.js"
  data-key="metrone_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  data-api="https://api.metrone.io/v1/events"></script>

For a first-party setup, point one CNAME (data.yourdomain.com) at Metrone and use that host in both attributes — see metrone.io/docs/cname.

AI Tracking

analytics.trackAICall({ call_id: 'call_123', provider: 'vapi', duration: 45 })
analytics.trackAIChat({ session_id: 'sess_456', provider: 'intercom', message_count: 8 })
analytics.trackAIIntent({ intent: 'book_appointment', confidence: 0.92, source: 'voice' })
analytics.trackAISession({ session_id: 'sess_456', action: 'end', duration: 120 })

Zero-Code Click Tracking

<button data-track="cta_hero">Get Started</button>
<a href="/pricing" data-track="nav_pricing">Pricing</a>

Human vs AI traffic

Every event this SDK sends is classified at ingest as human or AI, with no configuration needed:

• Humans clicking through from AI platforms (ChatGPT, Gemini, Perplexity, Claude, Copilot, …) are detected automatically from the referrer/UTM and grouped under one canonical AI source on the Metrone AI Traffic dashboard.
• AI agents themselves (GPTBot, ChatGPT-User, PerplexityBot, …) never execute JavaScript, so no browser SDK can see them. Capture those with @metrone-io/server's agent middleware or the agent-edge Cloudflare Worker — this SDK keeps handling your human visitors.

Features

• No HTTP cookies — uses sessionStorage for sessions, no cross-site tracking
• Automatic SPA route tracking
• Automatic outbound link, tel:, mailto:, and download click tracking
• Zero-code click tracking via data-track attribute
• AI voice call, chat, intent, and session tracking
• Event batching with sendBeacon flush on page unload
• Retry logic with exponential backoff
• Idempotency keys to prevent duplicate events
• DNT and consent mode support
• Automatic human vs AI traffic classification at ingest (AI Traffic dashboard)
• CJS + ESM + IIFE builds

Documentation

metrone.io/docs

License

MIT