Design a client-side analytics SDK

Requirements exploration

An analytics SDK looks like the easiest problem in the list: collect an object, POST it to a server. A first version fits in ten lines. The real problem is where those ten lines run.

They run on someone else's page, next to code we've never seen, on phones with slow CPUs, in tabs that close without warning, in browsers that block trackers, and in countries with privacy laws. So the first minutes go to finding out which of those worlds we're in.

A few words first. An event is one fact about what a user did, such as Product Viewed or Signup Started. Each event has a name, properties (key and value pairs like price: 19), a timestamp, and who did it. The collector is the server endpoint that receives events, and the host page is the customer's website where our script runs.

Questions to ask first

• Is this a first-party SDK for our own app, or a product other companies embed? Embedded means we're a guest: we can't assume a framework, a bundler, or a build step, and every bug we ship breaks thousands of sites at once.
• What do customers track? Hand-written events only, or also automatic page views and clicks? Automatic capture changes the privacy story a lot.
• How much traffic? A large customer at 50 million page views a day with about 10 events per view sends 500 million events a day, around 6,000 per second on average and several times that at peak. Batching on the client is how we keep requests per second sane.
• How bad is a lost event? A lost Button Hovered is noise. A lost Order Completed breaks a revenue report. Do customers need a way to mark events as important?
• Which regions and laws? In the EU and UK, analytics tracking generally needs consent first (GDPR and the ePrivacy rules). California users can opt out of the sale and sharing of their data (CCPA and CPRA). This decides whether we can send anything before a consent banner is answered.
• Which browsers? Safari's Intelligent Tracking Prevention (ITP) limits cookies and storage set by scripts. Brave and many extensions block known tracker domains. On some sites a large share of traffic sits behind one of these.
• Do customers want to install through npm too? A script tag and an npm package can share the same core but load differently.

Functional requirements

• A public API: track(name, properties), page(), identify(userId, traits), group(groupId, traits), reset(), and a way to add plugins.
• Calls made before the script finishes loading are kept and replayed in order.
• Every event carries an anonymous id, a user id after login, a session id, a unique event id, a timestamp, and page context (URL, referrer, screen size, locale).
• Events are batched, stored so they survive a reload, retried on failure, and delivered when the tab is hidden or closed.
• Consent is respected: nothing leaves the browser before the user agrees, where the law needs it.
• Optional automatic page views for single page apps and optional click autocapture.
• A debug mode that shows every event, its validation result, and the queue.

Non-functional requirements

Out of scope

• The ingestion pipeline, warehouse, and dashboards. We design up to the collector's HTTP contract.
• Session replay (recording the DOM). It's a separate, much heavier product.
• Performance metrics such as LCP and INP. That is real user monitoring; see the Real-user monitoring (RUM) lesson. The same transport can carry them.
• Error tracking with stack traces; see the Error tracking lesson.
• Building the consent banner itself. We read consent from it; the cookie-consent problem designs the banner.

What makes this hard

Five traits of this problem drive every later chapter. Name them early in the interview: it shows you see past the fetch call.

1. We're a guest on someone else's page. The customer's page owns the main thread, the global scope, and the user's patience. Our script competes with their checkout code for the same CPU. If we throw an error, block rendering, or add a 300 ms task to a click, it's their Core Web Vitals and their revenue that suffer. And a bug we ship lands on thousands of sites at the same moment.
2. It's fire and forget, with no one watching. A broken button gets a bug report. A dropped event gets nothing: the chart just looks a little lower. So the SDK has to be correct by design, and it needs a debug mode because no user will ever tell us.
3. Pages die without notice. On mobile, users switch apps, and the browser may freeze or kill the tab later without running any more of our code. The last events of a visit, often the most important ones like Checkout Completed before a redirect, happen exactly when the page is going away.
4. The environment pushes back. Ad blockers block known analytics domains. Safari limits how long script-set cookies and storage live. Networks drop. Some users browse in private mode where storage is thrown away at the end of the session.
5. Privacy is a legal requirement, not a feature. In many places we can't set an id or send an event until the user agrees. Collecting an email address by accident in a URL or a button label is a data breach, not a bug.

Notice what is missing: no complex UI, no real-time updates, no rendering. The SDK's only visible parts are a debug panel and, sometimes, the consent banner it listens to. The wireframe below shows where our code lives on a typical host page.

