Spectra Developer Documentation

60-Second Quickstart

Add the snippet from your Sites page to the head of every page you want recorded. It carries your key, your site id and the address recordings are sent to; the exact values are shown when a key is issued. The recorder starts as soon as the script arrives. Anything your page needs to tell it before then can wait in window.spectraQ, as described below.

The tag is read for these attributes and no others. A misspelled one is ignored in silence, so if the recorder is not doing what you expect, check the spelling here first.

After the snippet: what to set up

The snippet on its own records visits, finds the moments people struggled, and keeps the sessions worth keeping. Everything below is optional, and each one answers a question you will eventually ask of a recording. They are in the order most teams want them.

1. Say who the visitor is

Without this every session belongs to an anonymous visitor, and a support request that starts with a customer name has nowhere to go. One call, at sign-in:

Spectra.current()?.identify(user.id);

It applies to the whole session including everything before the call, so signing in halfway through a visit still attaches the part that led up to it. Their previous visits group under the same person too. In the session list, clicking a visitor shows everything else they did.

2. Say which build and which deployment

Two attributes your build writes, and the reason to bother with them is the question "did this start with the last deploy", which nothing else can answer.

<script src="…/v1/s.js" data-api-key="…"
        data-release="2026.09.25"
        data-environment="production"></script>

The Issues page then groups problems by build and tells you which one a problem arrived in and whether it is still there. The environment keeps your staging visits from being read as customers: set it on every deployment, not only production, or the untagged ones are the ambiguous ones.

3. Say what state the page is in

One address is often many pages: signed in or out, a plan, an experiment, a feature you are trying out. Say which one this is, and the Integrity page tells you where a broken control happens, for example "when plan is free and on screens 360px and narrower", instead of only that it happens somewhere.

Spectra.record({
  apiKey: '…',
  integrity: {
    context: () => ({ plan: user.plan, checkout_test: variant }),
  },
});

// When the state changes without a page load:
Spectra.current()?.setContext({ plan: 'pro' });

<script src="…/v1/s.js" data-api-key="…"
        data-context="theme: html@data-theme; member: body.logged-in"></script>

Up to ten labels, each a short state that many visitors share. A value that looks like an email address, an account number or a token is refused. Whether the visitor is signed in, their screen size, browser, language and light or dark mode are known without asking, and the build too when you set it above. Passing null to setContext removes a label.

Experiments are read without asking from Optimizely Web Experimentation and PostHog when they are on the page, in the room your own labels leave. For any other testing tool, pass the arm where the tool reports it. The name can be the tool's own; it is made into a label for you.

new GrowthBook({
  trackingCallback: (experiment, result) => {
    Spectra.current()?.setExperiment(experiment.key, result.key);
  },
});

A button that reads the same in two layouts of a page is counted as one, as long as the page never shows both at once. A button with no text, or one of several that read the same, is known by where it sits, so in another layout it can be counted as two. To keep it one button in every version of a page, give it a name: data-spectra-id="checkout".

Some faults are what you meant: an export button behind a paywall on the free plan, a link hidden from people who already pay. Mark one as intended on the Integrity screen, everywhere or only in the state it was found in, and it leaves the list and the score. In any other state the control is still checked. The same screen sets how many visits a fault must have met before it is listed.

4. Report the errors your own code catches

Uncaught errors are recorded for you. An error your framework catches never reaches the browser, so nothing outside your code can see it, and the better your error handling the less a replay knows. One line puts them back. See Reporting errors your code catches for React, Vue, Angular and script-tag examples.

5. Say where to be told when something breaks

Under each site, in Tell me when it breaks, paste a Slack incoming webhook or any address of your own. Without it, a page that stops working is found immediately and mentioned whenever somebody next opens the dashboard, which at three in the morning is not much use. See Being told when something breaks.

6. Decide what a replay may keep of your traffic

Every request your page makes is already recorded with its address, status, how long it took and what asked for it, and so is everything the page loaded. What is not kept, until you name the addresses, is what the requests actually said:

networkCapture: {
  bodies: { urls: ['/api/'] },
  headers: ['content-type', 'x-request-id'],
}

That is the difference between "it returned 400" and "it returned 400 because the postcode was empty". Nothing is kept for an address you did not name, credential headers are refused even if you list them, and values under names like password or cardNumber are replaced before anything reads them. Start with one address and widen it.

7. Mark anything that must never be recorded

Input values, and what a visitor types into an editable region such as a chat box or a rich-text editor, are masked by default. Passwords, card fields and one-time codes always are, whatever else you set. For a region of the page, add data-spectra-block to the element and it is replaced by a placeholder of the same size. For a screen you cannot mark up in advance, such as a document another customer uploaded, pause instead:

Spectra.current()?.pause();   // before showing it
Spectra.current()?.resume();  // after

