Reveal is a SaaS product that helps founders and product teams onboard new users with short, human video guides. A founder records themselves walking through the product inside a Chrome extension; their face appears as a circular camera bubble that follows the user from one tooltip step to the next. The dashboard at app.reveal.software manages those guides — grouping them into checklists, controlling when they appear, and showing how users actually move through them.
A guide can be delivered two ways: as live tooltips on the customer's real product (pixel-driven), or as an interactive embed — a chapter-based video player that lives in an iframe and works anywhere on the web. Same recording, same camera bubble, same analytics. Two surfaces.
This manual is the source of truth for what Reveal does. It's organised around features — analytics, embed, behavior, feedback — rather than the screens that contain them. Designers and engineers should both be able to read it end-to-end and finish with the same picture of the product.
Jump to
The feature areas of Reveal. Each one is a self-contained chapter.
What problem Reveal solves
SaaS onboarding has a tone problem. Static tooltips and pop-ups feel automated and skippable. Long onboarding videos sit on a separate page and never get watched. The middle ground — a real person walking the user through the product, in-context, step by step — has been impossible to scale because every founder would need to record a personalised Loom for every user.
Reveal makes that scalable. The founder records once. Reveal embeds the recording into the live product as floating tooltips with a camera bubble that follows along. New users get a guided tour that feels like a one-on-one demo. The team gets analytics on what actually lands.
01 · Foundations
Core concepts.
Six terms you'll see everywhere. Get the vocabulary right early and the rest of the manual reads cleanly.
Guide
The unit of content. A single recorded walkthrough made of one or more steps, attached to a customer's product. Has a status (draft, published, archived), an audience, an embed config, a behavior config, and analytics. The same guide can be delivered as live tooltips on the customer's site or as an interactive embed — see Playback mode below.
Created in the Chrome extension · managed in the dashboard
Step
A single moment inside a guide. A step targets one element in the customer's UI (via a CSS selector) and shows a tooltip there. Each step includes a short video clip with the founder's camera bubble.
Element selector · video · ordered within a guide
Camera bubble
The circular video of the founder that floats alongside the tooltip. The visual signature of Reveal. It humanises onboarding — the same words spoken by a real face land differently than the same words in a text bubble.
Recorded once · plays per step
Checklist
An ordered set of guides forming a multi-step onboarding journey. Think "first day at Acme" — five small guides that, taken together, get the user activated. Has its own funnel, its own widget, and rules for whether users must take them in order.
Sequential or free order · widget on customer site
Pixel
A small <script> tag the customer installs once, at the root of their domain. It identifies the user, decides which guide or checklist applies, renders the tooltip layer, and reports analytics. One pixel covers everything — every guide, every checklist.
Installed once per domain · one pixel = entire workspace
Playback mode
How a guide reaches the user. Reveal supports two modes from the same source recording. Live tooltips overlay the customer's real product via the pixel — what the manual has described from the start. Interactive embed plays the guide inside an iframe player, anywhere on the web, no pixel required on the host page. Both share the same recording, the same camera bubble, and the same analytics.
Two delivery modes · one recording · same analytics
How they relate
A workspace contains many guides. Guides can be grouped into checklists. Each guide can be delivered in one of two playback modes — live tooltips (through the pixel) or interactive embed (no pixel needed on the host page). Both modes are configured by the same behavior rules and report into the same analytics store. Most of the dashboard is dedicated to one of those six things.
02 · Feature
Authoring & Capture.
How guides come into being. Authoring is split between two surfaces: recording happens inside the Chrome extension, organising and publishing happens in the dashboard. The seam between them is the most important UX in Reveal — get it wrong and creators bounce between tools forever.
What creators do
Recording a new guide
The fundamental creation flow. Founder hits "Record new guide" and the extension takes over.
Extension
Trigger
"Record new guide" button on the dashboard's Guides page (top-right). It deep-links into the Chrome extension. The dashboard never records video — it only manages it.
In the extension — Personal Intro
Before the creator hits "Record new guide" they can toggle Personal Intro on or off. It's on by default. When the recording starts, a 3-second countdown plays, then the Personal Intro kicks in: the founder appears in a large central camera bubble — like a presentation — and speaks an opening message that precedes the actual walkthrough. When they're done, they click "Finish Intro" and move on to the guide itself.
In the extension — Speak then Click
After the intro (or immediately, if intro was disabled) the guide proper begins. Reveal uses a method called Speak then Click: the founder talks to camera while pointing the user toward a UI element, then clicks that element — and the click is what ends the recording for that step. One short video clip per step, automatically scoped to the action it describes.
Why Speak then Click matters
Because each step's video is its own self-contained clip, every step can later be re-recorded individually or replaced with a pre-recorded video — without touching the rest of the guide. That's the whole point of the method: it keeps editing local.
Positional data, captured alongside
While the screen is recording, the extension also captures structured data: timestamped cursor positions and the exact pixel coordinates of every click. This sits as a small JSON sidecar next to the video file. It costs almost nothing to record and unlocks features that come later — hotspot placement for the interactive embed, and the future polish layer (cursor smoothing, focus-cue zoom) for MP4 export. See Interactive Embed for how this data gets used.
What gets created
A draft guide with N steps (plus the optional Personal Intro). Title and description default to placeholders the founder edits later, in either surface.
Uploading a video for a step
Replace any step's recorded clip with a pre-recorded video — useful when a creator wants a more polished take.
Per-step
When it's used
After the initial Speak-then-Click recording, a creator might decide a particular step's video isn't quite right — wrong tone, background noise, fluffed line. Rather than re-recording inside the extension, they can upload a polished pre-recorded clip (e.g. a clean studio recording) and Reveal will swap it in for that single step.
What stays the same
The step's element selector, position in the guide, and tooltip placement are all preserved. Only the video changes. The camera bubble continues to follow the user through the UI as normal.
Why this matters
It's why Speak then Click was designed the way it was. Because each step is its own clip, each step can be improved on its own. Creators get the speed of in-context recording and the polish of pre-produced video, without picking one or the other.
What the dashboard does
Steps inspector
Read-only view of a guide's steps. Editing happens in the extension.
Dashboard
Per step
A thumbnail (auto-generated frame), title, the CSS selector being targeted, duration, and per-step completion data.
Open in Editor
Every step row has an "Open in Editor" affordance — clicking it deep-links back to the extension at that exact step. This is the one bridge between the two tools and it must be reliable.
Why read-only
Editing video in a web dashboard is a different (and much harder) product. Reveal's bet is that creators are happiest editing where they recorded, and inspecting where they manage.
Publishing & lifecycle
Three states a guide moves through.
PublishedDraftArchived
Draft
Default state for any newly-created guide. Drafts never appear to end users. Visually distinct in the dashboard — desaturated poster, dashed border, off-white background — so creators can scan their workspace and immediately see what's live and what's not.
Published
Live and eligible to fire on the customer's site (subject to behavior rules). Publishing is gated: a guide with zero usable steps cannot be published.
Archived
Hidden from the default view but not deleted. Archived guides keep their analytics history. Useful for retiring outdated content without losing the data.
Organisation & discovery
How creators find the right guide among many.
Dashboard
Status tabs
All / Published / Drafts / Archived. The default tab is All. Tab counts are always live.
Performance filter
High (≥70% completion) / Low (<40%) / Any. A common workflow: "show me my low-performing guides so I can fix them."
Has feedback / issues
Quick toggle to surface guides with new feedback or detected drop-off. A tactical view, not a permanent filter.
Gallery vs list
Gallery (default) shows poster previews — emotional, scannable, good for browsing. List is dense and sortable — better for power users with 50+ guides.
Bulk actions
Selecting multiple guides reveals a floating action bar. Supported: archive, delete. Designed for the moment when a creator audits their workspace and wants to retire a batch of outdated content.
03 · Feature
Analytics.
Reveal measures whether onboarding is actually working. Not vanity metrics — real signals about where users get stuck, which guides land, and what to fix next. The product's job is to turn raw events into one of three answers: "this is working", "this isn't working, here's why", or "we don't have enough data yet."
What we track
Eight events form the entire analytics foundation. Everything in the dashboard derives from these.
Event
What it means
Why we care
guide.started
A user reached step 1 of a guide
The denominator for completion. If starts are low, the trigger is wrong.
step.reached
A user reached a specific step
The bricks that build the funnel. Tells us where users actually go.
step.skipped
A user clicked "next" without engaging
Different from drop-off. Skip means "I don't need this", drop means "you lost me".
guide.completed
A user reached the final step
The success metric. Combined with starts, it gives the completion rate.
guide.skipped
A user dismissed the guide entirely
Surfaces guides that feel intrusive. High skip → fix the trigger.
guide.rated
A user gave a face rating
Qualitative signal — completion can be high while satisfaction is low.
checklist.started
The first guide in a checklist begins
Used in the journey funnel.
checklist.completed
All guides in a checklist done
The activation metric for whole onboarding journeys.
What we surface
Step completion
Per-step measurement of how many users who started reached this step.
Core
What it is
For each step in a guide, the percentage of users who started the guide that made it to this step. Always relative to step 1, never relative to the previous step.
Why it matters
It's the most actionable view in the product. Creators don't need to read a number — they look at the chart and know which step to fix.
Drop-off detection
Auto-flagging the steps where users actually leave.
Auto-flagged
Definition
Drop is the difference between this step's completion and the previous step's. If 90% reached step 2 and only 60% reached step 3, step 3 has a 30-point drop.
Threshold
Drops of 5 percentage points or more are highlighted in red. Drops of 10+ surface as warnings throughout the dashboard ("Leaks at step 3" pills on guide cards).
Why a threshold
Without one, creators see noise. With one, the signal travels — every drop badge in the UI is meaningful.
Completion rate
Top-level success metric for any guide.
Headline
Formula
Completed / Started. A guide that 100 users started and 70 finished has a 70% completion rate.
Where it appears
Headline KPI on Home, on every guide card, on the guide detail hero, and in the recent guides table. It's the number creators glance at first.
Time-windowed
Always shown for a given range (default 7 days). Compared against the previous equivalent range to show a delta — "completion rate is up 8% week over week".
Impressions & starts
Two related counts that track guide exposure and engagement.
Volume
Impressions
Number of times the guide had an opportunity to fire — i.e. a user matching the audience landed on a page where the trigger was met.
Starts
Number of times the user actually engaged (reached step 1). Starts ÷ Impressions tells us how compelling the trigger and intro are.
Why both
A guide with high impressions and low starts has a trigger problem. A guide with high starts and low completion has a content problem. Reveal needs both numbers to tell those stories apart.
Average watch time
How long users spend on the camera bubble videos before moving on.
Engagement
What it tells us
Average seconds spent per step before the user clicks next. Long watch time = the recording is engaging. Very short watch time on a long step = users are skipping past content the founder thought was important.
Caution
Don't penalise short watch time on its own. A confident "click here" video should be 3 seconds long and get skipped quickly. Read alongside completion, not in isolation.
Average rating
Qualitative score from the post-guide feedback screen.
Qualitative
Scale
Four faces — sad, neutral, happy, love. Mapped to a 1–4 score and shown as an average.
Statistical floor
Hide the rating until at least five users have rated. Below that, one grumpy user can drag a guide's score from "love" to "neutral" and creators will spend an afternoon worrying about a sample size of two.
Checklist funnel
Multi-guide completion analytics for whole journeys.
Checklists
What it is
Same idea as a step funnel, but the units are guides instead of steps. "How many users who finished guide 1 went on to start guide 2?"
Rendered as
A smooth curve with dots at each guide and dashed red rings on the guides where users abandon. Visually evocative; immediately tells you whether the journey is intact.
Auto-insight
When a clear bottleneck exists (≥10pp drop between two guides), Reveal generates plain-language insight: "34% of users who finish guide 2 don't start guide 3. Consider triggering guide 3 automatically." Helpful, not preachy.
Where analytics surface
Same data, different lenses depending on the page.
Inline mini-stats per card — completion bar, drop-off pill, feedback count
04 · Feature
Embed.
Four ways to put a Reveal guide in front of an end user. Customers pick whichever fits their existing site. They are not mutually exclusive — most customers install the pixel and use the dynamic link in onboarding emails. The fourth option, Interactive Embed, is a separate playback mode entirely; it has its own chapter.
The four options
1. Pixel — embed at the root level of the domain
One <script> tag in the customer's <head>. After that, every guide and checklist in the workspace can fire automatically based on behavior rules.
RecommendedOne-time install
Why this exists
The pixel is the foundation. Without it, end users cannot trigger a guide at all — not via the Reveal button, not via a dynamic link, not at all. Guides live inside the <script> (the pixel) on the customer's site, or alternatively inside the Reveal Chrome extension. With the pixel installed, Reveal becomes a continuous onboarding layer on the customer's product — every guide eligible to fire, every checklist available, all governed by audience and behavior settings.
The extension exception
A user with the Reveal extension installed can experience a guide on a site that doesn't have the pixel. This becomes useful later, when the product opens up to community-recorded tutorials — users teaching other users on apps they don't own the code to. Not a v1 priority, but the architecture supports it.
Install
Customer copies a snippet from the Embed tab and pastes it once into their site head. The snippet contains the workspace's unique pixel key.
Detection
The Reveal Chrome extension detects whether the pixel is installed and reports back. The dashboard shows a live status chip — "Pixel detected on acme.com · 4 pages" with a green pulse — so creators can confirm install is working without leaving Reveal.
Site-wide toggle
A workspace-level switch. When on, all published guides are eligible to fire across the customer's whole domain. When off, the pixel only fires guides that are explicitly invoked (via dynamic link or Reveal button).
Same pixel, all features
One pixel install covers guides, checklists, and any future product. Customers never need to install a second snippet. The Embed tab makes this explicit — "Already installed? Checklists use the same pixel as your guides."
Live diagnostics
Three small tiles on the Embed tab: detected domain + last ping, pageviews today, users currently mid-guide (with a pulsing dot). Real-time enough to feel alive without being a full ops dashboard.
2. Reveal button
A pre-styled button the customer can drop anywhere on their site. Clicking it triggers a specific guide on demand.
Manual trigger
Why this exists
Some guides shouldn't fire automatically — help-center articles, "show me how" links inside settings, optional tutorials. The Reveal button gives users the choice to start a guide on their terms.
Configuration
Three style options — Solid, Reveal red, Outline — and a custom label. The Embed tab shows a live preview of the button on a dotted canvas so creators can see exactly what they're shipping.
Output
A small HTML snippet the customer pastes wherever they want the button to appear. The snippet updates live as the creator changes style and label.
Use cases
In-app help menus · onboarding pages · empty-state CTAs · documentation. Anywhere a "Show me how" affordance makes sense.
3. Dynamic link
A URL parameter that fires a specific guide when present. Bridges Reveal into channels outside the product itself.
Cross-channel
Format
Append ?reveal={guideId} to any URL on the customer's domain. When a user lands there with that param, the pixel fires that specific guide regardless of normal trigger rules.
Why this exists
Onboarding doesn't only happen inside the product. It also happens in welcome emails, intercom replies, support articles, sales follow-ups. The dynamic link lets those channels deliver users straight into the right guide.
Properties
Never expires · unlimited uses · works for any user (no audience matching). It's an explicit "I want to see this" signal from the user clicking the link, so we honour it unconditionally.
Use cases
Welcome emails ("here's how to get started") · feature announcements ("watch the founder show you what's new") · support articles · cold outreach with a personalised demo.
4. Interactive Embed
A self-contained interactive player that can live on any page, anywhere on the web. The same guide, delivered as a chapter-based player instead of as live tooltips.
TBDNew playback mode
What it is
A YouTube-style player rendered inside an iframe — the screen recording as background, the camera bubble visible throughout, hotspots showing where to click. Each Speak-then-Click step becomes a chapter. The viewer drives pacing by clicking through.
Why this exists
Live tooltip mode (pixel) only works on a customer's own site, where they control the code. Interactive Embed works anywhere — marketing pages, help-center articles, partner sites, even sites the creator doesn't own. It's the same guide, delivered as a self-contained widget rather than as an in-product overlay.
No pixel required
The interactive embed is fully self-contained. The widget brings everything it needs — video, camera bubble, hotspots, analytics — without depending on the pixel being installed.
Where it's configured
The snippet to copy lives here in the Embed tab as a fourth option. The player itself — its preview, looping cover, controls, bubble position, MP4 export — is tuned in a dedicated Interactive Player tab on Guide Detail. Snippet here; player tuning there.
Guides to fire automatically on the customer's product
Pixel
Users to start guides on their own terms, inside the product
Reveal button
To send users into a specific guide from email or external content
Dynamic link
A self-contained guide for marketing pages or sites you don't own
Interactive Embed
All of the above (most customers)
Pixel + button + link + interactive embed together
Checklists embed slightly differently. They share the same pixel as guides, but instead of inline tooltips they render as a floating widget — typically bottom-right corner, with a header showing "N of M complete", a strikethrough list of completed guides, and a progress bar. Position is configurable; style is configurable; the rest is consistent.
05 · Feature
Interactive Embed.TBD · Work in progress
Reveal has two delivery modes for a guide. Live tooltips overlay the customer's real product, driven by the pixel — that's the original mode the rest of the manual describes. Interactive Embed is the second mode: the same guide, recorded the same way, but delivered as a chapter-based video player inside an iframe. It works on any page on the web — including pages the creator doesn't own — without requiring a pixel on the host site.
One recording. Two ways to play it back. Same camera bubble. Same analytics. The architectural framing matters: this is not a separate product. It's a new rendering of the same Guide object.
Two delivery modes side by side
Live tooltips (pixel)
Interactive Embed
Where it plays
On the customer's real product
Anywhere on the web, inside an iframe
Requires pixel?
Yes, on the host page
No
Background
The actual live DOM
The recorded screen video
Camera bubble
Follows tooltips, anchored to elements
Fixed corner (v1) — see below
Driven by
Pixel + behavior rules
Viewer clicks (chapter playback)
Best for
Active onboarding inside the product
Marketing pages, help centres, external sites, demos
Capture quality starts in the extension. For Interactive Embed and MP4 export to look good, the source recording needs a consistent 16:9 aspect ratio. That's the job of the Window Resizer in the Chrome Extension — an opt-in "Snap to 16:9" before recording starts. See the Chrome Extension chapter for the full behaviour, including fallback for smaller screens.
What the viewer experiences
The interactive player
A YouTube-shaped player with chapter-based playback. Each Speak-then-Click step becomes a chapter; the viewer drives pacing.
Core
Player anatomy
The recorded screen video as the canvas. The camera bubble rendered on top. A timeline scrubber at the bottom with chapter marks (one per step). On hover, the controls bar reveals — Arcade-style. Hotspots pulse over the target element when a chapter is waiting for input.
Chapter-based, not continuous
Each step plays through, then pauses at the click moment. The hotspot pulses where the click should happen. The viewer clicks the hotspot to advance. This is the central UX choice — it converts a passive watcher into an active learner, and it gives us per-step analytics (every advance is step.reached, every drop is locatable). Continuous playback would throw all that signal away.
Personal Intro plays as the opening chapter
If the guide was recorded with Personal Intro on, it becomes chapter 0 — the founder's face in the centre of the player, like a presenter opening a talk. A nice moment that neither Arcade nor Navattic has.
Cover thumbnail
A short looping muted video (2–3 seconds) of the Personal Intro plays as the player's poster — a tiny "live" preview before the viewer hits play. Same idea as a GIF, but encoded as a small MP4 or WebM via <video muted loop autoplay playsinline> — smaller, full colour, and accessibility-friendly.
Player controls (v1)
Mute toggle · Fullscreen · Replay (jumps back to chapter 0). These are the controls that ship in v1 alongside the chapter playback model.
Captions TBD
Planned feature, not in v1. Auto-generated transcripts as a baseline, with creator-editable captions and multi-language support down the line. Captions are an entire subsystem of their own — source pipeline (Whisper / Deepgram), VTT storage, an editing UI, translations, burn-in for MP4 export. Worth doing well rather than fast.
Where it lives in the dashboard
Two surfaces, deliberately separated:
The Embed tab on Guide Detail holds the snippet — the iframe code customers copy into their pages. It sits alongside Pixel, Reveal Button, and Dynamic Link as a fourth delivery option. Symmetrical with how the other delivery methods are presented.
The Interactive Player tab on Guide Detail is where the player itself gets tuned — live preview, looping cover, player options (autoplay, default muted state, controls visibility, dimensions), bubble position, MP4 export, and eventually captions. This is its own tab because there's enough to configure that putting it in Embed would dwarf the other three cards.
Naming convention: the delivery option is called Interactive Embed everywhere (it's a peer to Pixel, Button, Link). The configuration surface inside one guide is called Interactive Player. Read as: "Use Interactive Embed to put the guide on a marketing page; the Interactive Player tab is where you decide how it looks."
Embedding it
Snippet & sizing
How customers actually put the player on a page.
Self-contained
Snippet
An iframe-based embed snippet generated per guide. The customer copies it from the Embed tab and pastes it into any HTML page. Responsive width by default; aspect ratio locked to 16:9.
No pixel needed on host page
The player is fully self-contained — it brings its own video, camera bubble, hotspots, and analytics. The host site doesn't need the Reveal pixel installed. This is what makes the Interactive Embed work on marketing pages, partner sites, blog posts, anywhere.
Analytics still report home
Even though the embed runs without a pixel on the host page, it still posts analytics events back to Reveal — guide.started, step.reached, step.skipped, guide.completed. Same event names as live tooltip mode, same data shape, same store. From the dashboard's point of view, an Interactive Embed view is just another view of the guide.
Where the camera bubble lives in this mode
v1: Fixed bottom-right
In v1, the bubble parks in a fixed corner of the player — bottom-right by default. This is the well-understood "picture-in-picture" / YouTube-call vocabulary that viewers already know how to read. The bubble doesn't compete with the click hotspot for attention because the hotspot is in the screen recording, not the corner. Predictable, ships fast, looks right.
v2 (TBD): Dynamic positioning
A future iteration could compute the bubble's position from the click hotspot — placing the bubble in whichever corner is furthest from the action, so it never obscures. More dynamic, more "live tooltip"-like. Deferred until v1 has been used in the wild and we know whether the static corner feels lifeless.
MP4 export
Export a guide as a flat video
For customers who want to publish onboarding content to YouTube, embed in slide decks, or share as a file. On-demand server-side render.
TBD
What it is
An on-demand export that produces a single .mp4 file containing the entire guide — screen recording, camera bubble, tooltips, all composited together as one continuous video. Triggered from the dashboard ("Export as MP4"); runs as a server-side render job; the customer is emailed a download link when it's ready.
Why this exists
The Interactive Embed wins on interactivity. The MP4 wins on distribution — YouTube, X, LinkedIn, slide decks, customer-success emails with an attached video. Both have a place. We give customers both outputs from the same source recording.
The honest tradeoff
An MP4 of an interactive guide strips the thing that made it interactive. Customers should expect to use this as a distribution format, not as the primary artifact. Live tooltips and Interactive Embed are how the guide is experienced; MP4 is how it gets shared on platforms that don't host the embed.
Composition pipeline
Server-side FFmpeg job. Inputs: the per-step screen clips and camera clips (already stored — see Authoring). Outputs: a single .mp4 with screen as background, bubble composited as overlay, tooltips burned in, transitions between steps. Raw quality in v1 — the polish layer (below) lands in v2.
The polish layer
Cursor smoothing & focus-cue zoom
Screen-Studio-style motion polish, applied at playback (embed) and at export (MP4). Capture data now; render polish later.
TBD · v2
Cursor smoothing
The extension already captures the cursor path as timestamped data alongside the screen recording (see Authoring). The polish layer ignores the hand-recorded cursor in the video and draws a synthetic cursor on top, with its motion run through a spring physics curve. The result is a broadcast-quality smooth cursor instead of the jittery one the creator actually moved.
Focus-cue zoom (not magnification)
At click moments — captured precisely as positional data — the renderer applies a soft transform that zooms toward the click target. This is a focus cue, not a magnifier. Constrained to 110–140% range, held for ~0.5–1 second, eased back out. Inside that range, 1080p source holds up cleanly. Outside it, the upscaling becomes visible.
Why the constraint matters
Screen Studio's zoom looks great because it's used as a focus cue, not as a magnifying glass. Customers who try to zoom into a 12px label and read it clearly will be disappointed — and shouldn't try. The product constraint should be explicit: focus-cue zoom, 110–140%, designed to direct attention rather than reveal detail.
Deeper zoom — a future option
For premium creators who need broadcast-quality 200% zoom, the answer is to capture at higher resolution (2560×1440 or 4K) and render at 1080p — so even a 2× zoom is sampling native pixels. Bigger files, longer uploads, but the option exists. Out of scope for v1.
Where polish applies most
Interactive Embed viewers are clicking through and not paying attention to subtle motion. MP4 viewers are sitting back and watching. The polish layer earns its keep most in MP4 export — that's where smooth cursors and soft zooms turn an okay recording into something postable on YouTube without embarrassment.
One guide, three outputs
The architectural claim that makes all of this feel small rather than overwhelming: one recording produces three renderings. The creator records once — Personal Intro plus Speak-then-Click steps. Reveal stores the screen clips, camera clips, and positional data side by side as inputs. From those inputs, three outputs are rendered, each at its own moment:
1. Live tooltips
Rendered at runtime, on the customer's real product, through the pixel. Screen recording is invisible — the real DOM is the screen. Camera bubble renders as a positioned element. Tooltip overlays the live DOM.
2. Interactive Embed
Rendered at runtime, inside an iframe player, anywhere on the web. Screen recording is the canvas. Camera bubble renders on top in a fixed corner. Hotspot pulses where the click should land. Each step is a chapter.
3. MP4 export
Rendered on demand, server-side, as a flat video file. All inputs composited into one continuous .mp4 — screen background, bubble overlay, tooltips burned in. The polish layer (cursor smoothing, focus-cue zoom) applies here most visibly.
Recording is the input. Rendering is the output. Anything that improves how Reveal renders — better cursor physics, better zoom, better transitions, dynamic bubble positioning, even renderings we haven't thought of yet — can be applied to guides recorded today. The polish gets better; the recordings don't have to be redone.
06 · Feature
Behavior.
Behavior controls when a guide fires, who sees it, and what happens when they choose not to engage. It's the difference between a helpful nudge and an annoying pop-up. Every guide and every checklist has its own behavior config.
The five behavior questions
Trigger — when does it fire?
The single most important behavior decision. Get this wrong and even great content fails.
Critical
Auto on load
Fires immediately when the user lands on a matching page. Best for new-user onboarding where there's nothing else competing for attention.
After delay
Fires N seconds after the page settles (configurable 0–30s). Best for guides that should show up after the user has had a moment to look around. The slider in the UI lets creators try different values before committing.
Manual
Doesn't fire on its own. Triggered only by Reveal button or dynamic link. Best for help-center content where the user opts in.
On element click TBD
Fires when the user clicks a specific element (defined by CSS selector). Best for tying a guide to a specific feature — "show me how to set up integrations" tied to the integrations tab.
Audience — who sees it?
The targeting question. Wrong audience and right content still feels like spam.
Targeting
New users
First-time visitors only. The default for most onboarding guides — show it once during the first session, then move on.
Returning
Users who've been to the site before. Useful for "what's new" guides aimed at existing customers.
All users
Everyone. Use sparingly — the most common reason a Reveal feels intrusive is an "all users" guide on a high-traffic page.
Custom segment TBD
Match users by traits passed to reveal.identify() — plan tier, signup date, role, anything. The escape hatch for customers who already segment users in their own product.
How identity arrives TBD
The customer site calls reveal.identify(userId, traits) on every page — same pattern as Segment or Mixpanel. Reveal stores the user → traits mapping and uses it for audience matching.
On skip — what happens when they dismiss?
How polite is the guide if the user closes it?
Politeness
Resume next session
Show the guide again on the user's next visit, picking up where they left off. The most forgiving option — best for non-essential content the user might want later.
Restart next session
Show the full guide again next session. Useful when the guide is short and the value is worth a second look.
Never show again
If the user dismissed it, they meant it. The most respectful option for repeat traffic.
Skip threshold
A safety net. Even with "resume next session", after N skips (1–10, configurable) the guide gets permanently dismissed for that user. Default is 3. Reveal should never feel like nagging.
Frequency cap — how often is too often?
Maximum exposure rate for users who haven't dismissed.
Politeness
Once
Show the guide one time only. Most onboarding content lives here.
Daily / Weekly
Show at most once per day or once per week. For announcements or seasonal nudges that should re-surface but not constantly.
Unlimited
Show on every matching session. Reserved for help-center style content — only ever paired with a Manual trigger.
Feedback screen — ask for a rating?
Whether to show the face-rating screen after the final step.
Per-guide toggle
When on
After the user completes the last step, the camera bubble dismisses and a small face-rating screen appears: sad / neutral / happy / love + optional comment. See the Feedback feature page for full detail.
When off
Guide ends silently. Recommended for short utility guides where a feedback prompt would feel disproportionate.
Behavior for checklists
Checklists inherit the same five behaviors as guides, plus three more specific to journeys.
Guide order
Sequential — users must complete guides in order, each one unlocking the next. Free — users can take any guide first. Sequential is right for "tutorial" journeys; free is right for "checklist of optional things to try".
On full completion
What happens when the user finishes the last guide. Celebration screen (default — confetti, well done), quietly dismiss, or redirect to URL (e.g. send them to a "next steps" page).
Feedback after each guide
Toggle. When on, the face-rating screen appears after every guide in the checklist. Useful for granular feedback but use sparingly — five rating prompts in a row is fatiguing.
Behavior is the safety layer. Reveal can fire video tooltips on someone else's site — that's a powerful and slightly invasive thing. Behavior settings (skip threshold, frequency cap, "never show again") are the controls that keep it polite. They are not optional features. They are how Reveal earns the right to be on the page.
07 · Feature
Feedback.
Completion tells you whether users finished a guide. Feedback tells you whether they actually liked it. Reveal collects qualitative signal in the lightest possible way — four faces, an optional comment, no forms — and feeds it back into the dashboard where creators see it next to the guide it's about.
How feedback gets collected
The face-rating screen
The smallest possible feedback ask, shown after the guide's final step.
End-of-guide
When it shows
After the user reaches the last step, only if the guide's behavior config has "Feedback screen" turned on. Skipped guides never get a feedback prompt — only completed ones.
What it asks
"How was that?" — followed by four large face icons: sad, neutral, happy, love. One tap, done. An optional text field appears after a face is selected, never before.
Why faces, not stars
Faces are emotional and instant. A 5-star rating asks the user to compute a number; a face asks them to react. Reaction data is more honest, especially for short interactions.
Privacy
Feedback is tied to the user identity passed via reveal.identify(). If the customer's audience setting is "anonymous", emails are masked in the dashboard (j••••@acme.com).
Per-guide vs per-checklist feedback
Two different cadences — same UI.
Configurable
Per-guide
Default. One prompt at the end of one guide. Quick and proportional.
Per-checklist (after each guide)
When the "Feedback after each guide" toggle is on for a checklist, the prompt fires after every guide in the journey. Granular but fatiguing — recommended only for short checklists (≤3 guides).
How feedback gets shown
Rating breakdown
The aggregate view — how do all users feel about this guide?
Aggregate
Where it lives
Guide detail Overview tab, alongside the funnel chart. Always paired with completion data — feedback without context is misleading.
Visualised as
A stacked bar — love, happy, neutral, sad — segments coloured from green to red. Below it, a per-face row showing the icon, label, count, and percentage. The bar gives the feeling at a glance; the rows give the numbers.
Average rating
A single number derived from the breakdown (sad=1, neutral=2, happy=3, love=4). Shown as a face icon on guide cards and tables. Hidden until ≥5 ratings — see Analytics for the statistical floor reasoning.
Latest feedback stream
The qualitative view — what are people actually saying?
Qualitative
Where it lives
Two places. (1) Home page, sticky panel on the right showing the 3 most recent feedback entries across the whole workspace. (2) Guide detail, showing the latest entries for that specific guide.
Per entry
The face the user picked · the optional comment in quotes (truncated to ~140 chars) · the user's email · the guide it relates to · a relative timestamp ("2h ago"). Compact, readable, scrollable.
Why it matters
The breakdown tells you "23% of users were sad". The stream tells you why. Most of Reveal's product improvements happen because a creator read three sad-face comments in a row and immediately knew what was wrong.
Feedback as a filter
Surface guides that need attention.
Discovery
"Has feedback / issues" toggle
On the Guides list page, a quick filter that shows only guides with new feedback or detected drop-off. The intended workflow: open Reveal weekly, hit this filter, fix three things, close the tab.
Feedback count on guide cards
Every guide card displays its feedback count. New, unread feedback is visually distinguished — a small dot — so creators can see at a glance which guides have unread responses.
Why feedback is its own feature, not a sub-feature of analytics
Analytics tells you what people did. Feedback tells you what they thought. They use the same data pipeline but they answer different questions. A guide with 90% completion and 80% sad-face ratings is technically successful and clearly broken — and only by treating feedback as its own first-class signal does that contradiction surface.
08 · Feature
Checklists.
A checklist is several guides bundled into a single onboarding journey. If a guide is "let me show you this one thing", a checklist is "let me show you the five things that matter on day one." Same content building blocks, longer story arc.
What a checklist is
Structure
An ordered list of guides plus a layer of journey-level configuration.
Contents
A title, a description, and an ordered array of guide IDs. Plus its own audience, embed config, behavior config, and analytics — which apply to the journey as a whole, not the individual guides.
Status
Two states only — published or draft. No archive (a checklist with no value gets deleted, not archived).
Creating a checklist
Two-step modal. Light, fast, optimised for the common path.
Wizard
Step 1 — Details
Name (required), optional description, audience selector. Audience defaults to "New users" — most checklists are for onboarding.
Step 2 — Add guides
Searchable, scrollable list of all guides in the workspace. Creator selects one or more. The "Create checklist" button is disabled until at least one guide is selected.
After creation
Lands the user on the checklist's detail page in draft state. Order, audience, and behavior can all be refined before publishing.
Reordering & managing
The order matters
Guides in a checklist are ordered. The order is shown to users (in the widget) and used by analytics (the journey funnel).
Critical
How to reorder
Two ways, both supported in the same table. (1) Drag the grip handle to reposition. (2) Use ↑/↓ arrows to nudge one position. Both are needed — drag is fast for big moves, arrows are precise for small ones.
Save explicitly
Reorder changes are local until the creator clicks "Save order". The unsaved-changes state is visible (badge in the tab) so creators don't accidentally navigate away. This is intentional friction — accidental reorders would silently break a journey.
Per-row health
Each guide row shows its status in the journey context — "Healthy" or "Leaks step N". A guide that performs fine standalone might leak inside a checklist; this column surfaces that.
Removing a guide
Trash icon, hover-reveal. Confirmed via inline popover, not a full dialog — the action is reversible (the guide still exists, just not in this checklist).
The checklist widget
How users see a checklist
A floating panel on the customer site. Different from how guides appear (inline tooltips).
End-user
Anatomy
Dark header — checklist name, "N of M complete" counter, percentage circle. Body — guide list with completed items struck through and greyed, the next item highlighted with a "Next" chip. Footer — progress bar.
Style options
Floating panel (default — bottom-right, configurable to any corner) or Inline embed (renders into a div the customer places in their layout). Floating is more attention-grabbing; inline is more polite.
Position
2×2 picker in the Embed tab. Any corner of the viewport. Position is per-checklist, not per-workspace — different journeys can live in different corners.
Live preview
The Embed tab shows the widget rendered on a dotted canvas, in the chosen position, with mock progress. Change the position picker and the preview moves immediately.
Why checklists are not just multi-guides
It would be easy to think of a checklist as a folder. It isn't. A checklist is its own object with its own analytics (the journey funnel) and its own behavior controls (sequential vs free order, on-completion behavior). The story it tells — "here's how a user moves through your whole onboarding" — is qualitatively different from the story of any individual guide. The data model and the UI both treat them as first-class.
09 · Feature
Workspace & Team.
Everything around the content — who has access, what brand it ships under, where data goes, who pays. Not glamorous, but it's the difference between a tool one founder uses and a product a team adopts.
Workspace
Identity & branding
How the workspace shows up — to the team and to end users.
Workspace name
Editable display name. Shown in the sidebar header and on shared content. Defaults to the company name from signup.
Logo
Optional uploaded image. Shown in the sidebar and in any branded surface (e.g. the Reveal button). PNG, SVG, or JPG; square; ≥256px.
Workspace URL
A slug under reveal.software (e.g. reveal.software/acme). Used for any shareable workspace links. Lowercase, hyphenable, 3–32 chars.
Site domain
The customer's domain where the pixel is installed. Reveal verifies the pixel is reachable on this domain and shows a green "Verified" chip. Without verification, the pixel still works, but the chip stays grey — a small honest signal that something's not quite hooked up.
Team & roles
Roles
Three levels of access. Deliberately simple — most teams using Reveal are small.
Admin
Manage workspace settings, team, billing, danger zone. Typically the founder or ops lead.
Editor
Create and publish guides, manage checklists, edit behavior, view all analytics. Cannot touch billing or team membership. The default role for product/marketing folks.
Viewer
Browse guides and analytics. Cannot edit. Useful for stakeholders who want visibility without the keys.
Last admin
A workspace must always have at least one admin. The last admin can't demote themselves. They can only transfer admin to someone else first.
Invitations
Email-based, magic-link.
Flow
Admin enters an email + role, hits Invite. Recipient gets a magic link that's valid for 7 days. Pending invites are listed separately above accepted members. Each invite can be re-sent or revoked individually.
Member table
Shows everyone in the workspace with their avatar, name, email, join date, and an inline role switcher. The current user's row shows a "You" chip and disables the role switcher and remove button on themselves.
Account
Personal account settings
Per-user, separate from workspace settings.
Profile
Avatar, name, email. Email shows a "Verified" chip when verified. Changing email re-triggers verification.
Password
Current + new + confirm. Hidden if the user signed up via Google — instead, a small notice explains where they sign in from.
Two-factor
Toggle. TOTP only (apps like 1Password, Authy, Google Authenticator). No SMS — too easily compromised. Recovery codes generated on enable.
Notifications
How creators stay informed
Two channels — email and Slack — with per-event control.
Email digest
Frequency: Off / Daily / Weekly / Monthly. The digest summarises new feedback, drop-off changes, and new completions across the workspace.
Per-event toggles
Drop-off spike alert · New feedback received · New user started a guide · Guide published. Each toggleable on its own. Most creators turn on drop-off and feedback only — the others get noisy fast.
Slack
Connect via OAuth, choose a channel. Same per-event toggles apply. Recommended for teams that already live in Slack.
Integrations
Third-party data destinations
Send Reveal events to where the team already analyses data.
Initial set
Segment, Mixpanel, Amplitude, HubSpot, Intercom. The five places SaaS teams already track user behavior.
What flows out
All eight analytics events (started, reached, completed, etc.) with full payload. The integration partner decides what to do with them.
Segment passthrough
Segment is special — Reveal can also receive identify calls from Segment, so customers who already segment users don't have to call reveal.identify() separately.
API & webhooks
Programmatic access
For customers who want to build their own integrations.
API keys
Generate, rotate, revoke. Three scopes: read, write, admin. Live keys are partially masked in the UI; full key is shown once at creation and never again.
Webhooks
Customer provides an endpoint URL and selects which events to receive. Reveal posts each event as soon as it arrives. Failed deliveries retry with exponential backoff for 24 hours, then auto-disable with an admin email.
Signing
Every webhook is signed (HMAC-SHA256). The customer verifies the signature server-side. This is non-negotiable — anyone can guess a webhook URL, but only Reveal has the secret.
Billing
Plan, payment, usage
Stripe-backed; metered on impressions.
Plans
Free, Pro, Scale, Enterprise. Each has an impressions cap, a seat cap, and a feature set. Plans are workspace-level; teams pick one and grow into it.
Usage bar
Shows impressions used out of the plan cap, with a fill bar. Warns at 80% (yellow) and 100% (red). Resets on the billing date.
Invoices
Per-billing-cycle invoice list with date, amount, paid status, and PDF download. Auto-generated from Stripe.
Danger zone
Irreversible actions
Visually separated; each requires the user to type the workspace name to confirm.
Transfer workspace
Hand ownership to another admin. Requires 2FA challenge.
Export all data
Async job. The export bundle (JSON manifests, video files, analytics CSV) is emailed as a ZIP link with 24h expiry. Always available, even on Free.
Delete all guides
Soft-delete with 30-day recovery. A banner appears for admins during the recovery window.
Delete workspace
Hard-deletes after a 30-day grace period. The pixel stops firing immediately. Final.
10 · Feature
Chrome Extension.
Reveal is a two-surface product: the dashboard and the Chrome extension. The extension is where guides are actually recorded — it sits over the customer's product, captures camera and screen, and lets the founder mark which UI elements each step targets. This manual focuses on the dashboard, but the seam between the two surfaces shapes the whole UX.
What the extension does
Records guides in-context
The founder navigates to the live product, hits "Capture step", and the extension records a short clip with their camera bubble overlaid. Each capture is a new step. The element being demonstrated is auto-detected from the click, generating the CSS selector that the published guide will use.
Edits steps
Re-record, retarget, trim, upload video — all step-level editing happens in the extension. The dashboard inspects; the extension authors. This split is intentional — see the Authoring chapter for the rationale.
Detects the pixel
When the extension is open on a customer's domain, it checks whether the Reveal pixel is installed and reports back. This is what powers the live "Pixel detected" status chip in the dashboard's Embed tab.
Captures positional data alongside the video
While the screen is being recorded, the extension also captures timestamped cursor positions (sampled at ~30Hz) and the exact pixel coordinates of every click. This sits as a small JSON sidecar next to the video file. It's cheap to record now and impossible to recover later — so we capture it on every recording, even if we don't render anything fancy with it yet. The data unlocks hotspot placement in Interactive Embed and the future polish layer (cursor smoothing, focus-cue zoom) for MP4 export.
Window Resizer
Snap-to-16:9 before recording
An opt-in button that resizes the Chrome viewport to a clean 16:9 frame, so every guide produces consistent screen capture suitable for video export.
Opt-in
Why it exists
Without it, every creator records at whatever window size they happen to have open. The result is a library of guides with inconsistent dimensions — some 1366×768, some 1440×900, some odd half-screen sizes. That makes MP4 export look amateurish and the interactive embed inconsistent. Snapping to 16:9 before recording fixes the problem at the source.
What it does
Before the creator hits Record, the extension offers a "Snap to 16:9" button (recommended). When accepted, the Chrome viewport is resized to 1920×1080 exactly — the window grows slightly to accommodate the address bar so the content area is precisely 1080p.
When the screen is smaller than 1080p
Many laptops (e.g. 1366×768, 1440×900) can't fit a 1920×1080 viewport. In that case the extension silently falls back to the largest 16:9 dimension that fits the screen — typically 1280×720 — and shows the chosen resolution prominently in the recorder UI. The creator isn't blocked; they just produce a 720p recording instead.
When the screen is larger than 1080p
On 1440p and 4K displays, the viewport still snaps down to 1920×1080. The window looks smaller than the surrounding desktop, but the output is predictable. 4K capture (3840×2160) is a planned premium option but not v1 — bigger files, longer uploads, marginal benefit for onboarding content.
Opt-in by design
The creator can decline the snap. Some recordings genuinely benefit from a different ratio (a mobile-view demo, a portrait layout). The extension respects the choice; the snap is a recommendation, not a requirement.
How the dashboard talks to it
Deep links
Custom-protocol URLs the dashboard fires to drive the extension.
"Record new guide"
Opens the extension into recording mode, fresh slate. The new guide is created when the founder captures the first step.
"Open in Editor" (guide)
Opens the extension's editor with the chosen guide loaded. Most-used deep link in the product.
"Open in Editor" (step)
Same as above, but jumps to a specific step. Used from the Steps tab on guide detail.
"Open in Editor" (checklist)
Opens the extension on the checklist's preview surface (so creators can run through it as if they were a user).
The Extension settings panel
Installation status & permissions
Settings → Extension. A status mirror, not a configuration page.
Connected card
When the extension is detected, this card shows the icon, name, "Connected" chip, version, last seen, and device. Plus actions: "Open editor" and "Disconnect".
Permission tiles (×2)
Camera · Microphone. Both are required for recording. Reveal records audio through a dedicated microphone, not through the camera stream — so a creator can pick a specific mic (e.g. their podcast mic, an external interface) and the extension respects that selection.
Install card
Shown only when no connection is detected. A nudge to install the extension from the Chrome Web Store with a primary "Install extension" button.
11 · Surface
Pages tour.
Six pages make up the dashboard. Each one has a single primary purpose; everything else is in service of that. This is the surface-level view of the product — what users actually see when they open the app.
Home
Purpose: Workspace-wide health check. The "is everything OK?" page.
Time-of-day greeting with a contextual insight ("3 guides gained traction this week. 1 is losing users at step 2."), four KPI cards (impressions, starts, completion rate, avg rating), top-performer and needs-attention spotlight cards, recent guides table, latest feedback panel.
Intended visit length: 30 seconds. Creators glance, spot something, click into it.
Guides
Purpose: Find a specific guide. Manage many at once.
Header with totals and the primary "Record new guide" CTA. Two filter rows — status tabs and search/performance/feedback toggles. Default gallery view shows poster previews; list view is dense and sortable. Bulk-select reveals a floating action bar.
Intended visit length: variable. Could be 5 seconds (find that one guide) or 5 minutes (audit and clean up).
Guide detail
Purpose: Deep-dive on one guide. Where most product improvement actually happens.
Hero card with poster, breadcrumb, status chip, KPI ribbon (Impressions, Starts, Completion, Rating — the headline four; Avg. watch time joins them in the full KPI row below), and primary actions (Publish/Unpublish, Duplicate, Open in Editor).
Sticky tab bar with four tabs: Overview (full KPI row, step funnel, steps list, rating breakdown, latest feedback — all in one scroll), Embed (Pixel + Reveal Button + Dynamic Link cards for live tooltip delivery), Interactive Player (player preview, looping cover, player options, bubble position, MP4 export, captions — everything for the new interactive playback mode), and Behavior (trigger / audience / on skip / frequency cap / feedback screen).
Steps are a section inside Overview, not a separate tab. Edits happen in the Chrome extension; the Steps section links out with "Open in Editor" buttons per row. See Interactive Embed for the full feature spec of what lives in the Interactive Player tab.
Intended visit length: 5–10 minutes. The page where creators decide what to fix.
Checklists
Purpose: Browse and create journeys.
Three-column grid of checklist cards, each showing a stack of guide thumbnails, completion or finish-and-publish CTA. A ghost "New checklist" card sits in the grid as a permanent affordance. Creating a checklist opens a 2-step modal.
Intended visit length: short. Most teams have 3–10 checklists; this page is mostly a list with one navigation purpose.
Checklist detail
Purpose: Tune a journey.
Hero card similar to Guide Detail. Four tabs — Overview (journey funnel + auto-insight callout), Guides (reorderable table with drag handles and ↑/↓ buttons), Embed (widget with style + position picker), Behavior (extended form with sequential/free toggle and on-completion options).
Note: Interactive Player is a per-guide concept, so it appears on Guide Detail rather than Checklist Detail. Checklists ship as the floating widget — that lives in the Embed tab here.
Intended visit length: similar to Guide Detail. Visited less often but stickier when it is.
Settings
Purpose: Everything around the content.
Inner left nav with eight sections — Workspace, Team, Account, Notifications, Integrations, API & Webhooks, Extension, Billing — plus a visually separated Danger Zone. Each section is a self-contained page; navigation between them is fast.
Intended visit length: rare. Creators visit once at setup, then occasionally. Should not feel daunting.
The persistent sidebar
One sidebar across all six pages. Top to bottom: workspace switcher (logo square + workspace name + plan badge + dropdown), full-width search with a ⌘K shortcut, four primary nav items (Home, Guides with count badge, Checklists, Settings), a "Pinned" section for quick access to favourite guides, then the bottom area — Chrome extension status card (icon + "Reveal for Chrome", connection state, version, "Open editor" button) and the user's avatar row with name, email, and a … menu.
12 · Design
Design language.TBD · Work in progress
The visual rules. High-fidelity prototypes already exist in the package — these tokens are what they're built from, and what production should match.
Colour tokens
--bg#F4F4F5Page background
--card#FFFFFFCard surface
--border#E8E8EBDefault borders
--text#18181BPrimary text
--text-2#52525BSecondary text
--accentoklch(.64 .18 28)Reveal red-orange
--posoklch(.64 .14 150)Positive / published
--negoklch(.62 .17 25)Negative / warning
--draftoklch(.65 .12 75)Draft amber
Typography
Inter throughout. No serif. Tabular numerals on KPIs and code (font-feature-settings: "tnum").
Lucide icons. 16px default, 1.6px stroke, round linecap and linejoin. lucide-react in the React codebase.
Production parity
The bundled HTML files are reference, not code. They are React + Babel inline JSX prototypes used for design validation. The real codebase is React + Shadcn/ui + Tailwind. Recreate every screen using Shadcn primitives (Card, Button, Input, Tabs, Switch, etc.), then override styles to match these tokens. Shadcn's defaults are close but not identical.
13 · Delivery
Milestones.TBD · Work in progress
Nine milestones in dependency order. Sequenced so that every milestone produces something demo-able, and so that the riskiest work happens early. No durations — engineering owns sizing.