The public API and the snippet

Customers meet the SDK through two things: the snippet they paste into their HTML and the methods they call. Both are a contract we can never break, because thousands of copies of today's snippet will still be live in five years.

Four verbs are enough

Keep the surface this small on purpose. Every method we add must be stubbed in the snippet, documented, and supported forever. Segment and RudderStack use almost exactly these verbs, which is also a gift to customers: switching vendors means changing one script tag.

Calls made before the SDK loads

Here's the naive install: a script tag pointing at our CDN, and the customer's code calling analytics.track(). If the script tag is async (and it must be, see the next chapter), the customer's code usually runs first. analytics is undefined, the call throws a ReferenceError, and on a badly written page that error can stop the rest of their script. We just broke their site.

(function (w, d, src) {
  var a = (w.analytics = w.analytics || []);
  if (a.initialized || a.invoked) return; // real SDK, or snippet pasted twice
  a.invoked = true;
  a.snippetVersion = 3;
  ["track", "page", "identify", "group", "reset", "use", "consent"]
    .forEach(function (m) {
      a[m] = function () {
        var args = Array.prototype.slice.call(arguments);
        a.push([m, Date.now()].concat(args)); // keep the call time
        return a;
      };
    });
  var s = d.createElement("script");
  s.async = true;
  s.src = src;
  d.head.appendChild(s);
  a.page(); // inside the guard, so a doubled snippet counts one view
})(window, document, "https://cdn.example-analytics.com/v1/sdk.js");

Three details matter. First, the stub stores Date.now() with each call: if the SDK arrives 2 seconds later, Signup Started still gets the moment the user clicked, not the moment we caught up. Second, snippetVersion tells the SDK which snippet a site runs, so we know when an old copy still needs support.

Third, the guard on invoked makes a doubled snippet (common when a tag manager also injects it) harmless. That only works because the first page() call sits inside the guard too; a page() after the closing line would run twice and count every view twice. Segment's snippet uses the same guard and logs a console error when it's pasted twice. Google's version is even smaller: gtag() is a function that pushes its arguments onto the window.dataLayer array, which gtag.js works through once it loads.

// Inside sdk.js, once the core is ready
const stub = (window as any).analytics as unknown[][];
const sdk = createAnalytics(readConfig());

// Replay until the array is empty. A call made during the replay (by a plugin
// or a customer callback) still hits a stub, lands at the end, and runs in turn.
while (stub.length > 0) {
  const [method, time, ...args] = stub.shift()!;
  sdk.callAt(method as string, time as number, args); // same order as called
}
sdk.initialized = true;
(window as any).analytics = sdk; // from now on, calls reach real methods

Plugins: one pipeline for every event

Customers always want to change events: drop internal staff traffic, rename a property, add the A/B test variant, strip a query parameter. Instead of a growing list of options, run every event through an ordered pipeline of small functions. Each plugin gets the event and returns it changed, returns it as is, or returns null to drop it.

type Plugin = {
  name: string;
  stage: "before" | "enrich" | "destination";
  run(event: AnalyticsEvent): AnalyticsEvent | null;
};

function runPipeline(event: AnalyticsEvent, plugins: Plugin[]) {
  let current: AnalyticsEvent | null = event;
  for (const p of plugins) {
    if (!current) return null;
    try {
      current = p.run(current);
    } catch (err) {
      debugLog("plugin failed, skipped", p.name, err); // never throw into the host page
    }
  }
  return current;
}

Our own features are plugins too: page context, session tracking, consent filtering, and sampling each live in their own plugin. That keeps the core tiny and lets a customer replace one piece. Plugins run synchronously and must stay fast; anything slow (like hashing with crypto.subtle) belongs after the event is in the queue.

Typed events, checked in development only

The biggest data quality problem in analytics is drift: one team sends Order Completed with total, another sends order_completed with amount. The fix is a tracking plan: a list of allowed events and the type of each property, stored as JSON Schema. From it we generate TypeScript types so the compiler catches typos, and a validator that checks events at runtime.

// Generated from the tracking plan
type Events = {
  "Order Completed": { orderId: string; total: number; currency: "USD" | "EUR" };
  "Signup Started": { method: "email" | "google" };
};