The session carries on either way. If the pictures themselves are the confidential part and a missed selector would be a problem rather than a gap, use data-block-all-media and every image, video and canvas becomes a placeholder. See On-Device Privacy and PII Masking.

What you do not have to do

Page loads, scripts, stylesheets, fonts and images are recorded without any configuration, as are clicks, typing, scrolling, the keys that are decisions such as Enter and Escape, how fast each page was for that visitor, and the moments the page stopped responding. Rage clicks, dead clicks, form trouble, failed requests and stuck loading screens are detected for you. None of it needs an option set.

Verifying Installation

Confirm the install from your browser's developer tools console. Run the following command on any page where the recorder is installed:

Within a few seconds the Replay screen lists this visit, kept for the reason Install test.

Spectra is the name the script tag gives the recorder. If you installed the npm package instead, import current from it and call current()?.flag('test_install') from your own code; the same goes for every Spectra.current() on this page.

Serving Spectra from your own domain

Content blockers refuse requests to third-party hosts that appear on a filter list. Served from Spectra's host, the recorder is third-party to your site. Served from your own domain, there is nothing to refuse: the script, its configuration and every recording travel on your origin under a path that says nothing about what it is. This is the install the Sites page recommends, and it needs one forwarding rule on your host.

Your own Content-Security-Policy is the second reason, and on measurement it is the larger one. We ran the recorder against forty public sites: seventeen of them refused the direct install at connect-src before it could fetch its configuration, so it started, threw nothing, and recorded nothing. Nothing on your page would have told you. Served from your own origin the recorder is same-origin, which connect-src 'self' already permits, so a policy you have not changed keeps working.

If you would rather install directly and your site sets a policy, allow https://api.spectra-trace.com in both script-src and connect-src. The recorder now says so in your browser console when a policy blocks it, once per page, naming the directive that refused it.

How it works

