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.
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.
Five 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.
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 · always present unless step is silent
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
How they relate
A workspace contains many guides. Guides can be grouped into checklists. Both guides and checklists are delivered to end users through the same pixel, configured by the same behavior rules, and report into the same analytics store. Most of the dashboard is dedicated to one of those five 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.
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.
Three 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 three 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.
How customers choose
If you want…
Use…
Guides to fire automatically based on user attributes
Pixel
Users to start guides on their own terms
Reveal button
To send users into a specific guide from email or external content
Dynamic link
All of the above (most customers)
Pixel + button + link 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
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.
06 · 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.
07 · 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.
08 · 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.
09 · 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.
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.
10 · 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, KPI ribbon, and primary actions (Publish toggle, Duplicate, Open in Editor). Sticky tab bar with four tabs — Overview (with four selectable layout variations), Steps (read-only inspection), Embed (pixel + button + dynamic link), Behavior (the five-question form).
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).
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 with logo and plan badge, full-width search with a ⌘K shortcut, four primary nav items (Home, Guides with count badge, Checklists, Settings), a "Pinned guides" section for quick access to favourites, then the bottom area — Chrome extension status card and the user's avatar row with name, email, and a … menu.
11 · 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.
12 · 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.