export function track<K extends keyof Events>(name: K, props: Events[K]): void;

track("Order Completed", { orderId: "o_19", total: 42, currency: "USD" }); // ok
track("Order Completed", { total: "42" }); // compile error: wrong type, missing orderId

Runtime validation costs bytes: a JSON Schema validator plus the schema can be 10 to 30 KB. So it never ships in the production SDK. In debug mode (a cookie, a query parameter, or analytics.debug(true)) the SDK lazy loads sdk-debug.js, which validates every event and prints clear warnings. In production the collector validates instead and tags bad events, so a dashboard shows "12% of Order Completed events are missing currency" without adding a byte to users' downloads.

Loading without hurting the page

The Third-party scripts and supply chain lesson covers why outside scripts are the most common reason a fast site turns slow. This chapter applies it to ourselves: we are the third party. The goal is that a customer who adds our snippet sees no change in LCP (Largest Contentful Paint, good under 2.5 s) and INP (Interaction to Next Paint, good under 200 ms).

How the file arrives

A script added by another script, like ours, is async by default: it downloads in parallel with parsing and runs as soon as it arrives, without blocking the HTML parser. We can also set fetchPriority = "low" on the script element (current Chrome, Safari, and Firefox all support the hint), so our download never competes with the hero image that decides LCP. The defer attribute would also work for a hand-written tag, but it waits for the whole document to parse, which delays page views on long pages.

A small core and lazy extras

Every byte we ship is downloaded, parsed, and compiled on every page view of every customer. On a mid-range Android phone, JavaScript parse and compile run at very roughly 1 MB per second of uncompressed code, so 100 KB of uncompressed SDK costs around 100 ms of main thread before it does anything. Splitting the SDK keeps the common path small.

For scale, products differ a lot. Plausible advertises a script of about 1 KB because it mostly sends page views, while a Google tag with several products configured commonly transfers tens of KB or more. Full-featured SDKs such as PostHog's, with autocapture, replay, and surveys, load much more but split it into lazily loaded parts.

A budget of under 25 KB gzipped for the core puts us closer to the small end while keeping batching, retries, and identity. A size check in CI fails the build if a change crosses it (the Performance budgets and monitoring lesson shows how).

Never a long task

A long task is any main thread task over 50 ms. While it runs, the browser can't respond to a tap. The trap for an analytics SDK is subtle: customers call track() inside their click handlers, so whatever we do synchronously inside track() becomes part of their interaction, and so part of their INP.

If track() serializes JSON, writes localStorage, and builds a request, a click can cost 5 to 20 ms more on a slow phone, 20 times a page. On a page already close to the 200 ms INP line, that is enough to push it over.

function scheduleBackground(work: () => void) {
  const s = (globalThis as any).scheduler;
  if (s?.postTask) {
    s.postTask(work, { priority: "background" });
  } else if (typeof requestIdleCallback === "function") {
    requestIdleCallback(work, { timeout: 2000 }); // run within 2 s even if never idle
  } else {
    setTimeout(work, 50);
  }
}

function processPending() {
  const start = performance.now();
  while (pending.length > 0 && performance.now() - start < 8) {
    enqueue(runPipeline(pending.shift()!, plugins)); // a few events per slice
  }
  if (pending.length > 0) scheduleBackground(processPending);
}

Identity and sessions

Analytics is about people over time: a funnel needs to know that the visitor who viewed pricing on Monday is the one who paid on Thursday. So every event carries ids, and the SDK owns three of them.

• Anonymous id: a random id for this browser, created on the first visit with crypto.randomUUID(). It exists before anyone logs in. That function only exists on HTTPS pages, so the SDK keeps a small fallback built on crypto.getRandomValues() for the rare HTTP site.
• User id: the customer's own id for a logged-in user, set by identify(). It's the same on every device.
• Session id: one visit. We use the session's start time in milliseconds, which is unique enough per browser and sorts naturally.

Where the anonymous id lives

How do we find the top domain? We can't just take the last two labels: for shop.co.uk that gives co.uk, a public suffix where browsers refuse cookies. The cheap trick most SDKs use is to try, from the shortest candidate upward, and keep the first one the browser accepts.

