DOCUMENTATION

Browser client

JavaScript errors from real visitors — our script, or twenty lines of your own.

JavaScript errors from real visitors, with the request context that caused them. Two ways in: the script we ship, or twenty lines of your own.

Before you start

You need the exact origins your site is served from, and the project's js_key (public). Browser reports are off for every new project; step 2 turns them on and shows the key.

1. Understand the authentication — it is not a secret

  • Browser reports go to POST /api/v1/ingest/js/<js_key>; the key is in the URL and is public by design.
  • The request's Origin must be on the project's allowed origins. An origin that is not, or a project whose browser reports are off, is answered 403.
  • Limits: 10 reports per request, 64 KB, 30 requests per minute per address — snapshot uploads count toward the same 30.

Why not a secret? Anything shipped to a browser is public the moment it ships. Pretending otherwise produces a secret that leaks and a team that believes it did not. A browser sets Origin itself, so the allowlist stops other sites' pages from reporting as yours. A script outside a browser can send any Origin it likes; against that, codesafe caps the volume: the per-address rate limit, a fixed list of fields it reads, and a daily snapshot budget per project. A stolen js_key lets someone send reports and snapshots, nothing more — it reads nothing and changes no setting.

2. Turn browser reports on and allowlist your origins

In PROJECTS → the project → REPORTING, under PUBLIC JS ENDPOINT, tick accept browser reports on the public JS endpoint. The BROWSER JS KEY shows once it is ticked; a new project gets its key when it is saved.

Under ALLOWED ORIGINS, add every origin the app is served from, one per line, scheme://host[:port] and nothing else:

https://www.example.com
https://staging.example.com
http://localhost:8080

A report from an origin not listed is answered 403. That includes www versus bare domain — they are different origins. The page never sees the answer, but codesafe counts every 403 on ACTIVITY with the origin it refused.

Only your own code's errors are reported. The client keeps an error only when a script from the page's own origin, or an inline script in its HTML, threw it. Extensions, tag managers, widgets — and your own bundle when a CDN on another host serves it — are dropped in the browser. codesafe repeats the test on arrival (the FIRST-PARTY FILTER on the same tab, on by default); the hosts listed there as extra first-party script hosts count as your own.

3. Add the client

Script tag

<script src="https://yourcodesafe.cloud/js/codesafe-client.js"></script>
<script>
	ovosCodesafe.init({
		url: 'https://yourcodesafe.cloud',
		key: 'YOUR_PUBLIC_JS_KEY',
		release: 'v2.113.1',        // optional, but it earns its place
		environment: 'production',
	});
</script>

Async + stub

<!-- early in <head>; keep the stub as written, the client reads its names -->
<script>
(function (w) {
	var stub = {events: [], calls: [], options: null};
	stub.capture = function (event) {
		if (stub.events.length < 50) {
			stub.events.push(event);
		}
	};
	w.addEventListener('error', stub.capture, true);
	w.addEventListener('unhandledrejection', stub.capture);
	w.ovosCodesafe = {
		stub: stub,
		init: function (options) {
			stub.options = options;
		},
		captureException: function () {
			if (stub.calls.length < 50) {
				stub.calls.push(['captureException'].concat([].slice.call(arguments)));
			}
		},
		captureMessage: function () {
			if (stub.calls.length < 50) {
				stub.calls.push(['captureMessage'].concat([].slice.call(arguments)));
			}
		},
		flush: function () {}
	};
})(window);
ovosCodesafe.init({
	url: 'https://yourcodesafe.cloud',
	key: 'YOUR_PUBLIC_JS_KEY'
});
</script>
<script async src="https://yourcodesafe.cloud/js/codesafe-client.js"></script>

Your own

// the browser endpoint reads the flat JS report object, not a server envelope
const report = (error) =>
{
	const body = JSON.stringify([{
		message: error.message,
		name: error.name,
		stack: error.stack,
		url: location.href,
		priority: 3,
		timestamp: Date.now(),
	}]);
	
	// sendBeacon survives the page unloading, which is exactly when errors happen
	navigator.sendBeacon('https://yourcodesafe.cloud/api/v1/ingest/js/YOUR_PUBLIC_JS_KEY', body);
};

addEventListener('error', (event) => report(event.error ?? new Error(event.message)));
addEventListener('unhandledrejection', (event) =>
	report(event.reason instanceof Error ? event.reason : new Error(String(event.reason))));

WordPress

The plugin ships the same script and fills the key in for you:

	Settings → ovos codesafe → Report JavaScript errors

Trace correlation and DOM snapshots are switches on the same screen.

