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
Originmust be on the project's allowed origins. An origin that is not, or a project whose browser reports are off, is answered403. - 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
fetchcalls — a request that rejects (a network failure) and nobody catches, or one you pass tocaptureException— with the stack from the call site. A4xxor5xxanswer, and every XHR call, becomes a breadcrumb, not a report. - Breadcrumbs — the last 20 clicks, navigations,
fetchand XHR calls (method, URL, status, duration),console.error/console.warnlines (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
webdriveradmission, 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.
| option | default | what it does |
|---|---|---|
logLevel | 4 | send reports of this priority or more severe |
maxErrors | 10 | unique errors sent per page load |
ignore | Script error., ResizeObserver loop | messages 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, traceOrigins | true, — | see Trace correlation below |
snapshot | false | a masked DOM snapshot with the first error |
snapshotMask | — | extra CSS selectors blanked in the snapshot |
snapshotStyles | false | inline 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 insnapshotMask, 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.