function topDomain(hostname: string): string {
  const parts = hostname.split(".");
  for (let i = parts.length - 2; i >= 0; i--) {
    const candidate = parts.slice(i).join("."); // co.uk, then shop.co.uk
    document.cookie = `__probe=1; Domain=${candidate}; Path=/; SameSite=Lax`;
    if (document.cookie.includes("__probe=1")) {
      document.cookie = `__probe=; Domain=${candidate}; Path=/; Max-Age=0`;
      return candidate;
    }
  }
  return hostname; // localhost or an IP address
}

Login, logout, and stitching

When a user logs in, the customer calls identify("u_812"). We keep the anonymous id and add the user id to every later event. That one event carrying both ids is what lets the warehouse stitch identities: all earlier anonymous events from this browser now belong to u_812. When the same user logs in on a phone, that phone's anonymous id is stitched to u_812 too.

Two traps. First, reset() on logout must clear the user id and create a new anonymous id. Otherwise, on a shared family laptop, the next person's browsing is stitched to the previous user.

Second, if identify() is called with a different user id than the stored one without a reset() in between, treat it as a new person: start a new anonymous id rather than merging two accounts. Merging two known ids on purpose, for example when a guest checkout becomes an account, is an explicit merge that the server handles, through a separate call like Segment's alias().

What a session is

A session ends after 30 minutes without any event. Google Analytics and Amplitude both default to 30 minutes, and customers will compare our numbers with theirs, so matching the convention matters more than the exact value. We keep sessionId and lastEventAt in localStorage so every tab of the same site shares one session. On each event: if now - lastEventAt is over 30 minutes, start a new session and emit a Session Started event first; then update lastEventAt.

Edge cases worth naming: a tab left open overnight sends its next event into a new session, which is right. Two tabs racing to start a session at the same moment can create two ids; that's acceptable because the warehouse can merge sessions that overlap in time for the same anonymous id. And a session never needs a timer: we only check when an event happens.

The event queue: batching, storage, and retries

The naive transport sends one fetch per event. A product page with a page view, three scroll milestones, a few impressions, and two clicks makes 10 requests in 30 seconds. On a phone, each request can wake the radio, and on the collector each one is a separate HTTP exchange.

For the large customer from the requirements, 6,000 events per second become 6,000 requests per second instead of a few hundred. And if the tab reloads while a request is waiting, the event is gone.

So events go into a queue, and the queue sends batches: one POST with many events. The queue answers four questions: when to send, where events wait, what to do on failure, and what to do when it's full.

When to send a batch

Where events wait

Several tabs of the same site each run the SDK, and they share one IndexedDB. Each tab writes its own events tagged with a tab id and only sends its own. When a tab starts, it checks for events from tabs that closed without sending, and one tab adopts them, using a Web Locks lock (navigator.locks.request("outbox", ...)) so two tabs don't send the same orphaned batch at once. The event ids make a rare double send harmless anyway.

Failures, retries, and duplicates

• Retry on network errors, 429 Too Many Requests, and 5xx. Wait with exponential backoff and full jitter: a random wait between 0 and min(60 s, 1 s x 2 to the power of attempt). Honor a Retry-After header when the collector sends one. The Retries, timeouts, and backoff lesson explains why jitter matters: without it, a collector outage ends with every browser retrying at the same second.
• Don't retry a 400 (the batch is malformed) or 413 (too large). Split a 413 batch in half and try each half once; drop a 400 batch and report it to our own error endpoint.
• Deduplicate with an event id. Every event gets a messageId from crypto.randomUUID() when track() runs. If a batch reached the server but the response was lost, the retry sends the same ids, and the collector ignores ids it has seen in the last 24 hours. At-least-once delivery plus dedupe gives us effectively once.
• Order by time, not arrival. Batches can arrive out of order after retries, so the warehouse sorts by the event's own timestamp. Phone clocks can be wrong by minutes, so each batch also carries sentAt; the server computes the skew as its receive time minus sentAt and shifts every event's timestamp by it.

When the queue is full

A phone offline for a week, or a page stuck in a loop calling track() 100 times a second, can grow the queue without bound. Cap it at 1,000 events or 2 MB, whichever comes first. When it's full, drop the oldest normal events first and keep key events. Never drop silently: count drops and send the count with the next batch (dropped: 312), so the dashboard can show a gap instead of a mysterious dip.

