Overview

@supapulse/core is the browser tracker behind every Supapulse install. The script tag loads it from jsDelivr; apps can install it from npm. It has no runtime dependencies, and the browser build is about 2.3 KB gzipped.

What it doesCopy Anchor Link

• Pageviews. Sends one when it initializes, then one on every history.pushState, history.replaceState and popstate. Turn this off with autoPageviews: false.
• Custom events. supapulse.event(name, properties) sends a named event with any JSON-serializable properties.
• Sessions. Each page load gets a random session ID, kept in memory. Revenue can use it to link a payment to the visit. See Sessions.
• Identify. supapulse.identify(userId) links the visitor to your customer ID, so revenue is credited to the visit that brought them. See Revenue attribution.
• Delivery. Sends with navigator.sendBeacon and falls back to fetch with keepalive. Failed fetch sends are retried with exponential backoff, and 429 responses wait for Retry-After.

It stores nothing in the browser: no cookies, no localStorage, no sessionStorage.

Core or React?Copy Anchor Link

@supapulse/react creates and initializes a core tracker for you. Use it in React apps; use core everywhere else. See the React overview.

ExampleCopy Anchor Link

import { Supapulse } from '@supapulse/core';

const supapulse = new Supapulse();
supapulse.init({ apiToken: 'pub_your_token' });

// A pageview was sent on init. Track an event:
supapulse.event('signup', { plan: 'growth' });

// After login, link the visitor to your customer ID:
supapulse.identify('user_123');

// Optional: pass these through checkout to attribute revenue to this visit:
const sessionId = supapulse.getSessionId();
const fingerprint = await supapulse.getVisitorFingerprint();

How a pageview gets countedCopy Anchor Link

1. The tracker posts { type: 'pageview', data: { url, path, referrer, title, locale, utm_* , session_id } } to /api/ingest with the public token.
2. The API checks the token and the request's Origin, queues the event and answers 202.
3. A worker builds the visitor hash from the IP address, user agent, site and salt, looks up the country, parses the browser, OS and device type from the user agent, and stores the pageview without the IP address.

The tracker doesn't compute the visitor hash. getVisitorFingerprint() asks the server for it when you need it, for revenue; see the API reference.

Next stepsCopy Anchor Link

• Install the package
• Track pageviews and events
• All configuration options