The User Got Stuck and You Found Out Last: Session Replay and Heatmaps for Vibe Projects

A user says "your site is stuck" — and you don't even know which step they got stuck on: a fictional lesson first

First, a fictional teaching example. A-Lin built an online resume tool called "Resume Workshop" on her own with AI. Three months after launch, users were slowly growing — but the numbers in the admin panel looked wrong: signup conversion had dropped from 42% to 27%, and every few days a support email arrived saying "your site is stuck", "the save button does nothing", or "I filled in everything and it all disappeared". A-Lin opened her analytics dashboard and could only see "high drop-off at step 3" — but what actually happened at step 3? Was the button unclickable, was the error message unreadable, or did the page just go blank? She guessed for three weeks, shipped three revisions, and none of them fixed the real problem.

Then she added session replay, recording a random 5% of sessions. The case cracked on day one: on small phone screens, the "Save and continue" button on step 3 was pushed out of view by the on-screen keyboard, so users spent ages tapping the blank space below the button. Worse, when saving failed, the page only shivered slightly, with no error message at all — users assumed the network was slow and tapped a dozen times, submitting the form over and over. A-Lin fixed two things: the button became sticky at the bottom, and a failed save now shows a clear message. Two weeks later, conversion was back at 41%.

The point of this story: analytics tells you "something is wrong somewhere", while session replay tells you "exactly what happened". A team that only reads numbers fixes bugs by guessing; a team that watches replays fixes bugs by watching. This guide explains how to wire session replay and heatmaps into your vibe project: what to record and what not to record, how much is enough, how to handle privacy, how to read the three kinds of heatmaps, how to run the workflow from replay to fix, and finally a launch checklist. All names, product names, and numbers in the examples are fictional teaching examples, used only to make the ideas clear; the ratios and day counts are engineering rules of thumb, not any official standard — verify them against your own product and user volume before using them.

Setting the boundaries first: this guide only covers "watching how users actually use it" — not four other things

Before building anything, let's draw the boundaries. Several guides already published on this site cover neighboring territory, and this one is a new piece of the puzzle, not a repeat. The first is the analytics guide: events, funnels, and metrics — how many people came, how many left, which step loses the most. That is the "numbers" layer. The second is the error monitoring and crash reporting guide: frontend errors, crash reports, and error boundaries — the "did the code break" layer. The third is the usability testing guide: inviting real people in, watching them use the product, listening to them — the "actively go and test" layer. The fourth is the user feedback loop guide: users telling you what is wrong — the "users speak up" layer.

This guide covers a fifth situation: the user said nothing, nothing crashed, testing never caught it — but they got stuck and left anyway. Session replay and heatmaps solve "silent churn": the user never complained and never hit an error, they just quietly closed the page. In the analytics dashboard that only shows up as a number; in a replay it is a living sequence — "they clicked here, waited three seconds, clicked there, then closed the tab".

Three more things look similar but are not this guide's job. First, A/B testing: replay tells you where users get stuck, A/B testing tells you which version is better — they hand off to each other, but they are not the same job. Second, user interviews: interviews ask "why did you think that", replay shows "what you actually did" — one asks about motives, the other watches behavior. Third, performance monitoring: whether a page loads slowly belongs to performance monitoring; replay only covers "what the user did while it was loading slowly". The boundary matters in practice: replay and heatmaps are "watching" tools, not "measuring" tools and not "asking" tools. Get their position right first, then talk about how to use them.

1. What session replay actually records: not a video, a "re-performance"

First, clear up a common misunderstanding: session replay does not record the user's screen as a video. There is no MP4 sitting on your server. It records changes to the DOM — every click, scroll, keystroke, and mouse movement becomes a stream of events; on playback, the tool replays those events on a timeline and reconstructs the page the user saw. That mechanism determines three things. First, recordings are tiny — a session is usually a few dozen kilobytes. Second, playback can fast-forward, jump between segments, and filter by event. Third, and most importantly — a recording contains no pixels, only data, so you control exactly which data goes in and which stays out.

Five kinds of events in a session are worth recording. First, clicks: which element was clicked, the coordinates, whether it hit anything interactive. Second, scrolling and mouse movement: how far down the page the user went, where the mouse lingered longest. Third, input: how long the user spent in each field, how many times they deleted and retyped — but note, this records the behavior, not the content; the privacy section below goes into detail. Fourth, page changes: route changes, popups appearing, error messages, loading states. Fifth, session signals: rage clicks (many rapid clicks on the same spot), dead clicks (clicks on elements that do nothing), and u-turns (entering a page and immediately going back). Together, these five reconstruct "what the user actually went through".

Three kinds of things, on the other hand, should never enter a recording. First, the contents of sensitive fields — passwords, card numbers, ID numbers. Recording those is an incident waiting to happen. Second, the contents of files users upload or long private texts they paste. Third, the contents of third-party iframes, such as an embedded payment page — you cannot record them, and you should not try. The rule of thumb is one sentence: a recording should only contain "how the user interacted with your interface", never "what the user's private information is".