Also cap the rate: more than 50 events per second from one page is almost always a bug, so the SDK keeps a token bucket and drops the excess with a debug warning.

Try the queue below. Add events, watch the triggers fire, fail the network to see backoff, and hide the tab in the middle of a batch.

Delivery when the page goes away, and offline

The events at the end of a visit are often the valuable ones: the last scroll depth, the time spent, a Checkout Completed fired just before the page redirects to a thank-you page on another domain. The TikTok feed guide uses the same moment to send watch time; here we build it into the general queue.

Which page event to listen to

The old answer was unload or beforeunload. Both are unreliable on mobile: when a user switches apps, the browser may later freeze or discard the tab without firing either. Chrome has gone further and deprecated unload: since Chrome 155 (October 2026) its handlers no longer fire by default on any site.

The back/forward cache (bfcache) keeps a page in memory so the Back button restores it instantly. In Firefox, an unload listener makes a page ineligible for it, and Safari often caches the page anyway and skips the handler. So an SDK that adds an unload listener gains nothing reliable and can make the customer's Back button slower.

The modern answer: flush when visibilitychange fires with document.visibilityState === "hidden". It fires when the user switches tabs, switches apps, locks the phone, or navigates away, and on mobile it's the last event we can count on. Also listen to pagehide as a backup: it fires whenever the page is unloaded or put into the bfcache, so it covers any browser that skips visibilitychange on the way out. Flushing twice is harmless: the second time the buffer is empty.

How to send while the page is leaving

const BEACON_LIMIT = 60_000; // bytes, under the shared 64 KiB budget
const encoder = new TextEncoder();

function send(body: string): boolean {
  if (typeof navigator.sendBeacon === "function") return navigator.sendBeacon(url, body);
  fetch(url, { method: "POST", body, keepalive: true }).catch(() => {}); // old browsers
  return true;
}

function flushOnHide() {
  const batch: AnalyticsEvent[] = [];
  let bytes = 200; // room for writeKey, sentAt, and the brackets
  for (const event of buffer.peek()) { // oldest first
    const size = encoder.encode(JSON.stringify(event)).length + 1; // bytes, not characters
    if (bytes + size > BEACON_LIMIT) break; // the rest waits in the outbox
    batch.push(event);
    bytes += size;
  }
  if (batch.length === 0) return;
  const body = JSON.stringify({ writeKey, sentAt: new Date().toISOString(), batch });
  if (!send(body)) return; // refused: everything stays in the outbox
  buffer.remove(batch); // so the pagehide that often follows finds nothing to resend
  outbox.markSent(batch.map((e) => e.messageId)); // may not finish; ids dedupe a resend
}

document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "hidden") flushOnHide();
});
addEventListener("pagehide", flushOnHide);

Coming back from the back/forward cache

A page restored from bfcache doesn't load again; its JavaScript simply resumes. Listen for pageshow with event.persisted === true: restart the flush timer, check whether the session timed out while the page was frozen, and send a page view, because to the user it was a new view of the page. Also avoid things that block bfcache: no unload listener, and no open WebSocket held by the SDK.

Offline

When requests fail with network errors, events stay in the IndexedDB outbox and backoff slows our attempts. navigator.onLine === false reliably means no network at all, so pause sending then. true only means some network exists, maybe a captive portal, so keep relying on request results. On the online event, reset the backoff and flush right away.

We do not register a service worker or Background Sync: the customer owns the site's service worker scope, and a guest script must not claim it. The Offline sync engine guide goes deeper on durable queues for apps that own the whole page.

Sampling, consent, and privacy

Two different questions decide whether an event leaves the browser. Sampling asks "do we need it?", a cost decision. Consent asks "are we allowed to?", a legal one. Both must be decided per user, consistently, and early in the pipeline.

Sampling without breaking funnels

A customer with 500 million events a day may only want to pay for 10%. The naive way is if (Math.random() < 0.1) send() per event. It cuts volume, but it destroys funnels: a user who viewed a product, added it to cart, and paid would have each step kept with a 10% chance, so only 0.1% of buyers show all three steps. The funnel shows a 99% drop that never happened.

