Pixel reference

This page is for whoever has to put the pixel on the site. It covers the snippet, what the script does once it loads, how a guide is matched to a domain, and what to check when nothing shows up.

You install one pixel per workspace. It is not per guide, and it does not need updating when someone records a new guide.

The snippet

Copy this from the Pixel installation card on any guide's Embed tab, under the label "Paste into <head>". The values below are placeholders.

<!-- Reveal pixel -->

<script defer src="https://embed.reveal.software/pixel.js"

data-workspace="acme"

data-key="wk_xxxxxxxx_xxxxxxxx_live"></script>

• data-workspace Required: Yes · What it is: Your workspace slug, the same one shown in the sidebar under the workspace name and in dashboard URLs. It tells the pixel whose guides to look for.

• data-key Required: Yes · What it is: Your pixel key. It authorises the request and scopes it to your workspace. It is a publishable key that runs in the browser, so it is visible in view source.

Heads up. The pixel key is not the Live key under Settings, API & Webhooks. That one is a secret with full read and write access and must never appear in front-end code. See API keys.

Where to put it

Three rules, and they are the whole placement story.

In <head>. Put it in the shared layout or base template so it lands on every page rather than on one route.

Once per domain. A second copy on the same page does not double your coverage, and one tag already covers every guide and checklist in the workspace.

Leave defer on. The script is deferred, so the browser keeps parsing and rendering while it downloads, and the pixel runs after the document is parsed. Do not swap it for a synchronous tag to make it run earlier.

What happens at load

Once the script executes it does three things.

Resolves which guide applies. It looks at the visitor and the current URL and works out whether any published guide in the workspace should serve here, using the guide's domain list, its trigger, and its audience. The checks it runs are the same ones mirrored on each guide's Issues tab.

Renders the tooltip layer. If a guide applies and its trigger fires, the pixel draws the tooltip and the camera bubble on top of your real UI. Nothing is injected into your own markup for you to style around.

Posts analytics. Impressions, starts, step progress, completions, and ratings go back to Reveal, which is what fills the Overview tab and the step funnel.

Domain matching

A guide only serves on the domains listed on it. That list lives on the Domains card of the guide's Embed tab: "The sites where this guide is allowed to run. The pixel only serves the guide on these domains." Changes there save automatically.

• acme.com That exact host, and nothing else.

• *.acme.com All subdomains of acme.com, for example app.acme.com.

• * Any site the pixel is installed on.

Having the pixel on a page is not enough on its own. If the host is missing from the guide's domain list, the pixel loads and the guide stays quiet.

Note. app.acme.com and www.acme.com are different hosts. If you serve your product from a subdomain, list the subdomain or use a wildcard.

Single page apps

The pixel resolves which guide applies at load time, against the URL in the address bar at that moment. That is the part you can rely on, and it means a full page load into any route in your app behaves the same way as a load into your marketing site.

What we cannot promise here is exactly how it behaves when your router changes the URL without a page load, because that depends on how your app pushes history and repaints. Test the case you care about on your own app before you rely on it: load a route that should not fire a guide, navigate client side to one that should, and watch whether the guide appears.

If the answer matters for your rollout, two things reduce the risk. Set the guide's trigger to Manual only and start it from a Reveal button or a dynamic link, so firing is something your app does deliberately. Or scope the guide's domain list tightly so it can only serve where you have tested it.

Verifying the install

The Embed tab is the check. The Pixel installation card shows a status chip that reads "Waiting for first pageview" until the pixel actually fires on a real page, and three diagnostic tiles under it.

• DOMAINS DETECTED The domains the pixel has actually been seen on. It reads "awaiting first ping" until one arrives.

• PAGEVIEWS TODAY Impressions today, so you can confirm traffic is reaching the pixel at all.

• GUIDE ACTIVE RIGHT NOW How many users are mid-guide at this moment.

Two buttons sit below them. Test on \{domain\} opens your site so you can watch the guide fire, and Copy pixel key hands you the key on its own.

Reveal for Chrome also reports detection back to the dashboard. The card's own copy puts it plainly: "Our Chrome extension reports back when it sees the pixel in the wild." So if you have the extension installed and you visit the site yourself, detection can show up in the dashboard without waiting on production traffic.

Common install problems

The pixel is in the wrong domain's head

Marketing site and product app are often separate codebases. Putting the tag in the marketing template does nothing for guides that run inside the app. Check DOMAINS DETECTED and confirm the host you see there is the host you want guides on.

The guide is not published

Draft guides do not load on a live site. The Issues tab states it directly: "Draft guides don't load on your live site. Publish it to make it available to visitors." Click Publish on the guide and try again.

The guide's domain list is missing the host

The most common version of this is listing acme.com while your product runs on app.acme.com. Add the host on the Domains card, or use *.acme.com.

Content security policy is blocking the script

If your site sends a Content-Security-Policy header, embed.reveal.software has to be allowed or the browser will refuse to load the pixel. You will normally see this as a CSP violation in the browser console rather than as a silent failure.

Content security policy

If you run a CSP, this is the starting point rather than a guarantee, because directives interact with whatever else your policy already sets.

script-src https://embed.reveal.software; frame-src https://app.reveal.software;

Allow embed.reveal.software in script-src so the pixel itself can load. Add app.reveal.software to frame-src only if you also embed the interactive player, since that is where the player iframe is served from.

Verify this against your own setup rather than pasting it in. Load a page with the browser console open, look for CSP violations naming either host, and widen the matching directive until they stop. If your policy uses nonces or hashes for scripts, the pixel tag needs to satisfy that too.

Next steps

• Install the pixel: The step by step install, written for anyone.

• Embed reference: The button, dynamic link, and player snippets in one place.

• Events: What the pixel records as a guide plays.

• Troubleshooting: When the guide still does not appear.