@atribu/tracker

Official browser tracking SDK — page views, sessions, engagement, outbound links, file downloads, forms, bookings, all auto-captured.

Published: @atribu/tracker on npm · Source: github.com/AtribuCore/atribu-tracker

@atribu/tracker is a npm-installable alternative to the <script src="atribu-tracker.js"> tag — same runtime, bundled inline, configured at init() time. Most teams using a modern frontend framework (React, Next.js, Vue, Svelte) will prefer this over the script tag.

Install

npm install @atribu/tracker

Quick start

import { init } from "@atribu/tracker";

init({
  trackingKey: "trk_live_...", // from Tracking Settings → Ingest Keys
});

That's it. Page views, sessions, engagement, outbound links, file downloads, form submissions, and booking detection are all auto-captured.

What's auto-captured

Signal	Triggers
Page views	`init`, SPA navigation (`pushState`/`replaceState`/`popstate`/`hashchange`), bfcache restoration
Sessions	30 min inactivity timeout (configurable 1–120 min)
Engagement	Scroll depth (px + %), time on page — sent on page exit
Outbound links	External link clicks via `sendBeacon`
File downloads	pdf · xlsx · docx · csv · zip · mp4 · and 30+ more
Form submissions	Standard `<form>` submits AND GHL-style `<div>` form fetches
Booking detection	Calendly · Cal.com · GoHighLevel · custom postMessage patterns
Meta Pixel bridge	Intercepts `fbq()` calls for server-side CAPI dedup
Bot filtering	Blocks bots; tags AI agents (ChatGPT, Claude, Perplexity, Gemini)
Declarative events	`data-atribu-event` HTML attributes — no-code event tracking

Configuration

init({
  trackingKey: "trk_live_...",                  // required
  apiHost: "https://tracking.example.com",      // custom tracking domain (optional)
  trackingEndpoint: "...",                       // full override of collect URL (optional)
  interceptMetaFbq: true,                       // mirror Meta Pixel events (default true)
  metaBridgePageview: false,                    // mirror Meta PageView too (default false)
  customProperties: { tier: "pro" },            // static props on every event
  transformRequest: (event) => event,           // event middleware (return null to suppress)
  ignoredPages: ["/admin/*"],                   // URL patterns with `*` wildcards
  sessionTimeoutMinutes: 30,                    // 1–120 min
  sessionMode: "inactivity_only",               // or "inactivity_or_source_change"
});

Framework setup

app/providers.tsx

"use client";

import { useEffect } from "react";
import { init } from "@atribu/tracker";

export function AtribuProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    init({ trackingKey: "trk_live_..." });
  }, []);
  return <>{children}</>;
}

app/layout.tsx

import { AtribuProvider } from "./providers";

export default function RootLayout({ children }) {
  return (
    <html><body><AtribuProvider>{children}</AtribuProvider></body></html>
  );
}

import { useEffect } from "react";
import { init } from "@atribu/tracker";

function App() {
  useEffect(() => {
    init({ trackingKey: "trk_live_..." });
  }, []);
  return <>{/* your app */}</>;
}

import { onMounted } from "vue";
import { init } from "@atribu/tracker";

onMounted(() => init({ trackingKey: "trk_live_..." }));

import { onMount } from "svelte";
import { init } from "@atribu/tracker";

onMount(() => init({ trackingKey: "trk_live_..." }));

<script type="module">
  import { init, track } from "@atribu/tracker";

  init({ trackingKey: "trk_live_..." });

  document.querySelector("#signup-btn").addEventListener("click", () => {
    track("signup", { source: "landing" });
  });
</script>

Custom events

import { track, trackRevenue } from "@atribu/tracker";

track("button_click", { label: "hero-cta" });

trackRevenue("purchase", 99.99, "USD", { plan: "enterprise" });

User identification

Two complementary APIs:

import { identify, setUserId } from "@atribu/tracker";

// PII-based — joins this visitor to the customer_profile via identity graph
identify({
  email: "[email protected]",
  firstName: "Jane",
  lastName: "Doe",
  phone: "+1234567890",
});

// Stable user_id stamped on every future event (e.g. on login)
setUserId("user_abc123");

// Clear on logout
setUserId(null);

identify does the heavier identity-graph work (anonymous_id ↔ email ↔ phone resolution). setUserId just stamps your application's user ID on events.

import { setConsent } from "@atribu/tracker";

setConsent({ analytics: true, marketing: false });

Consent state persists to localStorage and is attached to every event. Events fired before consent are queued and replayed once granted.

Declarative events (no-code)

Track events without writing JavaScript using HTML data attributes:

<button
  data-atribu-event="signup"
  data-atribu-prop-plan="pro"
  data-atribu-revenue="99.99"
  data-atribu-currency="USD"
>
  Sign Up
</button>

The tracker auto-captures clicks on elements with data-atribu-event and extracts:

Event name from data-atribu-event
Custom properties from data-atribu-prop-* attributes
Revenue from data-atribu-revenue + data-atribu-currency

Privacy

What the tracker does NOT do

No third-party tracking — all data goes to your configured endpoint only
No cookies set for tracking IDs (visitor + session IDs live in localStorage)
No fingerprinting — visitor IDs are cryptographically random, not derived from device characteristics

First-party only. All data goes to your configured endpoint. No cross-site identifiers.
No cookies set for tracking. Visitor + session IDs live in localStorage. The tracker reads _fbp/_fbc cookies (set by Meta Pixel) only when present, for CAPI match quality.
Consent-aware. setConsent() state is persisted and attached to every event.
Bot filtering on-device. Traditional bots are blocked at the client level. AI agents (ChatGPT, Claude, Perplexity, Gemini) are tracked but tagged visitor_type: "ai_agent" so you can filter them in reporting.

Lifecycle controls

import { flush, reset } from "@atribu/tracker";

flush(); // force-send queued events (e.g. before navigating away)
reset(); // clear visitor ID, session, all stored state (e.g. on logout)

Singleton access

Initialize once, retrieve from anywhere:

import { init, getTracker } from "@atribu/tracker";

// At app entry:
init({ trackingKey: "trk_live_..." });

// In any other module:
const atribu = getTracker();
atribu.track("button_click", { label: "hero-cta" });

Developer exclusion

Exclude yourself from tracking during development:

localStorage.atribu_ignore = "true";

Remove it to re-enable:

delete localStorage.atribu_ignore;

Runtime support

Runtime	Supported
Modern browsers (Chrome, Safari, Firefox, Edge)	✅
Mobile webviews (iOS, Android)	✅
SSR (Node 18+, Next.js server components)	✅ — no-op fallback
Bun (browser bundle)	✅
Deno	❌ (no DOM)

In SSR contexts, init() returns a silent no-op client so you can safely import + call from server components.

Provenance

Every published version of @atribu/tracker ships with a Sigstore provenance attestation signed by GitHub Actions OIDC. Verify with:

npm audit signatures

On this page