SDK reference

The script tag and the npm package (@spectosh/browser) share one recorder. This page lists everything you can configure and call.

Recording starts at once

The recorder captures from the moment it starts: errors, console output, requests and the page itself are held in memory while the project's settings load (one request, cached at the edge), then filtered by those settings and sent — or dropped, if the project is paused, sampled out or doesn't know the key. So start it as early as you can: the script tag first in <head>, startRecording() in your entry file before the app renders, or SpectoProvider at the root.

Keys know where they live

A key is all an install needs. pk_… belongs to the hosted service; a project in another region or on a self-hosted instance has a key that says so — pk_…@eu.specto.sh, pk_…@replay.example.com — and its Install page shows it that way. The settings request also confirms the key: a host that doesn't know it records nothing, and the console says why, so a key without its host never sends data to the wrong place.

Script tag

<script src="https://specto.sh/specto.js" data-key="pk_your_key" defer></script>

window.Specto

npm package

npm install @spectosh/browser

import { startRecording, identify, track } from '@spectosh/browser'

// in your entry file, before the app renders
const rec = startRecording({ key: 'pk_your_key' })

TypeScript types ship with the package — for @spectosh/browser and @spectosh/browser/react.

Options

The recorder

React

@spectosh/browser/react starts the recorder from your app's root, catches the errors React swallows, and gives components a hook. React is a peer dependency (17 and later).

import { createRoot } from 'react-dom/client'
import { SpectoProvider, spectoErrorHandler } from '@spectosh/browser/react'

createRoot(document.getElementById('root'), {
  onCaughtError: spectoErrorHandler(),    // React 19
  onUncaughtError: spectoErrorHandler(),
}).render(
  <SpectoProvider apiKey="pk_your_key" user={user}>
    <App />
  </SpectoProvider>
)

An error reported by both a boundary and a root handler is recorded once. Next.js, Remix and the other frameworks: framework guides.

Project settings win when stricter

At start the SDK fetches the project's settings (Settings → Privacy, cached at the edge) — the same request confirms the key. The stricter of those and your options applies: the dashboard can pause recording, force strict privacy, turn off console or request details, or lower the sample rate without a redeploy. Ingest enforces the same settings server-side.

Sessions, storage and limits

A session continues across page loads in the same tab (each load is recorded as a navigation, so funnels see every page), ends after 30 minutes without interaction and rotates after 4 hours. Batches upload every few seconds from a Web Worker, are numbered so retries never duplicate data, and the tail goes out with sendBeacon when the page is hidden. A full DOM checkpoint every 5 minutes keeps a lost batch from ruining a replay.

No cookies. Visitors with Do-Not-Track or Global Privacy Control turned on are never recorded. More: privacy controls, consent banners, troubleshooting.