# @tracescout/browser

Browser SDK for TraceScout: session replay, error & console capture, Web Vitals,
and automatic fetch/XHR network capture — with W3C trace-context correlation to
your backend logs. **Beta.**

Only a **public project ID** is required in the browser. **Never put a private
ingest key, admin credential, or server secret in browser code** — the browser
SDK does not use or accept one.

## Install

### npm (bundlers: React, Vite, Next.js, Vue, Angular)

```bash
npm install @tracescout/browser@beta
```

```js
import TraceScout from '@tracescout/browser';

TraceScout.init('YOUR_PROJECT_ID');
```

- ESM (`dist/tracescout.esm.min.js`) is used by bundlers; a UMD build
  (`dist/tracescout.min.js`) covers CommonJS/`require` and `<script>`.
- **SSR-safe import:** importing the package on the server does not touch
  `window`. Call `init()` only in the browser (e.g. a Next.js client component
  or inside `useEffect`).

### Direct `<script>` / CDN (version-pinned)

Pin an **immutable, versioned** URL in production — do not use an unversioned
"latest" URL for production customers:

```html
<script src="https://cdn.tracescout.com/sdk/v2.2.0-beta.0/tracescout.min.js"></script>
<script>TraceScout.init('YOUR_PROJECT_ID');</script>
```

The CDN artifact at a given version is built from the same release commit as the
npm package of that version, so they never differ behaviorally.

## What it captures

- **Session replay** (rrweb), **console** and **JS errors**, **Web Vitals**,
  and **fetch / XHR** requests (method, URL, status, timing, and — for API
  calls — headers and bodies), shown in the TraceScout dashboard.
- **Header sanitization:** credential-bearing request/response headers
  (`authorization`, `cookie`, `x-api-key`, …) are redacted before capture.

## Trace propagation (safe by default)

- A W3C `traceparent` header is added to **same-origin** outbound `fetch`/`XHR`
  requests so browser activity correlates with your backend traces.
- **An existing valid `traceparent` is never overwritten.**
- **Third-party origins receive no `traceparent` and no TraceScout baggage** —
  your `sessionId`/`userId`/`projectId` are never sent to other hosts, and no
  CORS preflight is added to cross-origin calls.
- **Trusted cross-origin propagation is not enabled in this beta.** If your app
  calls a different-origin backend and you need the trace linked across it, that
  is a separate, explicit configuration (not yet available) — same-origin is the
  default.
- The SDK never instruments its own ingestion requests.

## Public API

```js
TraceScout.init('YOUR_PROJECT_ID', { environment: 'production' });
TraceScout.identify('user_123', { plan: 'pro' });
TraceScout.track('checkout_completed', { total: 42 });
TraceScout.setUserMetadata({ plan: 'pro' });
```

## Version / CDN alignment

The npm version and the CDN `…/sdk/v<version>/…` path are produced from the same
release commit. Pin the same version in both places.

## Docs

https://docs.tracescout.com/docs/getting-started/installation

## License

Licensed under the [Apache License 2.0](./LICENSE) (see also [NOTICE](./NOTICE)).
"TraceScout" names, logos, and trademarks remain reserved — Apache-2.0 does not
grant trademark rights.