The stub buffers errors and calls while the script loads, so nothing thrown before it arrives is lost and a slow codesafe never blocks the page.

Minified: /js/codesafe-client.min.js is the same client, minified — about 10 KB compressed instead of 31 KB. It behaves identically and updates with the readable one; use it in either snippet in place of codesafe-client.js.

Writing your own? The browser endpoint reads the flat JS report object — message, name, stack, file, line, col, url, priority, count, timestamp, release, environment, tags, traceId, extra — and ignores everything else. It is not the envelope a server sender posts; Browser reports lists its fields.

4. Verify it

Open the site, then in the browser console:

ovosCodesafe.captureException(new Error('codesafe test from ' + location.host));
ovosCodesafe.flush();

The row appears in EVENTS within a few seconds, with runtime browser. An error you throw by hand in the console is not reported: no script of the page threw it, and the client keeps only errors its own scripts throw.

If nothing arrives: check the Origin against the allowlist first — that is the cause nine times out of ten. The Network tab shows the beacon's 403, and ACTIVITY counts it with the refused origin.

What the shipped client captures

  • Uncaught errors and unhandled promise rejections from your own code.
  • Failed fetch calls — a request that rejects (a network failure) and nobody catches, or one you pass to captureException — with the stack from the call site. A 4xx or 5xx answer, and every XHR call, becomes a breadcrumb, not a report.
  • Breadcrumbs — the last 20 clicks, navigations, fetch and XHR calls (method, URL, status, duration), console.error / console.warn lines (200 characters each) and failed resource loads that led there.
  • A masked DOM snapshot with the first error per page load, when you turn it on (snapshot: true).
  • Automation evidence: a webdriver admission, and the external scripts a visitor never attempted to load — the signature of a bot running inline JS. A seeded IGNORE rule drops the errors that follow a script never loaded or failed to load (scripts_missing, scripts_failed); pause it in RULES to see them.

It is wrapped so it can never throw into your page. If codesafe is unreachable the call simply fails and your site does not notice.

Options

Every option goes into init(); url and key are the only required ones.

optiondefaultwhat it does
logLevel4send reports of this priority or more severe
maxErrors10unique errors sent per page load
ignoreScript error., ResizeObserver loopmessages never sent — RegExps or text
release, environment—deploy label and stage on every report
tags—tags on every report, e.g. ['shop', 'eu']
context—a function whose object is merged into every report's extra
trace, traceOriginstrue, —see Trace correlation below
snapshotfalsea masked DOM snapshot with the first error
snapshotMask—extra CSS selectors blanked in the snapshot
snapshotStylesfalseinline the page's styles, so the snapshot renders styled
otlp—send reports to an OpenTelemetry Collector instead

By hand: ovosCodesafe.captureException(error, extra, priority) (priority 3 by default), ovosCodesafe.captureMessage(text, priority, extra) (priority 5 by default, so pass 4 or lower to get past the default logLevel) and ovosCodesafe.flush(), which sends the queue now instead of after two seconds.

Trace correlation

On by default (trace: true): the client sends a W3C traceparent on the page's same-origin fetch and XHR calls. The server error and the browser failure then carry one trace id, and codesafe lines them up as a single request across services.

Calls to another origin get the header only when that origin is listed in traceOrigins, and that server must allow it (Access-Control-Allow-Headers: traceparent). Set trace: false if a firewall or security plugin rejects the extra header.

DOM snapshots

With snapshot: true, the client uploads a masked copy of the page beside the first error of a page load, and the event detail shows it.

  • At most 512 KB after gzip; a larger snapshot is not sent. It is kept 7 days.
  • Each project takes 2000 snapshots or 256 MiB a day by default; past either, an upload is answered 429.
  • Give an element data-codesafe-mask, or list a selector in snapshotMask, and its text is blanked before upload.

Through your own domain

The page can send everything to its own domain while your server forwards it to codesafe. Give init() your own address as url (url: 'https://www.example.com/codesafe'), then forward /codesafe/js/codesafe-client.js and POST and OPTIONS on /codesafe/api/v1/ingest/js/<js_key> to the same paths on codesafe. To keep each visitor's address, your server adds the project's api_key and the visitor's address to every forwarded report; Browser reports lists the headers and has the nginx and Apache configuration. Snapshots are not covered: post them straight to codesafe or leave them off.

What never leaves the browser

  • Input values are stripped from DOM snapshots before upload.
  • Scripts are removed from snapshots entirely.
  • No cookies, no storage, no keystrokes, no session recording.

Next: Build your own client if you would rather not ship ours, or Browser reports for the full field list.