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 initializes immediately and queues commands automatically before network bundle arrival.

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. 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.

4. 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.

5. 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.

6. Mark anything that must never be recorded

Input values are masked by default and passwords always are. 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 Privacy and 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 telemetry transport directly from your browser developer tools console. Run the following command on any page where the SDK is embedded:

The Spectra Sessions dashboard updates within seconds displaying a test_install trigger tag alongside your current session replay.

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, and a timestamp. No API key, no user id, no personal data of any kind, so it is safe in your server logs. It stops being accepted after one minute, and it is only ever accepted 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 and nothing is reported: the recorder compresses on your visitor's own thread instead, on the page whose responsiveness you installed us to measure.

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 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

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 dynamic trigger rules in the Spectra dashboard, under Sites and then Trigger Rules. Rules propagate instantly to client SDKs without requiring code redeployments:

Framework Integration Reference

React and Next.js (App Router)

Install the official package from npm:

Vue 3 and Nuxt 3

Create a client plugin inside your Nuxt project under plugins/spectra.client.ts:

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);
  }
}

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.

Sessions and filters

Sessions 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 at the top: the last day, week or month.

Analytics

Sessions 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 the site at a glance for the window you choose: how many visits, how long they lasted, how much of that was active, and how many ran into something that went wrong. It also carries the three speed measures a visitor actually experiences.

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 four 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. Overview 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 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; they take effect on the next page load without a deploy.

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.

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 kept 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. Upgrades apply immediately and are prorated by the payment provider. Invoices and payment details are managed from the same page.

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, no identifier assigned by us that outlives the visit unless you have set one with identify(), and no text from the page. 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 redacts sensitive information client-side prior to network dispatch. Passwords, credit card numbers, and auth tokens are stripped at the DOM serialization layer.

Erasing one person's recordings

When somebody asks you to delete their data, this removes every session recorded for them on a site: the sealed recordings, anything still being written, the search index entries, and the off-box copy if you have one. 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, or use the Sites page, which does the same thing for you.

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.