Your host forwards one prefix, for example /q4hx/*, to https://api.spectra-trace.com/v1/*. The Sites page shows the tag with your key and a prefix chosen for your site; any prefix works as long as the tag and the rule agree.

Every rule below forwards the whole prefix, which is what we recommend. If your host or firewall needs the paths listed instead, these are all of them. A path your proxy does not forward is lost with no error on your page and nothing on ours, so the list has to be complete:

The rule, per host

Recording a whole journey

Do you need this?

If your whole site sits at one address, like example.com, then no. Paste the snippet and you are finished. A visit that moves through ten of your pages is already one recording.

You need this page if your visitors move between two different addresses that both belong to you. A marketing site at www.example.com and an app at app.example.com is the usual shape. Without the setting below, somebody who reads your pricing page and then signs up becomes two separate recordings, and the interesting part is split down the middle.

The rule that matters most

So put the snippet on every page you want to watch, at every address. In practice that means putting it in the shared layout or header template all your pages are built from, once, so nobody has to remember. If your two sites are separate projects, each one needs it in its own layout.

The setting below does a different job. It does not reach other pages. It tells two snippets that are already running that they are watching the same visit, so their two recordings become one.

Joining two of your addresses

List your addresses in the tag, and use the same tag on every page of both sites:

Two things to get right, and that is all of it:

List every address, including the one the page is on. The simplest thing is to paste the identical tag everywhere rather than tailoring the list per site. An address you have not listed is never given a session and never accepts one, so listing only one side leaves you exactly where you started: two recordings, nothing broken.

Use the same data-site-id on both. A recording is filed under its site and its session together, so two different site ids mean two recordings no matter what else is true.

What this covers

People leave a page in more than one way, and something that only handled links would miss most of them:

About the cookie, and visitors who refuse it

Between subdomains of one site, a small cookie carries the session. It is the only thing that survives a redirect made by your own server, because the browser sends it whatever caused the visitor to move.

If you list no addresses, no cookie is written at all. That is the ordinary install, and you can tell a privacy reviewer plainly that the product sets no cookie. When you do list them, the cookie holds a reference to the session and nothing about the person, has no expiry date, and disappears when the browser closes. It is a handover between two pages of one visit, not a record of who somebody is.

If a visitor blocks or refuses cookies, nothing breaks. Moving through one address keeps working, because that never used a cookie. Clicking a link or submitting a form to your other address keeps working, because the session travels on the link itself. Only the two cases that need the cookie fall back, and they fall back to what you had before: two recordings instead of one, with no errors and nothing for the visitor to notice.

A redirect your own code makes

There is one move nothing can see: your code setting location.href. If it goes to another domain of yours, hand the session over in one line:

An address you did not list comes back unchanged, so this is safe to put before any redirect, including one to a payment page. When the destination is somewhere no recording is possible, it also marks the moment in the replay, which is worth doing on its own.

A redirect your server makes, between two of your domains

This is the last case, and the only one that needs anything from your backend. Between subdomains it is already handled and you can skip this. It applies when your server decides to send the visitor from one of your domains to a genuinely different one, for example after a sign-in.

Nothing in the browser can carry that on its own. There is no link to attach anything to, because the move was decided on your server after the page was gone, and a cookie cannot cross from one domain to another. The only thing in a position to carry it is the server issuing the redirect. So give it something to carry:

The arriving page reads it and carries on as the same recording. The header name is yours to choose; only the _spz parameter matters, and it is removed from the address before the page records anything.

What is in that token. A reference to the session, a counter, a timestamp, and the key that lets the page it opens carry on recording this visit. No API key, no user id, no personal data of any kind. The key reaches this one visit and nothing else, because every visit is given a key of its own. Treat the token as you would a short-lived session link, and keep it out of logs you share. A page stops accepting it after one minute, and only ever at an address you listed. If you pass it somewhere you did not list, nothing happens at all.

Sites you do not own

This is the distinction that matters, and it is about whose page it is, not which address it sits at. Your second domain works because you can put the snippet on it. A payment page at Stripe or Dodo, or a sign-in page at an identity provider, is somebody else's site: you cannot put a script there, so nobody can record it. Not us, and not any other session replay product either.

What you get instead is the shape of the absence. The replay shows left for checkout.stripe.com, then returned after 3m 12s, and the visit carries on as the same recording. What happened before the payment and what happened after it stay one story rather than becoming two.

Linking a replay to your server logs

A replay stops at the edge of the browser. It shows you that a request took nine hundred milliseconds and came back a 500; it cannot show you what your server did inside it. So the person debugging has the replay open in one window and their logging or tracing tool in the other, trying to match a timestamp against a list of thousands, for a request that happened four hours ago.

Turn this on and both sides give the request the same name, so you can go straight from one to the other.

Every request your page makes to its own address now carries two extra headers:

The replay records the same trace id beside each request, so a viewer has something to paste into your tracing tool.

Requests to a different address

If your API lives somewhere else, name it:

Requests to your own address are safe without any of that, which is why tracing: true covers them and nothing else.

Keeping your tracing bill and your metrics sane

Two things are worth setting deliberately before you turn this on across a busy site.

How many traces your backend is asked to keep. The traceparent header carries an instruction: keep this one. By default every request carries it, so correlation works without tuning, but that also means a tracing tool that charges by volume will keep everything. If you have sampling turned down, turn this down to match:

Turning it down does not turn off the link. The headers still go out on every request; the trace is simply marked as one your backend may drop. Since logs are usually not sampled at all, correlating a log line with a replay keeps working for every single request, whatever rate you pick.

Where the session id is allowed to end up. The session id is unique per visit, which is exactly what makes it useful for correlation and exactly what makes it dangerous as a metric dimension: a metric split by it becomes one series per visitor, which is how monitoring bills get out of hand.

By default there is nothing to worry about. OpenTelemetry does not copy baggage onto spans unless you have added the baggage span processor yourself, and nothing copies it onto metrics. If you have added that processor, or you generate metrics from span attributes, do one of these:

On a trace or a log line it costs nothing: both are stored per event and looked up by id, which is the whole point of putting it there. It is only aggregation that cannot take a value unique to every visitor.

Things it will not do

It will not disturb tracing you already have. If your page already sends traceparent, that one is left exactly as it is and we record its id as the one to search for. If you already use baggage, ours is added to yours rather than replacing it.

Nothing is sent unless you ask. With no tracing setting, no request is touched at all.

Spectra is not a tracing tool. We do not collect spans or show you a flame graph, and we are not trying to replace what you already run. All this does is make sure both systems call the request by the same name.

Nothing personal travels in these headers. A trace id, a request id and the session id. No account details, no API key.

What does not work

A DNS alias is not first-party. Pointing a subdomain of yours at Spectra's host with a CNAME does not help: uBlock Origin on Firefox resolves the alias and blocks the request anyway. The forwarding has to happen on your own host.

Some visitors cannot be recorded by anyone. A visitor with JavaScript disabled, or a blocker set to refuse every script, does not run the recorder at all. No install changes that.

Content security policy and bundled apps

If your site sends a Content-Security-Policy, add worker-src blob: whichever install you chose. The recorder compresses recordings on a worker it builds from a blob: URL, and worker-src falls back to script-src when it is absent, so a policy of script-src 'self' refuses it. Nothing breaks: the recorder compresses on your visitor's own thread instead, on the page whose responsiveness you installed us to measure, and says so once in the browser console with the line to add.

Beyond that, a first-party install needs nothing added, because everything else it asks for is 'self'. The direct install also needs https://api.spectra-trace.com in script-src and connect-src.

These are the directives Spectra needs; keep whatever else your policy already sends.

If your policy refuses Spectra's address, the recorder says so once in the browser console, names the directive that refused it, and stops on that page, so it costs your visitors nothing. A policy sent as Content-Security-Policy-Report-Only refuses nothing, and recording carries on as normal.

If you bundle the recorder rather than loading the tag, pass the prefix as the tunnel option and it is used for every request:

A tunnel value that already carries a query string keeps the older ?target= form, so proxies written against it keep working. New installs should use the prefix: one rule instead of a hand-written proxy, and nothing for a filter to match.

Recording rules: what gets recorded

Spectra does not keep every session. A session is kept when something worth seeing happens: an error, a sign of frustration, or a moment your own rules mark as important. Everything else is discarded, which is why your quota goes a long way.

Automatic Default Triggers

Choosing which failed requests count

Until you say otherwise, every failed request is a problem: any answer from 400 up, and any request that never completed, which a rule names as 0. A request blocked by the browser for being cross-origin (CORS) is one of those: the browser hides its status, so it is a 0 and not a 4xx. Each failed request records the visit and is listed under Issues.

Some failures are expected, such as a 401 from a check for whether the visitor is signed in. A rule leaves those out, or counts one again. Rules are read in order and the last one that matches a request decides it.

• status: codes such as 404, '4xx' or '5xx', a range such as '500-503', or 0 for a request that never completed. Left out, every code.
• urls: text found anywhere in the address, such as '/api/session', or a pattern. Left out, every address. Accented and non-Latin paths can be written as they read.
• count: whether a request the rule matches is a problem. True unless it says false.

The same rules can be set without a deploy, under Failed requests for each site on the Sites page. Only a workspace admin or owner can change them there; everybody else in the workspace can see them. They are read after the rules in your code, so a rule on the Sites page has the last word, and every page uses a change within five minutes. A rule the recorder could not use is refused when it is saved, with the reason, and one in your code is skipped with a warning in the browser console.

Three kinds of request are never a problem, whatever a rule says: one your own code cancelled, one cut short by the visitor leaving the page, and Spectra's own.

The error your code raises about a failed request, such as "Request failed with status code 401" or "Failed to fetch", is the same problem as the request and is not listed again. When a rule leaves the request out, the error goes with it. When an address answers with a web page where your code expected JSON, the error from reading it is listed as Expected JSON, got a web page, with the request named when only one page arrived at that moment. Chrome does not tell a page when its own response.json() fails, so in Chrome that error is seen only when your code reads the text and parses it.

Programmatic Code Triggers

Dispatch custom business events or update session properties dynamically from your application logic:

Zero-JS HTML Markup Triggers

Annotate HTML elements directly to capture friction points without custom script logic:

Dashboard Trigger Rule Conditions

Configure trigger rules in the Spectra dashboard, under Sites and then Trigger rules. Every page uses a change within five minutes, with no redeploy:

Framework Integration Reference

React and Next.js (App Router)

Install the package from npm:

Render this once, in your root layout. Importing the package on the server is safe; recording starts in the browser, when the effect runs. In development React runs an effect twice, and the recorder is stopped and started again, which leaves one recorder running.

Next.js (Pages Router)

React with Vite, and other single-page React apps

Start the recorder before the app renders, so the first screen is in the recording.

React Router and Remix

In framework mode, start it from the root route, which every page renders.

Vue and Nuxt

A Vue app starts the recorder before it mounts:

In Nuxt, use a client plugin. Nuxt 4 reads plugins from app/plugins/; Nuxt 3 reads them from plugins/ at the project root. A plugin in the wrong folder is never loaded and says nothing, so check which one your version uses.

SvelteKit

Start it when the root layout mounts, which happens once, in the browser.

Angular

Start it before the application boots. The recorder works outside Angular's change detection, so it does not make your components check themselves again.

Astro

Add this to the layout every page uses. Astro bundles it and runs it once per page, with or without view transitions.

WordPress, Shopify, Webflow, Google Tag Manager and other site builders

Use the script tag from the Sites page rather than the package. Paste it wherever your platform lets you add code to the head of every page: the theme header in WordPress, theme.liquid in Shopify, the site-wide custom code setting in Webflow, Wix, Squarespace or Framer. In Google Tag Manager, add it as a Custom HTML tag firing on all pages; the tag keeps its settings when Tag Manager adds it after the page has loaded.

SDK Configuration Parameters

The record() initialization method accepts an object with the following parameters:

User Identity and Event Tracking

Link incoming replay recordings to your internal user accounts using identify():

What the recorder returns

Spectra.record() returns an instance, also reachable as Spectra.current(), with these methods:

Reporting errors your code catches

Uncaught errors and unhandled promise rejections are recorded for you, and the session they happened in is kept. But a framework catches: that is what an error boundary is for, and an error it catches never reaches the browser, so nothing outside your code can see it. The better your application handles its failures, the less a replay knows about them. One line puts them back.

class Boundary extends React.Component {
  componentDidCatch(error, info) {
    Spectra.current()?.captureError(error, { component: info.componentStack });
  }
  render() { return this.props.children; }
}

app.config.errorHandler = (error, instance, info) => {
  Spectra.current()?.captureError(error, { where: info });
};

@Injectable()
export class SpectraErrorHandler implements ErrorHandler {
  handleError(error: unknown) {
    Spectra.current()?.captureError(error);
  }
}

// app.config.ts: register it, or Angular keeps its own handler
providers: [{ provide: ErrorHandler, useClass: SpectraErrorHandler }]

window.spectraQ = window.spectraQ || [];
try { risky(); } catch (error) {
  window.spectraQ.push(['captureError', error, { where: 'checkout' }]);
}

The error is recorded with its message, its stack and any properties you attached to it, so a tagged error keeps the status code that explains it. The session is kept for review, and the message is scrubbed for personal data exactly like every other message.

Errors from scripts on another domain

An error thrown by a script loaded from another domain, such as a CDN or a third-party widget, reaches every error tool as Script error. with no message, file or line. The browser hides the details on purpose, so that one site cannot read another's code through its errors. To see them in full, add crossorigin="anonymous" to the script tag that loads it, and have its host send an Access-Control-Allow-Origin header. Many CDNs send it already; your own servers may need it added.

Add the attribute only where the header is sent. A browser refuses to run a script marked crossorigin whose host does not send it.

Replay and filters

Replay lists every recording kept for the selected site, newest first, with why it was kept. Filter by the reason, by one of your user ids, by a release or environment, or by a page URL, which matches anywhere the visit went rather than only where it started. The second row of filters narrows by what they were on and how the visit went: phone, tablet or desktop, browser, operating system, how long they stayed, and whether anything broke. Clicking a visitor shows everything else that person did. A site with no recordings yet shows the install steps in place until the first one arrives.

Issues

Issues groups recordings by what went wrong, so the same error on the same page is one row however many people hit it. Open a row to see the pages affected and the recordings behind it. Choose the window in the bar at the top, from the last day to the last ninety.

An issue you cannot or need not fix, such as an error from somebody else's script, can be ignored: open it and choose Ignore. It leaves the list, the daily email and the weekly brief for everybody in the workspace. Its recordings and counts are kept, Status set to Ignored shows it again, and Stop ignoring brings it back. Only a workspace admin or owner can ignore an issue. To stop a kind of failed request counting at all, rather than one issue, see Choosing which failed requests count.

Traffic

On the paid plans the Overview leads with your traffic, counted for every visit: visitors, visits, pageviews, bounce rate, the time on site of the middle visit, and how often your events fired, each against the window before. Each figure is drawn as a line over the window: by the hour for the last 24 hours, by the day for longer, in UTC. On a very large site a long window is estimated from a share of its visitors, and the Overview says so beneath the chart.

Your traffic is kept for three months, or for your plan's history window if that is longer.

Below the figures: the top, entry and exit pages; where visits came from, with search engines and networks named, a visit with no referrer credited to the utm_source of the link it arrived on, and visits from AI assistants such as ChatGPT, Perplexity and Gemini on their own tab; the five campaign tags, utm_source, utm_medium, utm_campaign, utm_content and utm_term; countries; devices, systems and browsers; and your events, with the share of visitors who fired each and what they were worth.

Visits from crawlers, link previews, audit tools such as Lighthouse, WebPageTest and GTmetrix, and headless browsers are not counted, and do not use your allowance. The country comes from the visitor's time zone, not their address, which Spectra never reads. It is country only, and a visitor on a VPN is placed where their computer's clock is set. To count an event, call spectra.track('Purchase', { value: 49.99, currency: 'USD' }); the value and the three-letter currency are optional, and are the only properties counted.

Analytics

Replay and Issues answer questions about one visit at a time. Analytics answers the ones that only exist across many: which control nobody finds, how far down a page people actually get, which page quietly loses them. It measures every visit rather than the share worth recording in full, so a page with no recordings still has numbers.

Overview is how visits went for the window you choose: how many ran into something that went wrong, how long people stayed on a page and how much of that was active, and the three speed measures a visitor actually experiences. Visitors, sources and countries are on the main Overview.

Pages ranks every route by traffic, with time on page, how far people scrolled, and how many arrived from elsewhere on your site and were gone within five seconds. Open a row for that page on its own.

The heatmap is drawn over your real page rather than a screenshot. A masked capture of the page is rebuilt in the browser and the counts are attached to the elements themselves, so the map stays correct when your layout changes and can be shown at desktop, tablet or phone width. Switch between clicks, rage clicks, dead clicks and clicks that caused an error. Each busy element wears its share of the page's clicks in the view you are on, the rail beside the picture ranks the busiest and explains the colours, and hovering a row lights its element on the picture. Click any element to list the visits that clicked it, with replays first.

Scroll draws how far down the page visits got, as bands over the page itself: the share of visits that reached each part, labelled every quarter, and a dashed line where a typical first screen ended. Anything that matters wants to sit above that line.

The picture of a page appears after a few visits: a small share of visitors contribute one, so a busy page costs almost nothing to keep current. Refresh picture takes a new one, and Pin picture keeps the current one whatever changes.

Findings is the ranked list of what is going wrong, ordered by how many people each thing affects rather than how often it happens: forty visitors clicking a broken button once each matters more than one visitor clicking it forty times. Every finding states the rule it applied and links to a replay of somebody hitting it.

The replay player

A recording plays back what the visitor saw. Idle and away time is skipped automatically, so a twenty-minute visit with two minutes of activity plays in two. The panel beside the player has six tabs.

Activity is what the visitor did, in order, lighting up as playback reaches it: clicks, typing, page changes, the keys that are decisions such as Enter and Escape, and the moments the page stopped responding. Pages is each page of the visit, and Issues is what went wrong in it, each one a place to jump to. Details is who they were, what they were on, and how fast the page was for them, banded against the same thresholds Google uses so a number here means what it means in Search Console. Console is what the page logged, with errors shown as errors rather than as empty braces. Network is everything the page asked for and everything it loaded, each row saying what asked for it and how long the visitor waited, and opening to show the timing, the headers, and the bodies for the addresses you have named.

Copy bug report puts the page, the user, the errors and a link to this recording on the clipboard. Share link makes a read-only link that opens this one recording without a sign-in.

Sites and keys

Each site has its own key and its own snippet. The key is shown once, when it is issued; only a hash is kept, so there is no copy to show later. Replace key issues a new one and stops the old one immediately, so update the snippet in the same change. Rules for what to keep live under each site; every page uses a change within five minutes, without a deploy.

Failed requests under each site says which failed requests count as a problem, by code and address (see Choosing which failed requests count, under Recording rules). Anybody in the workspace can see the rules; only an admin or the owner can change them.

Being told when something breaks

Spectra already notices when a page stops working. It watches how often the people on a page click the things people normally click there, and how often a given failure happens compared with how often it usually happens, and when either changes sharply it starts recording the visitors it affects. What it could not do was tell you, so all of that waited until somebody opened the dashboard.

Under each site, in Tell me when it breaks, paste a Slack incoming webhook or any address of your own that accepts a POST. You get one message when a problem starts, naming the page and how much worse it has got, with a link to the recordings. One message per problem, not one per check: something that repeats itself every few minutes is something people turn off, and an alert nobody reads is worse than no alert because it feels like coverage.

When several things break at once, you are not sent a message for each. After a message, a site is quiet for ten minutes, and anything found in that time arrives together as one message that lists it. A site is sent at most ten messages a day. The tenth says it is the last, and anything else that breaks that day is on the Issues page. For a receiver of your own: every message carries an alerts list with each problem in it, and a message about one problem also carries it as alert. The text is written for Slack, so &amp;, &lt; and &gt; stand for &, < and >; the fields beside it carry every value as it was.

If your pages say which release they came from, you are also told when your newest release has a control people could not use that your other releases did not, or has one more often: one message for the release, naming each control, its page, and how many visits met it in that release against the others, counted on the screen sizes it happens at. Each one is told once. Nothing is said until enough visits have come in to be sure and the answer has held for half an hour, so a release a few minutes old takes a little while.

To see a message arrive before anything has broken, choose Send a test message under the same heading. It goes at once to every place your alerts go, and the screen says how it went at each. It never holds back a real alert, and one can be sent every few seconds.

The same alerts can go to Telegram as well, or instead. Under Tell me when it breaks, choose Connect Telegram, then open Telegram from the link it gives you and press Start for a private chat, or choose a group to add Spectra's bot to your team's. The link works once, for thirty minutes. If Start does nothing, because the Telegram app is not installed, choose Open in Telegram Web, or open Spectra's bot yourself and send it /start followed by the code, which is the end of the link after ?start=. The Sites screen shows the whole command. Each alert reaches Telegram once, exactly as it reaches your webhook, and Disconnect stops it without touching the webhook. If the bot is removed from the group or blocked, the next alert finds that out: Spectra stops sending there, and the site shows Telegram as not connected.

If you set a signing secret, every message carries a X-Spectra-Signature header: sha256= followed by an HMAC-SHA256 of the exact body, keyed with your secret. Recompute it over the raw bytes you received and compare. That is how your receiver knows the message came from us. The secret is never shown again after you save it, not even to you.

Team and invitations

Invite colleagues by email from the Team page. An invitation link is good for seven days and is also shown to you, so you can pass it on if the email does not arrive. Roles: an owner pays and can see billing; an admin manages people, sites and keys; a member watches recordings and edits rules; a viewer reads. Anyone with admin or above can change a role or remove a person, but not themselves. You only see what your role allows, so a page you have no use for is not shown to you.

You can be in two workspaces: one of your own and one you were invited to. When you are in both, a workspace picker appears at the bottom of the sidebar, and everything on the page follows the one you choose. To join a different workspace, leave one first from its Team page. The owner of a workspace cannot leave it, since the subscription belongs to them.

Plan and quota

Billing shows your plan, the sessions this period against your allowance, and your retention window. When the allowance is used up, new recordings pause until the period resets or you move up a plan; nothing already kept is affected. On the paid plans your traffic keeps counting past it, up to twenty times your plan's visits, so the Overview's figures stay whole for the month; past that, nothing more is counted until the period resets, and the recorder stops sending anything at all. A plan change applies immediately: the new plan is charged in full and starts a fresh month, with no credit for the days left on the old one, and the confirmation says so before you agree. Invoices and payment details are managed from the same page.

The free plan is session replay: recordings, the replay player, sessions and issues. The integrity check, weekly summaries and Spectra AI are part of the paid plans, and heat maps and page analytics are the analytics add-on.

Reproduce: test every pull request with real visits

Reproduce records what real visitors do on your live site and replays it against every pull request. If something people did yesterday no longer works in the pull request, the check fails and tells you which journey and which step. Nobody writes or maintains tests. It is an add-on, switched on per site: ask us to switch it on, then follow these steps. They take about ten minutes.

What you need

• A site in Spectra (Sites), and its API key. The key is shown once, when the site is made; if you no longer have it, issue a new one on the Sites page.
• A GitHub repository for the site, where you can add secrets and workflows.
• A build command that writes your site to a folder (dist, build or out), or a preview URL for each pull request.

Step 1. Put the Reproduce tag on your live site

Open the dashboard, choose the site in the bar at the top, and go to Reproduce, then Set up. Copy the tag from step 1 there and put it first inside <head> on every page, in place of your current Spectra tag. Replace YOUR_API_KEY with the site's key. Leave out async: a visit is replayed from its first moment, so the script has to start first.

Deploy the site. Every visit from then on is recorded as a possible test. What visitors type is kept as typed, so a replay can sign in the way they did; passwords, card fields and one-time codes are never recorded, only their shape. To keep typed text scrubbed, add data-inputs-as-typed="false" to the tag.

Step 2. Create a CI token

Still on Reproduce, Set up, step 2: type a name such as github-actions and press Create token. Copy the token straight away: it is shown once. If you lose it, revoke it on the same page and create another.

Step 3. Give GitHub the token and the site

In your GitHub repository, open Settings, then Secrets and variables, then Actions, and add a secret named SPECTRA_REPRODUCE_TOKEN holding the token from step 2.

Step 4. Add the workflow

Create the file .github/workflows/spectra-reproduce.yml in the repository with the workflow from Set up, step 3 (it has your site's id filled in), or this one with YOUR_SITE_ID replaced. Change two lines: base is your live site's address, and candidate is the folder your build writes. If your build command is not npm run build, change that line too.

The folder is uploaded to Spectra and served privately for the length of the check, so you do not need a preview deployment. Uploaded builds are kept for seven days.

The report is posted on the pull request as one comment and rewritten on every push, never a new one each time; without pull-requests: write it stays in the job summary. To see the reports before letting Spectra fail a job, add fail-on: never under with:. If you deploy previews on Vercel or Netlify, give the preview's address as candidate and run the workflow on: deployment_status, with if: github.event.deployment_status.state == 'success' on the job and candidate: ${{ github.event.deployment_status.environment_url }}. A deployment is not a pull request, so that report goes to the job summary and the check, not to a comment.

Step 5. Let people use the site

Checks are made of real visits, so the first one needs some. Use the site yourself for a few minutes, or wait for visitors. A visit counts once it has ended, about 20 minutes after its last activity. Reproduce, Journeys shows the tasks found so far; Add recent visits adds the latest ones now. Each check also adds them on its own.

Step 6. Open a pull request

The workflow runs on every pull request, and its result appears on the pull request and under Reproduce, Checks. Each journey gets one verdict:

• Same: it does what it did.
• Broken: a step that worked now fails. It can't be done, an answer that succeeded fails, an error appears, or a press does nothing. The check fails.
• Changed: it works, differently: a new page, a different request, or other words on screen at a step (an error message that now says something else, a message that appears and goes, a renamed heading). Shown for review; the check passes.
• Couldn't replay: Spectra could not judge it, for example because the pull request asks the server for something no recorded visit asked. It goes to Reproduce, Inbox, where you answer it once; it is never counted as a pass.

Spectra compares what each step showed on screen, not only where it led: a failed payment that said "Something went wrong" in production and now says "Account balance should be greater than 500" is reported with both messages. Text nobody can see (kept for screen readers, folded away) is left out, and so is text that changes by itself between two replays of the same build, such as a clock or a rotating banner. Visitors' own moves in the browser, Back, Forward and an address typed, are replayed as they made them.

A journey that cannot be replayed even on your live site is tried again on another real visit of the same journey before it is reported. If none replays, you can Leave this journey out from the inbox, with a reason: it is left out of checks for 30 days, every report in that time lists it, and then it is judged again. When one change shows on many journeys (a button renamed everywhere), one Intended on every journey, for the difference named beside it, covers all of them. In the pull request's report Spectra quotes your app's own words, never what a visitor typed or what your server answered them: those read "[what the visitor typed]" and "[the server's answer]", and the dashboard shows them in full.

Every journey that is not the same is said in plain words: which step, what it did in production, what it does in the pull request, and why, as the browser saw it (for example, "another element covers it and takes the click"). Open the check under Reproduce, Checks to watch both replays side by side (Play both), and Watch the real visit opens the recorded visit at that moment. Copy fix prompt for an agent copies the same account, written for an AI coding agent to act on; the pull request's report carries it too. Replays are kept as video for 30 days.

If something is not right

• The Reproduce page shows only Set up, with "Reproduce isn't on for this site yet": the add-on is not on for the site chosen in the bar at the top. Check the site; the page names the site id it is looking at.
• The check says there are no journeys: no visit has been recorded and ended yet. Check that the tag is on the live site (step 1), use the site, and wait about 20 minutes.
• The check fails with "This token does not open this site": the secret holds a revoked token, or a token from another site. Create a new one (step 2).
• A journey is "Couldn't replay": open the Inbox. It says what was missing and lets you give the answer once, or decide that the difference is intended.

What counts as friction

A recording is kept when something went wrong or somebody struggled. These are the reasons, in the words the session list and the Issues page use. Nothing here needs configuring; they are what the recorder watches for on every page.

You can add reasons of your own with track(), setProps() or a data-spectra-trigger attribute, and turn them into recordings with rules. See Recording rules.

What analytics collect

Analytics answers questions that only exist across many visits: which pages people reach, where they stop, where they click, how far they scroll, how fast pages were. It works differently from recordings and it is worth knowing how, because the honest answer to "are you tracking my visitors" depends on it.

A recording is kept only when something happened. Analytics needs every visit, so each page life sends one small anonymous summary as the page is left: which page, how long, whether the visitor interacted, how far they scrolled, which elements were clicked, the speed the browser measured, and where they came from. It is a summary, not a stream: there is no replay in it and no way to reconstruct one from it.

What it never contains: no name, no address, and no text from the page. It carries the same anonymous visitor id your recordings do, a random value with nothing about the person in it, plus your own user id if you set one with identify(). That visitor id is kept on the device so a returning visitor is recognised; with persistence: 'session' or 'memory' it ends with the visit. Element labels go through the same masking your recordings do, so a button whose text you have masked is a button whose label is masked here too.

It is collected only for sites whose workspace has the Analytics add-on. A site without it sends nothing at all, rather than sending it and having it discarded at our end. Set analytics: false to opt a site out even with the add-on active.

Heatmaps need one more thing: a picture of the page to draw on. A small fraction of visitors to a page that has no usable picture contribute one, which is the page as it was built in their browser, with the same masking applied. Everybody else contributes nothing to it.

On-Device Privacy and PII Masking

Spectra hides sensitive information in the visitor's browser, before anything is sent. Every input value is masked by default, and so is what a visitor types into an editable region such as a chat box or a rich-text editor. Passwords, card fields and one-time codes always are, whatever else you set. Card numbers, email addresses and authorisation tokens found in the page's text, and in attributes such as titles and image descriptions, are masked too. These attributes change what is kept for one element and everything inside it:

Erasing one person's recordings

When somebody asks you to delete their data, this removes every session recorded for them on a site, wherever it is kept, and the analytics of every visit of theirs, recorded or not. It needs the admin role in the workspace that owns the site.

Authenticate with your dashboard session token, not the ingest key. The ingest key can only write recordings; it cannot read or delete them, which is what keeps a key pasted into a public page from being able to erase your history. Open your browser's developer tools while signed in to the dashboard and copy the Authorization header from any request. It stops working when your sign-in does, so copy a fresh one when you need it.

The reply says how many sessions were found and how many were removed. If a stored copy cannot be deleted the whole request fails rather than reporting a partial erasure as complete, so it is safe to retry.

Deleting a site

Deleting a site deletes everything recorded under it, everywhere it is kept. It cannot be undone and there is no recycle bin. Also admin or higher.