Documentation

MacroSession records visits to your web app as replays you can watch, tracks page views and the events you name, and flags the sessions where people hit rage clicks or JavaScript errors — all from one script.

Quickstart

  1. Create an account. You get a project with a public key (ms_…).
  2. Under Install, copy the two tags into the <head> of every page of your app.
  3. Visit your app, then open Sessions. Your visit is there within a few seconds.
<script>
  !function(w){var m=w.MacroSession=w.MacroSession||{q:[]};["identify","track","page","reset","optOut","optIn"].forEach(function(f){m[f]=m[f]||function(){m.q.push([f,[].slice.call(arguments)])}})}(window);
</script>
<script async src="https://macrosession.com/s.js" data-ms-key="ms_YOUR_PUBLIC_KEY"></script>

The first tag is a tiny stub: it defines window.MacroSession straight away and queues any calls made before the script arrives, so an identify() during your app's boot is never lost. The second loads the script asynchronously — it never blocks your page. Single-page apps need nothing extra: route changes are picked up from the History API.

What is captured

  • The replay — the page's structure and every change to it, mouse movement, scrolling and clicks, recorded with the open-source rrweb recorder. It is rebuilt in the player, not filmed, so it is small to send and sharp at any size.
  • Page views — every load and every route change, URL without the #fragment.
  • Clicks — a short CSS selector and the visible label of what was clicked (never text from inputs).
  • Rage clicks — three or more clicks in the same spot within 0.7 seconds.
  • JavaScript errors — uncaught errors and unhandled promise rejections, message only.
  • Session details — browser, OS and device class, screen size, language, referrer and UTM parameters.

A session is one browser tab. It survives reloads and ends after 30 minutes without activity. The script batches everything and sends it every five seconds, compressed, and once more when the page is hidden.

Identifying users

Call identify() once you know who is signed in. Their sessions then carry a name, and every session of theirs — on any device — is linked.

MacroSession.identify("user_123", { email: "ana@acme.com", plan: "pro" });

The id may use letters, digits and _ . : @ + -, up to 128 characters. Traits are flat: strings, numbers, booleans or null, up to 25 of them. Call MacroSession.reset() on sign-out so the next person on the same browser starts a fresh session.

Tracking events

MacroSession.track("Order Completed", { total: 42, currency: "USD" });

Names are 1–64 characters of letters, digits, spaces and _ . : / -. Properties follow the same rules as traits. Each event appears on the Events page — with who did it and a link that opens their replay at that moment — and in the session's timeline. The shape matches Segment's track call, so existing tracking plans carry over.

Privacy controls

Every form input is masked in the browser, before anything is sent: the replay shows asterisks, and click labels never include what was typed. Beyond that:

  • class="ms-block" — the element is never recorded; it plays back as an empty box of the same size.
  • class="ms-mask" — the element is recorded, but its text becomes asterisks.
  • class="ms-ignore" — interactions with the element are not captured.
  • Settings → Recording & privacy — mask all text project-wide, add a CSS selector that is never recorded, record only a percentage of sessions, or turn replays off and keep analytics.

Sensitive query parameters (anything named like token, password, secret, code, key, auth,session or email) are redacted from every stored URL. For consent banners, MacroSession.optOut() stops all recording and sending in that browser until optIn().

JavaScript API

MacroSession.identify(userId, traits?)   // name the person in this browser
MacroSession.track(name, properties?)    // a custom event
MacroSession.page()                      // a page view (automatic; for unusual routers)
MacroSession.reset()                     // on sign-out: new anonymous id and session
MacroSession.optOut()                    // record and send nothing in this browser
MacroSession.optIn()                     // undo optOut()

Server API

Authenticate with your project's secret key (mss_…, created under Settings → Keys). It is shown once and stored only as a hash. Never put it in a browser.

Track an event

POST https://macrosession.com/api/v1/events
Authorization: Bearer mss_...
Content-Type: application/json

{ "userId": "user_123", "event": "Invoice Paid", "properties": { "amount": 49 } }

An optional ISO timestamp backdates the event by up to a day. Server events have no session, so they have no replay.

List a user's sessions

GET https://macrosession.com/api/v1/sessions?userId=user_123&limit=20
Authorization: Bearer mss_...

{ "data": [ { "id": "…", "startedAt": "2026-10-11T12:00:00.000Z", "durationMs": 81000,
              "pages": 4, "errors": 0, "rageClicks": 1, "entryUrl": "https://app.acme.com/",
              "hasReplay": true, "url": "https://macrosession.com/app/sessions/…" } ] }

Put the url next to a support ticket: anyone signed in to your MacroSession account opens the replay in one click. Errors come back as { "error": { "type", "message" } } with status 401, 422 or 429.

Limits & retention

  • Sessions, replays and events are kept for 30 days, then deleted. Event-name totals are kept while the project exists.
  • Up to 5,000 recorded sessions per project per day while in beta. Past that, page views and events are still counted; new sessions are not recorded until the next day (UTC).
  • A single session stops growing its replay at 40 MB of recording data; its events keep counting.
  • Set Allowed origins in Settings once you are live, so your public key only works on your own domains.