// FNV-1a: a tiny, fast, well-spread 32-bit hash (not for security)
function fnv1a(text: string): number {
  let hash = 0x811c9dc5;
  for (let i = 0; i < text.length; i++) {
    hash ^= text.charCodeAt(i);
    hash = Math.imul(hash, 0x01000193) >>> 0;
  }
  return hash;
}

function inSample(id: string, rate: number, salt = "2026-q4"): boolean {
  return fnv1a(salt + ":" + id) % 10_000 < rate * 10_000;
}

Rate limits sit next to sampling. The client-side token bucket from the queue chapter stops runaway loops. The server can also send back a lower rate in remote config during an incident, and answer 429 with Retry-After so every browser backs off together.

Consent before anything leaves the device

Under GDPR and the ePrivacy rules, sites in the EU generally need opt-in consent before storing ids on the device or tracking for analytics. In California, CCPA and CPRA give users the right to opt out of the sale or sharing of their data. This is a simplified summary, not legal advice: the rules differ by country and change over time (the UK, for example, has relaxed consent for some low-risk first-party analytics under its Data (Use and Access) Act 2025).

The SDK can't know the law for each visitor, so the customer (or a consent management platform, or CMP, the tool behind most cookie banners) tells us the state, per category: analytics and marketing. The customer's legal team decides the defaults; the SDK's job is to make every option easy and the safe one the default.

• Pending: the banner is showing. Events are created and kept in memory only. No cookie, no localStorage, no IndexedDB, no network. Not even the anonymous id is written.
• Granted: write the ids, flush the held events, and work normally from now on.
• Denied: drop the held events, write nothing. Optionally send fully anonymous, cookieless counts if the customer's legal team allows it.
• Changed later: if the user withdraws consent, stop sending, delete our cookies and storage, and call reset().

Google's Consent Mode follows the same idea: the page calls gtag("consent", "default", ...) with categories such as analytics_storage and ad_storage set to denied, then update when the user answers. Version 2 added two more categories for ads, ad_user_data and ad_personalization. Our analytics.consent({ analytics: "granted" }) is the same shape, which makes it easy to wire both to one banner.

Consent Mode also shows the two ways to handle the Denied state. In its basic mode, Google's tags don't load at all until the user agrees. In its advanced mode, they load and send cookieless pings while consent is denied, which Google uses for modeling. Our Denied state matches basic mode by default, with cookieless counts as an opt-in for customers whose lawyers approve it.

Privacy by default

• Global Privacy Control (GPC): if navigator.globalPrivacyControl is true (the browser also sends the Sec-GPC: 1 header), the user has asked not to have their data sold or shared. Brave and DuckDuckGo send it by default, Firefox once the user turns it on, and some extensions add it; Chrome and Safari don't support it natively. California regulators treat it as a valid opt-out. Default: turn off marketing destinations; the customer decides about first-party analytics.
• No personal data by default: strip query parameters that look like secrets (email, token, password, code) from captured URLs, never capture input values, and flag property values that look like emails in debug mode.
• IP addresses reach the collector with every request; the browser can't hide them. Truncating or dropping them happens on the server before storage, and the SDK should say so in its docs rather than pretend.
• Data residency: an EU endpoint (eu.collector...) chosen in config, so EU data never leaves the region.

The lab below has 12 users. Move the sample rate and watch who is in: the same people stay in as the rate grows, because the hash doesn't change. Then change consent and GPC for the selected user and see what actually leaves the browser.

Automatic tracking and ad blockers

Customers love not writing tracking code. Two automatic features are worth building: page views in single page apps, and click autocapture. Both are optional plugins, loaded only when turned on in remote config.

Page views in single page apps

On a classic site, each page loads the SDK again and the snippet's page() call counts it. In a single page app (SPA), the router changes the URL with history.pushState() and no page load happens, so only the first view is counted. A dashboard that shows one page view per visit for a React app is a bug customers notice on day one.

function watchRoutes(onChange: () => void) {
  let lastPath = location.pathname + location.search;
  const check = () => {
    const path = location.pathname + location.search;
    if (path === lastPath) return; // hash-only or no change
    lastPath = path;
    requestAnimationFrame(() => onChange()); // let the router set the title
  };
  const nav = (window as any).navigation;
  if (nav) return nav.addEventListener("currententrychange", check);
  for (const method of ["pushState", "replaceState"] as const) {
    const original = history[method];
    history[method] = function (this: History, ...args: any[]) {
      const result = original.apply(this, args as any); // always call through
      check();
      return result;
    };
  }
  addEventListener("popstate", check);
}