When choosing a tool, ask yourself three questions first. How big is your user base? A product with a few hundred daily users and one with a hundred thousand need completely different sampling strategies. Is your app a single-page app or multi-page? Single-page apps have more route changes and dynamic content, and the replay tool has to handle them well. And does your data need to stay in a particular region? Recording data sits on the vendor's servers by default; products with data-sovereignty requirements should pick a solution that supports self-hosting or a designated region. The answers to those three questions basically decide whether you use SaaS or self-host, what sampling rate to set, and how much budget to reserve.

2. How much is enough: sampling rate is a balance between cost and luck

The easiest trap with session replay is one of two extremes: record everything, or record 1%. Recording everything costs money and creates noise: a project with 10,000 daily users generates 300,000 recordings a month, storage and playback costs climb fast, and 99% of those recordings are "the user finished normally and left" — nobody has time to watch them. Recording only 1% is a luck problem: the bug you are hunting for may happen to fall in the 99% you never recorded, and when the complaint arrives, you still have no recording in hand.

Experience suggests three tiers. Tier one is "record critical pages in full": signup, payment, and core action pages — a user only walks through these a few times in their life, the cost of failure is highest, and full recording does not cost much anyway. Tier two is "sample ordinary pages": 5% to 10% is a common starting point, enough to build a useful sample without blowing up storage. Tier three is "record everything when triggered by a condition": the user hits an error, fails the same action three times in a row, or sits for over 5 minutes without progress — those sessions are automatically recorded in full, because sessions where something goes wrong are the ones most worth watching.

Sampling rate is not a set-and-forget number; it should move with the product's stage. In the first month after launch, when volume is small, record everything — the goal is to gather the first batch of "how real users actually use this" material as fast as possible. Once daily users pass ten thousand, switch to full recording on critical pages plus 5% sampling on ordinary ones. As volume grows further, adjust by "problem density": a page with a recent spike in complaints gets its sampling rate temporarily raised to 50%, then lowered again once the problem is fixed. Sampling rate is an operating parameter, not a one-time configuration.

One more money-saving trick: recordings only need to be kept for 30 days. The debugging window for almost any bug is the first two weeks after it appears; 30 days covers it comfortably. Recordings older than 30 days lose value off a cliff — unless you need to keep them as evidence for a support dispute. Keeping recordings for 30 days versus 90 days triples storage cost for less than 10% more value. Do that math before setting the retention period.

3. Privacy first: the first line of code for replay should be "what not to record"

Session replay is a feature where you decide what not to record before you decide what to record. Get the order wrong and you can have an incident on day one. Privacy handling has four layers, and each one should be settled before you start building.

Layer one is field masking. Password fields are not recorded by default — that is standard in replay tools. Beyond that, you need your own "sensitive fields list": phone numbers, emails, ID numbers, card numbers, addresses, medical records, salaries — any field where users type something that identifies a specific person. The contents are never recorded; only "this field was filled, for how long, edited how many times". Masking must happen on the client side — the data is scrubbed before it ever leaves the user's browser — not recorded first and deleted on the server later. Get the order wrong and the data has already leaked.

Layer two is content redaction. Some pages are inherently sensitive: notes users write themselves, chat histories, uploaded file names. The fix is to mask by page or by region: either the whole page is not recorded, or a specific region is blurred. Redaction rules belong in configuration that ships with the code, not in manual handling by operations staff after the fact — manual handling will always miss something.

Layer three is notice and consent. Before recording, users must be told "we record how you use the product to improve the experience", with a clear way to opt out. Different regions have different legal requirements — some require explicit consent, others only require notice — and the exact compliance wording depends on where your users are, which this guide does not go into in legal detail. But one baseline never changes: after a user opts out, their sessions must stop being recorded, and the opt-out must actually work when clicked.

Layer four is access control. Playback permission is not for everyone: only the developers and support staff who need it to investigate problems should have it, granted on a need-to-know basis. Support watches recordings to help a user solve a problem, not to gawk at how they behave; developers watch recordings to locate a bug, not to read a user's private life. Keep access logs — who watched which recording and when — so there is something to check if anything goes wrong. Only when all four layers are in place is replay a feature you can switch on with a clear conscience.

4. How to read the three heatmaps: clicks, scrolls, and mouse movement each answer a different question

If session replay is "watch one person", heatmaps are "watch a crowd". A heatmap overlays thousands of clicks, scrolls, and mouse movements on a screenshot of a page, using color intensity to show where collective attention went. The three kinds of heatmaps each answer a different question, and reading them wrong leads to exactly the opposite conclusion.

Click heatmaps show "where users thought they could click". The darkest spots are where the most people clicked. Read them against two questions. First, is the most-clicked place the place you wanted people to click? If "cancel subscription" is redder than "keep using", your interface is pushing people out the door. Second, are people clicking things that are not clickable? A decorative image, a line of explanatory text, a blank area — if there is a red blob on it, users thought it was a button. Either make it actually clickable, or change its "clickable" appearance. The most valuable discoveries from a click heatmap are usually these "clicked but nothing happened" spots.

