attribu

Official Attribu SDK for web apps. Use this if you prefer npm packages over the script tag.

Installation

npm install attribu

Quick Start

Same API as in the Attribu docs: use initAttribu once, then call trackPageview(), track(), identify(), and trackPayment().

import { initAttribu } from 'attribu';

const attribu = await initAttribu({
  websiteId: 'your-website-id',
  domain: 'yourdomain.com', // optional, defaults to current hostname
});

// Track page views
attribu.trackPageview();

// Track custom events
attribu.track('button_click', { button: 'signup' });

// Identify users
attribu.identify({ user_id: 'user_123', email: '[email protected]', plan: 'pro' });

// Track payments (email-based)
attribu.trackPayment({ email: '[email protected]' });

// Or Stripe session-based
attribu.trackPayment({ stripe_session_id: 'cs_live_123' });

// Reset visitor identity (e.g. on logout)
attribu.reset();

With React / Next.js

// lib/analytics.ts
import { initAttribu } from 'attribu';

let attribu: Awaited<ReturnType<typeof initAttribu>> | null = null;

export async function getAnalytics() {
  if (!attribu) {
    attribu = await initAttribu({
      websiteId: process.env.NEXT_PUBLIC_ATTRIBU_WEBSITE_ID!,
      domain: process.env.NEXT_PUBLIC_ATTRIBU_DOMAIN,
    });
  }
  return attribu;
}

Then in your components:

import { getAnalytics } from '@/lib/analytics';

export default function SignupButton() {
  const handleSignup = async () => {
    const analytics = await getAnalytics();
    analytics.track('signup', { plan: 'free', source: 'homepage' });
  };

  return <button onClick={handleSignup}>Sign Up</button>;
}

API

initAttribu(config) -> Promise<AttribuInstance>

Initialize the SDK. Returns a client with all tracking methods. SSR-safe (returns no-ops on the server).

Config (AttribuConfig)

{
  websiteId: string;            // Required: Your Attribu website ID
  domain?: string;              // Optional: Defaults to current hostname
  src?: string;                 // Optional: Custom script URL (for self-hosted instances)
  allowLocalhost?: boolean;     // Optional: Allow tracking on localhost (default: false)
  allowedHostnames?: string[];  // Optional: Hostnames for cross-domain tracking
  disablePayments?: boolean;    // Optional: Disable auto payment detection (default: false)
  disableAutoPageview?: boolean; // Optional: Disable initial pageview (default: false)
}

By default, tracking is silently disabled on localhost, file:// protocol, inside iframes, and for bots/headless browsers. Set allowLocalhost: true for local development.

attribu.trackPageview() -> void

Track a page view. Uses window.location.href including query params, UTMs, and ad click IDs. SPA navigation (pushState/popstate) is automatically tracked. Duplicate pageviews for the same URL within 60 seconds are automatically skipped.

attribu.track(eventName, properties?) -> void

Track a custom event.

attribu.track('add_to_cart', { product: 'Pro Plan', price: 49 });

attribu.identify(data) -> void

Identify a logged-in user. user_id is required.

attribu.identify({ user_id: 'user_123', name: 'John', email: '[email protected]' });

attribu.trackPayment(data) -> void

Track a payment. Include email or stripe_session_id for attribution.

attribu.trackPayment({ email: '[email protected]' });
attribu.trackPayment({ stripe_session_id: 'cs_live_123' });

attribu.getVisitorId() -> string | null

Get the current visitor ID (from attribu_visitor_id cookie).

attribu.getSessionId() -> string | null

Get the current session ID (from attribu_session_id cookie).

attribu.getTrackingParams() -> { _att_vid, _att_sid }

Get visitor and session IDs for cross-domain tracking.

attribu.buildCrossDomainUrl(url) -> string

Append visitor/session tracking params to a URL for cross-domain navigation.

const url = attribu.buildCrossDomainUrl('https://other-domain.com/signup');
// => 'https://other-domain.com/signup?_att_vid=abc-123&_att_sid=s456-789'

On the receiving domain, initAttribu automatically picks up the params and restores the visitor/session.

attribu.reset() -> void

Reset visitor identity (e.g. on logout). Clears visitor and session cookies.

Script Tag Alternative

If you prefer not to use npm, add the script tag instead:

<script
  defer
  data-website-id="your-website-id"
  data-domain="yourdomain.com"
  src="https://attribu.tech/js/script.js"
></script>

License

MIT