Click autocapture and its privacy risk

Autocapture adds one click listener on document in the capture phase, marked passive, and records what was clicked: the tag, a short text label, a few safe attributes like id and data-track, and a CSS path. Customers then name events later in the dashboard ("clicks on button.buy are Buy Clicked"), without a code release. Expect volume too: autocapture can produce several times more events than hand-written tracking, which is a cost question for the customer.

The risk is in the text. A button can say "Send to jane@mail.com", a list item can hold a patient's name, a link can carry a reset token in its URL. These rules keep autocapture safe:

• Never read input, textarea, or select values.
• Skip elements inside [data-private] or a selector the customer chooses.
• Cut text to 50 characters, and drop it if it looks like an email, phone, or card number.
• Strip query strings from captured link URLs.
• Keep autocapture off by default on pages matching patterns like /account or /checkout.

Ad blockers and first-party proxies

Blocking lists like EasyPrivacy match known analytics hosts and paths. Depending on the audience, a noticeable share of events never arrive: often small on mainstream consumer sites and much larger on developer-heavy ones. The common workaround is a first-party proxy: the customer routes a path on their own domain, such as shop.com/ingest, to our collector through their CDN or server, and serves the SDK file from there too.

Be honest about what that is. It makes delivery reliable for users whose network or extension blocks third-party hosts by mistake. It also defeats a choice some users made on purpose.

Our position as a vendor: support the proxy, but tie it to the rules from the previous chapter, so consent, GPC, and opt-outs are respected exactly the same through the proxy. For numbers that must be complete, like orders and revenue, the better answer is to send those events from the customer's server, where they're facts the business records anyway, and keep the browser for behavior.

Architecture, data model, and the collector API

Now the pieces fit together. The SDK is a pipeline: a thin public surface on top, a chain of plugins in the middle, and a queue with transports at the bottom. Each box has one job, and the boundaries are where we expect change: plugins change per customer, transports change per browser, storage changes per environment.

Follow one event end to end. The click handler calls track(); the API stamps it and returns.

In the next idle slot, the pipeline runs: the consent gate checks the state, sampling checks the user, context adds URL, locale, screen size, and library version, and the event lands in the memory buffer. About once a second, the buffer is written to the outbox.

When a trigger fires, the transport sends a batch to the collector, which validates, deduplicates, corrects clock skew, and passes events to the warehouse. On success, the outbox deletes the batch.

Data model: one envelope for every event

Every event, whatever its name, travels in the same envelope. Keeping the envelope fixed is what lets one collector and one warehouse table serve every customer.

type AnalyticsEvent = {
  messageId: string;          // crypto.randomUUID(), for dedupe
  type: "track" | "page" | "identify" | "group";
  event?: string;             // "Order Completed", for track only
  properties: Record<string, unknown>;
  traits?: Record<string, unknown>; // identify and group
  anonymousId: string;
  userId: string | null;
  sessionId: number;          // session start time in ms
  seq: number;                // per-session counter; gaps show lost events
  timestamp: string;          // ISO time of the track() call, device clock
  context: {
    page: { path: string; referrer: string; title: string };
    locale: string; screen: { width: number; height: number };
    library: { name: "our-sdk"; version: string };
    consent: { analytics: "granted"; marketing: "granted" | "denied" };
  };
  sampleRate: number;         // 0.2 means this event stands for 5
  priority?: "key";
};

The SDK also keeps a little state of its own between events. The rule for placing it: ids that must survive across subdomains go in a cookie, small values the SDK reads on every event go in localStorage because a synchronous read is fine when it's tiny, and anything that can grow, like pending events, goes in IndexedDB.

The collector API

POST /v1/batch HTTP/1.1
Host: collector.example-analytics.com
Content-Type: text/plain;charset=UTF-8

{"writeKey":"wk_live_3f9a","sentAt":"2026-10-21T09:14:03.120Z",
 "dropped":0,"batch":[{"messageId":"9b1e...","type":"track",
 "event":"Order Completed","timestamp":"2026-10-21T09:14:01.884Z", ...}]}