Scroll heatmaps show "how far users got". They paint a color band down the page height, showing what share of users scrolled to each point. Remember one number when reading them: at the first break below the fold, usually only 50% to 70% of users arrive; each additional screen loses another chunk. So important content — pricing, core selling points, the call-to-action button — should not live only at the bottom of the page. The most common conclusion from a scroll heatmap is "users never saw that section", not "that section was badly written".

Mouse-movement heatmaps show "what users hesitated over". Where the mouse lingers, users were usually reading, comparing, or hesitating. Read them with one trap in mind: a resting mouse does not mean eyes were looking — plenty of people leave the mouse somewhere and go get water. So movement heatmaps are supporting evidence only, never a standalone conclusion. They work best cross-checked against click heatmaps: a spot where the mouse lingers long but nobody clicks is very likely a "users wanted to click but didn't dare" spot — an ambiguously worded note, a setting buried too deep.

Put the three together and there is an advanced use: comparing segments. New users' and old users' click heatmaps side by side look very different: new users click everywhere, old users go straight to the point. If new users' heatmaps are full of "dead clicks", your onboarding has a problem; if old users suddenly start clicking a corner nobody clicked before, a recently shipped feature is being discovered. A heatmap is not one picture — it is a set of comparisons.

5. From replay to fix: how to run a weekly "replay review"

With the tool wired up and recordings stored, the easiest step to skip is the one that matters most: who watches, when, and what happens afterward. Without a fixed routine, recordings become "stored but never watched" data garbage. A lightweight weekly routine in four steps works well.

Step one is triage: on Monday morning, the dev lead spends 20 minutes picking 5 to 10 "worth watching" recordings from the previous week. The filter has just three conditions: the most rage clicks, sessions where an error led directly to churn, and sessions where a user sat on a critical page for over 5 minutes without progress. Do not watch random samples — randomly picked recordings are almost always normal sessions, a waste of time.

Step two is the review: a fixed half hour each week, developers plus product plus support watching those 5 to 10 recordings together, 30 seconds to a minute of the key moment each. While watching, note only three things: which step the user got stuck on, why they got stuck, and how long the fix takes. The rule of the review is "watch the recording, don't argue about right and wrong" — when the recording shows a user clicking a dead button ten times, arguing "users should read the manual" is pointless; fixing the button is the job.

Step three is grading: whether to fix and when, in three tiers. P0 is "the user cannot pay, cannot sign up, or lost data" — fix it the same day. P1 is "the user got through but it was painful" — schedule it this week. P2 is "the user hesitated but got through on their own" — write it down and fix it in a batch later. When grading, remember: rage click counts are the most honest priority signal there is — where users click furiously is where it hurts most.

Step four is verification: after the fix, go watch fresh recordings of the same page and confirm the same problem is really gone. Many teams assume a fix worked once it ships — then users keep getting stuck in a different posture. The suggested verification window is one week after the fix goes live, with sampling temporarily raised to 50%, watching 20 fresh recordings, and lowering the rate only when it is clean. A fix without verification is the same as no fix.

This routine has a side benefit: it slowly changes how the team talks. Discussions used to be "I think users will do it this way"; now they are "in last Wednesday's recording, the user did it exactly this way". The first is guessing, the second is watching. The difference between guessing and watching is the difference between shipping three revisions that miss the point and cracking the case on day one.

6. Metrics and the launch checklist

Once replay and heatmaps are live, three metrics verify whether they are working. The first is the rage click rate: rage clicks per thousand sessions — it should start trending down in the first month. If it does not move at all, you are fixing things users do not actually care about. The second is the change in drop-off on critical pages: signup, payment, and core action pages should show visible recovery within two weeks of a fix. The third is the share of "can't explain it" support tickets: the kind where a user says "it got stuck" but cannot say where — those should keep shrinking, because support can now watch the recording instead of guessing.

Finally, the pre-launch checklist — 12 items, do not launch with any missing. Recording scope: critical pages recorded in full, ordinary pages sampled at 5% to 10%, condition-triggered full recording rules set, 30-day retention. Privacy: the sensitive-fields list written down, client-side masking verified working, per-page and per-region redaction rules configured, notice copy live, the opt-out actually clickable and effective, playback permission granted per person, access logs switched on. Heatmaps: click, scroll, and movement maps all wired up, segment comparison available by new versus returning users. Process: the weekly "replay review" on the calendar, P0/P1/P2 grading criteria written down, a post-fix verification window defined. All 12 checked, replay is truly live; miss one, and someone will be asking you a question you never thought of on day one.

In the end, session replay and heatmaps do not fix a tool — they fix a way of working: from "guessing what's wrong with users" to "watching what's wrong with users". When you guess, three revisions miss the point; when you watch, the case cracks on day one. Your users will not tell you which step they got stuck on — but their mouse will.