HTTP/1.1 200 OK
Content-Type: application/json

{"accepted":19,"rejected":[{"messageId":"c41d...","reason":"property total must be a number"}]}

• Auth: the writeKey identifies the customer's project. It's public by design (it's in their HTML), so it can only write, never read. Abuse is handled by rate limits per key and by allowed origins checked against the Origin header.
• Partial success: a batch is accepted even if some events fail validation. The response lists rejected ids and reasons, which the SDK prints in debug mode. The SDK never retries rejected events: they'd fail again.
• Errors: 400 for a malformed batch, 413 for too large, 429 with Retry-After for rate limits, 5xx for retryable server trouble. These map one to one to the retry rules in the queue chapter.
• Limits: 32 KB per event and 500 KB per batch on the server. The client's own caps are lower, so it never hits these in normal use.

Debugging, testing, and versioning

No user will ever report a missing event, so the SDK must make its own behavior easy to see, easy to test, and safe to change.

A debug mode customers actually use

• Turning it on: ?analytics_debug=1 in the URL (saved in sessionStorage for the visit), or analytics.debug(true) in the console. Nothing about it ships in the core except the check.
• What it loads: sdk-debug.js, with the schema validator, readable console groups per event (name, properties, plugins that changed it, sampling and consent decisions), and the validation result.
• The inspector panel: a small panel in the corner, inside a Shadow DOM so the host page's CSS can't break it, listing the queue, the outbox, the last batches with their status codes, and the current ids. The wireframe in What makes this hard shows it.
• Programmatic access: analytics.debugState() returns the queue length, outbox size, backoff timer, consent state, and sample decision, so customers' own end-to-end tests can assert on it.

Testing the SDK

• Unit tests with fake time and a fake transport: the queue is a pure state machine, so tests drive it with fake timers and assert "20 events cause one batch", "a 503 schedules a retry between 0 and 2 s", "a full queue drops the oldest normal event".
• Browser tests with Playwright in Chromium, Firefox, and WebKit: intercept the collector with page.route, then check that hiding the page sends a beacon, that consent pending sends nothing, and that a Back navigation from bfcache sends a page view.
• Contract tests: the collector's schema for the envelope is shared, and a test sends a real batch to a staging collector on every release.
• Host page tests: run the SDK on a test page that freezes Array.prototype, defines its own analytics global, uses a strict CSP, and loads an old snippet version. These are the pages that break SDKs in the wild.
• A size check in CI that fails if the core grows past its gzipped budget.

Versioning and caching the SDK file

Customers never update their snippet, but we must still fix bugs on their sites. So the snippet points at a major version URL like /v1/sdk.js, which always serves the latest compatible release. That file can't be cached for long, or a bad release would stick in browsers for days. The rest of the code lives in files named by content hash, which never change and can be cached for a year.

• Rolling out: a new core goes to 1% of page views first (the entry file picks a chunk by hashing the anonymous id), then 10%, then everyone, while we watch our own error rate and the delivery rate per version.
• Backward compatibility: never remove a method the snippet stubs; old snippets keep working forever. Deprecated options keep working and print a warning in debug mode only.
• Pinning: customers who need Subresource Integrity (an integrity hash on the script tag) or a strict review process can pin an exact version URL. They trade automatic fixes for control, and the docs should say so plainly.

Running it in the interview

This question rewards people who see the environment, not the code. Spend your time on the guest rules, the queue, and page death; the API itself takes two minutes.

Things worth saying out loud

Draw the architecture early and keep pointing at it. When you talk about the queue, point at the outbox; when the interviewer asks about privacy, point at the consent gate in the pipeline. It shows that every answer has a home in the design.

• "track() only captures and returns; everything else happens in idle time, because it runs inside the customer's click handler and counts toward their INP."
• "Delivery is at least once with a client-generated event id, so the collector can dedupe retries."
• "I flush on visibilitychange to hidden with sendBeacon, keep under the 64 KB budget, and never add an unload listener because it hurts the back/forward cache."
• "Sampling is per user with a hash, never per event, or funnels break."
• "While consent is pending, nothing is stored and nothing is sent."

Follow-up questions to expect