Skip to main content

@keploy/capture-sdk 3.1.0 release notes​

View as Markdown

3.1.0 is published under the npm latest tag. A project that depends on ^3.0.1 (or ^3) gets it the next time its lockfile is updated (for example npm update, or an install with no lockfile). To stay on 3.0.1, pin 3.0.1 (or ~3.0.1).

Nothing in the public API was removed or renamed. One new option is on by default (honorPrivacySignals), many behaviours changed, the recorded data has new shapes, the SDK loads new files at run time, and some TypeScript code written against 3.0.1 no longer compiles. Read the next two sections before you upgrade.

This package records. Keploy turns the recordings into deduplicated flows and, in beta, into Playwright tests that replay recorded journeys against recorded mocks. Generating and running those tests is Keploy's side, not the SDK's: nothing in this package generates or runs a test. Where these notes say what replay does with a recorded value, they describe how that beta replay reads it.

Two release candidates, 3.1.0-rc.1 and 3.1.0-rc.2, were published under the next tag only. If you ran one, the last section lists what changed since.

Before you upgrade: checklist​

  • Using privacyMode: "strict"? Remove privacy.maskNetworkBodies: false and don't pass defaultPrivacyConfig() beside it, or the capture will not start (1).
  • Filter KUI_E_CAPTURE_DECLINED out of your error reporting (2).
  • Call init() again from onError only after changing what was refused, and don't make rendering or routing wait on await KeployCapture.init(): a refused one can take up to about 30 s to resolve (3).
  • In unit tests with fake timers, advance them, or a refused init() does not resolve (3).
  • If your error tracker groups errors by stack, expect a refused init()'s errors to group together: their err.stack shows the SDK's hand-over, not your init() call (3).
  • TypeScript: update onError handlers and anything exhaustive over the SDK's error or warning codes (7).
  • Make sure your build ships the SDK's extra files and your Content-Security-Policy allows them: rrweb's chunk (8), the body worker dist/body-worker.js with worker-src 'self', the chunk dist/body-redact.* (13), the GraphQL term chunk dist/request-term.* ("GraphQL requests") and, under strict, dist/strict-attributes.* (5).
  • If anything reads recorded bodies, expect new notes in place of some of them: [Response body not read by the page] (11), [Body cut: ...] (13, 14), [Body not captured: ...] (14) and more [REDACTED] (17).
  • If you rely on text typed into rich-text editors being recorded under balanced, it no longer is (4).
  • Under strict, give controls that have only a label a data-testid (5).
  • Tests or dashboards that expect one flow per single-page-app visit now get one flow per route (15).

Behaviour changes​

1. privacyMode: "strict" with privacy.maskNetworkBodies: false no longer starts​

Strict mode now records no request or response bodies (see 6). A config that asks for strict mode and also sets privacy.maskNetworkBodies: false contradicts itself, so the SDK refuses to start, for every visitor:

  • nothing is recorded, patched or sent, and init() still resolves, once onError has run (see 3);
  • a console.error line is written, once per page load, and onError receives KUI_E_PRIVACY_CONFLICT in a task of its own (see 3), with evidence: { privacyMode: "strict", option: "privacy.maskNetworkBodies" };
  • this check runs before the privacy-signal check (see 2), so you also see it in a browser that sends Global Privacy Control.

This also catches privacy: defaultPrivacyConfig() (or a spread of it) beside privacyMode: "strict", because defaultPrivacyConfig() sets maskNetworkBodies: false.

What to change: delete maskNetworkBodies: false (or drop that key from what you pass), since strict mode already masks bodies. If you need bodies recorded, use privacyMode: "balanced" instead.

2. Do Not Track and Global Privacy Control visitors are not recorded​

The new option honorPrivacySignals defaults to true. The SDK treats a visitor as having opted out when any of these is set:

  • navigator.globalPrivacyControl === true;
  • navigator.doNotTrack is "1" or "yes";
  • window.doNotTrack === "1";
  • navigator.msDoNotTrack === "1".

For such a visitor, init() resolves, but the capture never starts:

  • rrweb is not loaded;
  • fetch and XMLHttpRequest are not patched;
  • nothing is sent;
  • no session exists, so getSessionId() returns "".

The SDK also tells you, twice over:

  • onError is called with KUI_E_CAPTURE_DECLINED for every declined init() call, not once per page, in a task of its own after the call (see 3). The one exception: a declined init() made while 16 others are waiting for their hand-over resolves without it. evidence.signal is "globalPrivacyControl" or "doNotTrack", and status is null.
  • A console.info line is written once per page load.

With continuous: true no session starts either.

Consequence: Brave and DuckDuckGo send GPC by default, so their users are not recorded unless they turn it off. If your onError forwards every error to an error tracker, it now files one event for each declined init() it is told of. Filter it out:

onError: (err) => {
if (err.code === "KUI_E_CAPTURE_DECLINED") return; // the visitor opted out; nothing failed
// ...
}

To opt out: set honorPrivacySignals: false, and the SDK records those visitors anyway. Do this only if your site has its own lawful basis to record them and your privacy policy says so.

3. onError runs in a task of its own, and repeated refusals are paced​

In 3.0.1, onError was called for a server rejection and for an invalid sessionIdGenerator; the second ran in init()'s microtasks, before init() resolved. In 3.1.0 it is also called, before anything is sent, for a declined visitor (2), a conflicting config (1), an invalid privacy route (17), and rrweb or strict's allow-list failing to load (8).

How a refused init() reaches onError. This covers every refusal above but a server rejection, which reaches onError as in 3.0.1:

  • In a task of its own. The capture ends and the singleton is released first. Then onError runs in a timer (setTimeout) task, never inside the refused init() call and never in its microtasks. A load that fails only after an offline start (8), or after a leave held it (14), is handed over the same way, after init() has resolved.
  • init() resolves after its handler. A refused init() resolves once its onError has run, so code after await KeployCapture.init(...) sees what the handler did.
  • Repeated refusals of one code are paced. Per page and per code, at most one hand-over is scheduled at a time. A refusal of that code made while one is scheduled joins it, and that hand-over tells each joined refusal in the order they came, each init() resolving after its own handler. A hand-over scheduled soon after its code's last one (within that one's wait plus 1 s of when it ran) waits twice as long as the last one did, counted from when the last one ran: 50 ms the first time, doubling up to 30 s. Otherwise it runs in the next task. So no refused init() is scheduled more than 30 s out.
  • At most 16 refusals of a code wait. A refused init() made while 16 of its code are waiting resolves at once, without calling onError, and the SDK keeps nothing of it. Every other refused init() is told when its hand-over's timer runs. The SDK's error spec moves to sdk-errors v5, which states the hand-over and this one exception.
  • The console line is written once per page load, per code. That holds for the console.error line of a conflicting config, an invalid route or sessionIdGenerator and a failed load (3.0.1 wrote an invalid generator's line on every init()), and for a decline's console.info line. A server rejection still writes its line every time.

A handler may still call init() again, since the capture has ended. Do it only after changing what was refused: a declined visitor, a conflicting config, an invalid route and a sessionIdGenerator that returns the same bad id fail the same way on the next init(), and a chunk that failed to load can fail again. For example, re-init after dropping a sessionIdGenerator that returned a bad id, or after rotating a key on KUI_E_INGEST_KEY_REJECTED. A handler that re-inits the same config for every refusal above, even twice for each one, never recurses or freezes the page: it goes round 11 times in its first minute, then twice a minute, and each round runs at most 16 handlers. A server rejection is not paced: a handler that re-inits the same config on one is called again for each upload the server rejects.

What this changes for your code:

  • An awaited init() can take up to about 30 s. Suppose a page calls init() again and again, less than about a second apart, and each is refused: a single-page app that calls it on every route change, say, for a visitor who sends GPC. Its refusals are then told at the code's growing waits, and an awaited init() resolves only at the code's next hand-over, up to about 30 s after the call (longer in a hidden tab, whose timers the browser throttles). Don't make rendering or routing wait on await KeployCapture.init().
  • Fake timers. A refused init() resolves only after a timer task, so under fake timers await KeployCapture.init(...) for a declined or refused config does not resolve until you advance them (for example await vi.runAllTimersAsync()). Advance them before you switch back to real timers: a hand-over left on a fake timer never runs. Later refused init() calls of its code in that copy of the SDK (in tests, the rest of the file) join it: up to 16 wait with it, unresolved, so an awaited one hangs until the test times out, and the rest resolve at once, untold. What waits is handed over only when a refused init() of that code finds the lost hand-over more than 31 s past due, or due more than 31 s ahead (a clock that went back), as performance.now() reads it. A page that clears timers it did not set can lose a hand-over the same way.
  • Many refused init() calls in one test file. The pace is kept per loaded copy of the SDK, so the tests of one file share it. If each test awaits a refused init() of the same code right after the last, the second waits 50 ms and each one after waits twice as long as the one before: the ninth waits 6.4 s, past a 5 s test timeout. Use fake timers and advance them, or load the SDK afresh for each test (for example vi.resetModules(), then import it again). The console line is written once per code per copy too, so only the first test that triggers a code sees it: a suite that expects the sessionIdGenerator line in each of several tests, as 3.0.1 wrote it, now sees it only in the first, unless each test loads the SDK afresh.
  • err.stack shows the SDK's hand-over, not your init() call. The error onError gets for these refusals is built when it is handed over, in the SDK's timer task, so its stack shows that task, not the code that called init(). An error tracker that groups errors by stack puts all of one code's refusals in one group. The error's code, message, evidence and remedy are as before.

4. Rich-text editors are masked under balanced​

In 3.0.1, rrweb's input masking reached input, textarea and select only, so text typed into a contenteditable element (TipTap, Quill, Lexical, ProseMirror, a plain one) was recorded in clear under balanced, emails and card numbers included.

In 3.1.0, the text of every element inside a [contenteditable] (other than contenteditable="false") is masked under balanced and strict, as an input's value is, and unmaskSelectors cannot unmask it. off records it.

Consequence: a page that makes a large region editable (a page builder, a notes app, a CMS editor) records that whole region as asterisks under balanced, including text the visitor did not type.

5. privacyMode: "strict" masks more, and records no page text​

In 3.0.1, strict mode did two things: it masked input values, and it replaced every visible text node with asterisks. Network data was recorded exactly as in "balanced", and every attribute was recorded as written. In 3.1.0, strict mode records no typed text, no visible text and no bodies:

  • Bodies. Strict forces privacy.maskNetworkBodies on (see 6).
  • Request URLs. Every query value is replaced with [REDACTED], and every parameter name is kept. For example, /search?q=ada%40example.com&page=2 is recorded as /search?q=[REDACTED]&page=[REDACTED]. An empty value and a bare name (?flag) are recorded as written. Such a request does not match a live one at replay today (see "Redacted values and replay" in 17).
  • The page's own URL, the session's referrer and every URL in the DOM. Every query value and every fragment-pair value is replaced, and names are kept. So the page URL in a recording can differ from the URL the visitor saw, for example ?page=[REDACTED].
  • Headers. Every request and response header value is replaced with [REDACTED], and its name is kept. The exceptions are these 18 headers, whose values are kept: accept, accept-encoding, accept-ranges, age, cache-control, connection, content-encoding, content-language, content-length, content-type, date, etag, expires, keep-alive, last-modified, pragma, transfer-encoding and vary.

Text in attributes, the head and comments. Text lives in more places than text nodes. A page that copies a visitor's search into <meta name="description"> sent the search to the ingest in clear under 3.0.1's strict mode. Strict now reads attributes by an allow-list. An attribute keeps its value only if its name is part of the page's structure: id, class, role, name, type, data-testid, ARIA state and relationships, form and layout attributes, SVG geometry and paint (on SVG elements only), or rrweb's own. It also keeps its value if a rule of its own reads it: URLs (with every query value replaced), CSS, srcset and srcdoc. Every other value is recorded as an empty string. That covers:

  • title, alt, placeholder, aria-label and the other aria-* text;
  • every data-* attribute except data-testid and a lazy loader's data-src, data-href and data-srcset, which are read as URLs (path kept, query values replaced);
  • every value that rrweb records in clear, including a checkbox's, radio's or button's. A field value that rrweb already masked keeps its asterisks;
  • an input's min, max and pattern (a date range copies the picked start into the end's min; a confirm field copies a typed email into pattern);
  • framework state, such as wire:snapshot, x-data, hx-vals and an Astro island's props;
  • a custom element's attributes, except its global ones (id, class, slot, ARIA state);
  • a <meta>'s content, unless the meta configures the page (http-equiv, or a name of viewport, color-scheme, theme-color, referrer, robots or format-detection);
  • comments;
  • every ARIA attribute that reflects a choice or an entry (aria-valuenow, aria-valuemin, aria-valuemax, aria-valuetext, aria-checked, aria-selected, aria-pressed, aria-current, aria-sort, aria-invalid, aria-activedescendant). HTML's checked and selected are dropped altogether;
  • a URL-named attribute (href, src, action and the rest) that holds text rather than a URL;
  • text, attributes, scripts and comments inside a srcdoc.

The <title> element's text and SVG <text> were already masked as text nodes. A checkbox's or radio's value in an Input event is asterisks; the event still says whether it is checked.

Still recorded under strict: URL paths (/search/<term>, a hash route, a <link rel="canonical">, a lazy image's data-src), ids, classes, a field's name, SVG geometry (a signature pad's strokes), text under unmaskSelectors, a comment outside <html> that changes after the snapshot, and data-testid, exactly as written, because replay finds elements by it. An app that builds a test id from user data (row-${email}) records that data. Do not put a visitor's text in any of these.

Strict recordings look different, and name elements differently. A strict recording no longer carries aria-label, so the flow engine names an element by data-testid, a stable id, or its tag and class names instead. Add data-testid to controls that have only a label. Played back as a session recording (with rrweb's player), a strict recording also looks different: CSS keyed on a data-* ([data-theme=dark], Radix's data-state) or on a title no longer matches, <progress> and <meter> show no value, and animated or filtered SVG and legacy table attributes (bgcolor, cellpadding) play back without them. On a Docusaurus site (measured on keploy.io/docs), the playback keeps the layout, colours, cards and icons, with the text masked; the themed logo and the colour-mode toggle's icon disappear, because Docusaurus shows them through [data-theme] CSS.

The allow-list is a chunk only strict loads. It is dist/strict-attributes.mjs (about 1.3 kB gzipped; .js for CommonJS, 1.5 kB). balanced and off never download it. Under strict the SDK imports it at init(), in parallel with rrweb, and records nothing until both have loaded. A bundler emits it as a chunk: deploy every chunk your build emits. With no bundler, serve dist/ as it is. If the chunk cannot be loaded (a Content-Security-Policy, a network failure, a deployment that dropped the file), the capture ends before anything is recorded or sent, with the new KUI_E_STRICT_ATTRIBUTES_UNAVAILABLE.

Strict mode still records each request's method, URL path, status, duration and header names, and its new requestTerm (see "GraphQL requests"; Keploy's hosted service does not use it yet). For a GraphQL request, that term holds the operation name and a hash of the query document with every literal blanked. It is computed from the raw body before masking, so it is recorded even though the body itself is [MASKED].

6. Bodies masked whole are decided without reading them​

This applies to every capture with privacy.maskNetworkBodies: true, in any mode, and to every strict capture (strict forces the option on).

In 3.0.1, such a capture read each body and recorded [MASKED], or null when the body was empty. In 3.1.0 it decides from what the body is, without reading it:

  • the Response your page gets is the network's own, never read, cloned or relayed by the SDK;
  • a body passed in fetch()'s init or to XMLHttpRequest.send() is decided from its kind and size, never serialised or decoded. A string body is still scanned for its requestTerm (see "GraphQL requests");
  • the body-redaction code (see 13) is never loaded.

A body is recorded null when it is absent: a request sent with no body or an empty one; a fetch response to a HEAD, a 204, 205 or 304, one with Content-Length: 0, and one whose body is null or already locked; an XHR text response that is empty. Every other body is [MASKED], including an XHR Blob (even an empty one), an XHR json, blob or arraybuffer response, and a fetch response that does not declare its length, even if it turns out empty (3.0.1 recorded that one null).

One body is still copied and read, and only as far as its requestTerm needs: the body of a Request object you pass to fetch() (fetch(new Request(url, { body })), as ky and axios's fetch adapter send it). The SDK copies it as your page calls fetch() and reads the copy after that call returns: whole when it starts as a JSON object, its first KiB otherwise, and a multipart one is parsed.

7. TypeScript: handlers written for 3.0.1 may not compile​

CaptureErrorCode grew from 5 codes to 10, and AnyCaptureError grew from 2 classes to 7. The new codes, with their classes, are:

  • KUI_E_DOM_RECORDER_UNAVAILABLE (DomRecorderRefusal);
  • KUI_E_STRICT_ATTRIBUTES_UNAVAILABLE (StrictAttributesRefusal);
  • KUI_E_PRIVACY_ROUTE_INVALID (PrivacyRouteRefusal);
  • KUI_E_CAPTURE_DECLINED (CaptureDeclined);
  • KUI_E_PRIVACY_CONFLICT (PrivacyConflict).

The onError example in the 3.0.1 README no longer compiles. It ends with a fallback branch that reads err.evidence.issues. That branch now also receives the five new classes, and their evidence has no issues:

error TS2339: Property 'issues' does not exist on type '... | Readonly<{ reason: string; }> | ...'.

The same change breaks two other common patterns:

  • a switch (err.code) that is exhaustive with a never default fails with TS2322;
  • a Record<CaptureErrorCode, …> that lists the five 3.0.1 codes fails with TS2739.

Three more types grew, and break the same patterns:

  • CaptureWarningCode grew from 2 codes to 6 (see "Error codes"), and CaptureWarningEvidence with it;
  • CaptureEvidence grew from 2 members to 6;
  • CaptureRemedy has a new required field, docs, so code that builds a CaptureRemedy object of its own must add it.

Fixes:

  • Smallest fix. Read err.issues instead of err.evidence.issues. Every CaptureError has an issues field, and it is null when the server sent none. This one change compiles against both 3.0.1 and 3.1.0.
  • Or narrow first. Guard the branch with if (err instanceof IngestRejection) (it is exported), then read err.evidence.issues inside it.
  • Update exhaustive code. Add the new codes to exhaustive switches and to Record<CaptureErrorCode, …> and Record<CaptureWarningCode, …> tables.
  • Filter declines. Drop KUI_E_CAPTURE_DECLINED before you report errors (see 2).

Plain JavaScript handlers are not affected by the types. At runtime, though, they now receive the five new codes. remedy.manual has also changed: it used to hold the remedy's prose and now holds a link to the error's docs page. remedy.manual is deprecated; read the new remedy.docs, which holds the same link.

8. If rrweb (or strict's allow-list) cannot be loaded, the capture stops​

In 3.0.1, if import("rrweb") failed, init() resolved and the SDK recorded no page activity, silently. Network calls were still recorded and sent.

In 3.1.0, the SDK refuses the capture instead, in any environment that has a window: a browser, or a jsdom-based test environment.

  • Nothing is sent, and fetch and XMLHttpRequest are not patched.
  • A console.error line is written, once per page load.
  • onError receives KUI_E_DOM_RECORDER_UNAVAILABLE in a task of its own (see 3), and evidence.reason holds the browser's error. Under strict, a failed allow-list chunk is refused the same way, as KUI_E_STRICT_ATTRIBUTES_UNAVAILABLE.
  • Where there is no window, as in server-side rendering, there is no refusal: the SDK behaves there as 3.0.1 did.

The usual causes are:

  • the ESM build loaded without a bundler and without an import map for rrweb;
  • rrweb's chunk blocked by a Content-Security-Policy or by the network.

A page that starts offline does not load rrweb (or, under strict, the allow-list) until the browser is online again, unless a service worker controls the page. Meanwhile, the page's network calls are recorded but held, not sent. If rrweb then fails to load, the capture is refused as above, and what was held is dropped unsent. Calling stop() while it waits also drops what was held.

9. A dropped page event holds page recording until a fresh snapshot is sent​

3.0.1 went on recording clicks, typing and DOM changes after the page snapshot they refer to had been dropped (an oversized snapshot, a full queue). Those events then named nodes the recording never showed. 3.1.0 holds them instead.

When a DOM event is dropped (too large to send, or evicted from the queue), the SDK:

  • also discards the page interactions and DOM changes still queued behind it, up to the next full page snapshot in the queue;
  • records no further clicks, typing, scrolling, mouse movement or DOM changes until it has taken a fresh full snapshot.

Network calls, route changes and custom events are still recorded.

Outside an outage, the SDK retakes the snapshot at once when the dropped event was a DOM change. When the dropped event was a snapshot, it retakes one after 5 s, then at doubling waits up to every 60 s, because each attempt serialises the whole document. A page whose snapshot never fits (over the ingest's 10 MiB cap) therefore records no DOM changes or interactions at all, and is serialised again every 60 s for as long as it stays that large. The KUI_E_EVENT_OVERSIZED console warning is the only notice; nothing in the recording marks the gap.

During an outage. The SDK now also caps what it holds unsent at 16 MiB of JSON, beside maxQueueSize (5,000 events by default). Past the byte cap, the oldest go first: batches that already failed are dropped whole, then the oldest queued events. While the browser is offline or uploads are failing, a dropped DOM event takes no retake: the hold stays until the outage ends, and then the SDK takes one fresh snapshot, queued after everything it held. Page recording resumes when the server first accepts a batch again. On a page that sends only DOM events, the outage ends when the queue has emptied while the browser is online, with no upload accepted, so the snapshot is taken again each time the 16 MiB cap refills. Interactions made between the first drop and that snapshot are not in the recording.

The same applies when, during an outage, a tab is shown again or the capture is resumed after pause(), and the page changed while the tab was hidden or paused: no interactions are recorded until the outage ends.

10. Ingest outages: uploads back off​

The first batch that fails gets three attempts. The gaps between them are 0.5–1 s and then 1–2 s. After the third attempt fails, 3.0.1 waited up to 4 s more before it put the batch back in the queue. 3.1.0 puts it back at once.

From then on, uploads count as failing:

  • One attempt per batch. Each later batch gets one attempt.
  • A wait before each new batch. The flush timer, a full batch, or an event over 32 KiB starts no new upload until a wait has passed. The wait is 2 s at first and then doubles: 4, 8, 16 and 32 s, up to a cap of 60 s. Each wait is also stretched by a random 0–50%, so at the cap it lasts 60–90 s. A dead endpoint therefore gets about one scheduled request a minute (a page whose only traffic is DOM events also restarts the wait each time its queue runs empty).
  • What bypasses the wait. stop(), the tab being hidden, the browser's online event and the page unloading all still send at once.

How long recovery takes to notice. Once the wait has reached its cap, the SDK can take up to about 90 s after its last failed attempt to try again. Add up to one batchInterval (5 s by default) for the next flush, so up to about 95 s in all. It notices sooner if the browser fires online, the tab is hidden, or stop() is called.

When a batch is accepted again, everything held is sent at once, not one batch per interval. If page events were dropped meanwhile, the SDK takes one fresh snapshot (see 9).

The page is not held up by the back-off. The wait is a timestamp check, not something the page's code waits on. While uploads fail, the SDK also stops re-snapshotting the page (but see the DOM-only case in 9), and the 16 MiB cap bounds the memory it holds.

11. fetch(): the page gets the network's own Response, and a body it never reads is recorded as not read​

In 3.0.1, the SDK read each response's whole body before fetch() resolved. A streamed response, such as SSE over fetch, NDJSON or an LLM's tokens, therefore reached the page only when it ended, and an endless stream never reached it at all. Every response body was recorded, whether the page read it or not.

In 3.1.0, fetch() resolves when the headers arrive, as it does without the SDK, and the body reaches the page as the network delivers it.

The Response is the network's own object. Its url, redirected, type, headers, bodyUsed, instanceof Response and BYOB readers are the browser's, and a Cache API round trip stores it exactly as without the SDK. The SDK answers the body readers, body and clone() with non-enumerable members of its own on that object.

The SDK reads a body only as your page reads it (unless bodies are masked whole, see 6, or the Response has no body member at all: under a fetch polyfill such as whatwg-fetch, which Mirage JS and pretender install, the SDK reads a clone, as 3.0.1 did, and records the body whether or not the page reads it):

  • Read whole (text(), json(), arrayBuffer(), bytes(), blob()): the browser's own method answers, and the SDK records what your app got. A blob() is read back from that same Blob after your code has it, so a page that leaves right after its blob() may have that exchange recorded cut. formData(), and a json() your app put on Response.prototype, are recorded from a copy read only as far as maxBodySize needs. A clone's whole read (res.clone().text(), as ky does) is recorded the same way; the first whole read to finish is the recording.
  • Read through res.body: the SDK reads the network once for each read your page makes, never ahead. A page that cancels or aborts stops the download at once, and is recorded with exactly what it read.
  • A clone's body is never recorded. Monitoring tools (Datadog RUM, Sentry) read a clone of every response through its stream; that is not your app's read. A body your app reads only through a clone's body is recorded as not read.
  • Never read: the SDK never reads it either. It is recorded as the text [Response body not read by the page], with its real status and headers. That includes a body a browser API consumes past JavaScript, such as cache.put(req, res) or WebAssembly.instantiateStreaming(res). Replay sends that text as the body.

Behaviour change: unread bodies. A response your page ignores (a fire-and-forget POST, a prefetch, a check of res.ok alone) was recorded with its whole body in 3.0.1. In 3.1.0 its body is the note above. If something downstream reads recorded response bodies, expect the note for those calls.

Behaviour change: when an unread exchange is recorded. Not at a deadline, because a page may read a body tasks later. It is recorded when the browser garbage-collects the Response, its clones and its stream, or when the tab is hidden, the page leaves, the capture pauses, or stop() settles. So such an exchange can reach Keploy well after it happened, or only as the page ends. A mobile browser may discard a hidden tab without another event, so a body your page first reads after its tab was hidden and shown again stays recorded as not read.

A response to HEAD, and a 204, 205 or 304, is recorded with an empty body. A body that fails part-way (an abort, a dropped connection, a navigation) is recorded with what had arrived, cut and marked ...[truncated]; for a body your page was reading whole, nothing of it is kept.

What else your page can see. Besides the SDK's own members on the Response (above), a body your code reads by calling the prototype's method directly (Response.prototype.text.call(res)) passes the SDK by, and is recorded as not read. And a streamed request body built into a Request (new Request(url, { body: stream, duplex: "half" })) that the server answers early can be read further than without the SDK, up to the chunk that crosses 3 x maxBodySize + 4 bytes. A stream passed as init.body is not read at all (recorded [ReadableStream]).

12. pause() and stop()​

  • pause() decides by when an exchange happened. An exchange that starts, or is answered, while the capture is paused is not recorded, even if its answer arrives after resume(). In 3.0.1 an exchange was kept or dropped by whether the capture was paused when its record was made.
  • An exchange still reading its body at pause() is recorded at once, with what had arrived, cut and marked ...[truncated], and nothing of it after, resume() included. Your page's own read goes on untouched.
  • stop() waits up to 1 s for exchanges already answered to finish their bodies, then records any still open (an endless stream) cut at that point. An unread body is recorded as not read.
  • The promise stop() returns also waits, for at most 10 s, for the final upload of a capture or session that had already ended on its own (at maxSessionDuration, at a server rejection, or between continuous sessions). Awaiting it is optional.

13. Body redaction runs in a Web Worker, which your build must ship​

In 3.0.1, request and response bodies were redacted on the page's main thread, by code inside the SDK's bundle. In 3.1.0, a capture that records bodies (the default, balanced) redacts them off the main thread:

  • dist/body-worker.js (about 9.3 kB gzipped), a Web Worker the SDK starts in the page's next idle period after the capture starts. The SDK creates it as new Worker(new URL("./body-worker.js", import.meta.url)), which webpack 5, Next.js (webpack and Turbopack), Vite and Parcel 2 turn into a file of your build;
  • dist/body-redact.mjs (about 9.7 kB; .js for CommonJS, 9.9 kB), the same code for the main thread, plus the res.body relay (see 11). init() requests it at once, beside rrweb. Your page's network is recorded from the start; it never waits for this chunk.

A capture that masks bodies whole (see 6) loads neither. Both files are new requests your page makes; deploy every file your bundler emits.

These setups have no worker:

  • webpack 4: it cannot parse import.meta, so the SDK keeps it out of every file webpack 4 reads;
  • esbuild: it does not emit the worker. Copy node_modules/@keploy/capture-sdk/dist/body-worker.js beside your bundle and it runs;
  • a build that loads the SDK's CommonJS files (its require entry): the CommonJS worker start has no import.meta, so it starts no worker;
  • an environment with no Worker, such as jsdom in unit tests;
  • assets served from another origin (webpack's publicPath or Next's assetPrefix on a CDN): a browser runs a worker only from the page's own origin;
  • a Content-Security-Policy that refuses it: allow worker-src 'self' (or the child-src or script-src it falls back to);
  • the SDK loaded from a CDN without a bundler;
  • any other bundler that does not turn new URL("./body-worker.js", import.meta.url) into a file. The SDK's tests build webpack 5, Next.js, Vite and Parcel 2; with anything else, check that your build emits dist/body-worker.js.

Each of these setups writes the KUI_E_BODY_WORKER_UNAVAILABLE warning (see 18) once per page load that records bodies, in production too. If you forward console.warn to an error tracker, expect one event per such page load.

Without the worker, the main thread redacts each body, but only its first 64 KiB. A body over 64 KiB, which 3.0.1 kept whole up to the 512 KB maxBodySize, is recorded cut: its first 64 KiB redacted under the line [Body cut: 65536 of N characters kept, unverified]. Replay reports a test over a cut body as unproven. If the body chunk cannot load either (a CSP, a 404 after a deploy, dist/index.mjs served alone), every body the page or the SDK read, whatever its size, is recorded as not captured (see 14), never in the clear; a response body nothing read keeps [Response body not read by the page]. The console says KUI_E_BODY_WORKER_UNAVAILABLE (a warning, see 18) once per page for each part that failed, worker or code.

With no bundler, serve the package's dist/ directory as it is, import dist/index.mjs from it, and map rrweb alone with an import map. The SDK loads its chunks and the worker from beside dist/index.mjs. An import map that maps @keploy/capture-sdk/body-redact, /body-worker-start, /request-term or /strict-attributes is honoured first.

From a CDN (jsDelivr, unpkg), import dist/index.mjs by its path. The chunks load from the CDN if it sends CORS headers, as CDNs do; the worker cannot, so bodies over 64 KiB are cut as above. unpkg's package root redirects to dist/index.mjs. jsDelivr's package root answers with the file at the root's own URL, where no chunk is beside it, so name the path there. Two cases to avoid or know about:

  • A package-root URL with ?module serves the module field's build, dist/index.bundler.mjs, which is not meant for a page without a bundler: it loads no chunk from beside itself, so it records every body as not captured and refuses every strict capture with KUI_E_STRICT_ATTRIBUTES_UNAVAILABLE.
  • The SDK loads only chunks of its own version. If a CDN hands it another version's chunk (unpkg's ?module rewrites the SDK's own imports to the @latest version's files), it refuses that chunk and loads its own from beside itself.

The module field now names dist/index.bundler.mjs (it was dist/index.mjs), a build for webpack 4 and Parcel without the no-bundler worker start. The exports map still gives import dist/index.mjs and require dist/index.js.

PrivacyEngine.maskNetworkData() called directly still masks headers and the URL, but it redacts bodies only once a capture on the page has loaded the body code. Until then it records each body as [MASKED], never in the clear. In 3.0.1 it always redacted bodies itself.

14. Some bodies are now recorded cut or "not captured"​

3.0.1 recorded every body up to maxBodySize. 3.1.0 bounds what it holds for redaction and never sends a body it could not redact, so a body can now arrive as one of these notes instead. Replay never serves a cut or not-captured body; a test that reaches one is reported unproven.

Too much waiting for redaction. The SDK holds bodies waiting for redaction (for their idle task, for the worker to start or answer, or for the body chunk) up to a page-wide bound of 8 Mi UTF-16 units (16 MiB of strings). Each exchange counts its bodies plus 1,024 units, and counts again while a copy is posted to the worker, until the worker answers. An exchange that comes while the bound is full is recorded with nothing of its bodies kept: [Body cut: 0 of N characters kept, unverified]. Nothing is logged. With bodies of 512 KB (the default maxBodySize), that happens past 16 exchanges in a burst before the page is idle, or past 8 that a slow worker has not answered; smaller bodies take many more. A lone exchange is taken whatever its size when nothing else is held.

The page leaves, or stop() settles. Bodies still waiting in the worker are redacted on the main thread then, up to 64 KiB in all; the first body past that keeps what is left of the 64 KiB, and the rest are recorded with nothing kept. If the body chunk has not loaded by then, they are recorded "not captured" (below).

Not captured. The cut note with nothing kept, then a line that says why. There are three causes:

[Body cut: 0 of N characters kept, unverified]
[Body not captured: the page left or the capture stopped before redaction was ready]

[Body cut: 0 of N characters kept, unverified]
[Body not captured: the redaction code could not load]

[Body cut: 0 of 0 characters kept, unverified]
[Body not captured: the page took the body's stream before the redaction code had loaded]
  • left: the page left (or stop()'s 1 s bound came) before the body chunk had arrived;
  • code failed: the body chunk could not load at all (see 13);
  • early: your page took res.body before the body chunk had arrived, and nothing read the body whole. Such a page gets the browser's own stream at once; the SDK never makes a read wait for its chunk. A page that only looks at res.body and then reads whole (ofetch and Nuxt's $fetch do response.body ||, then text()) is recorded as usual.

While the page is leaving. The SDK counts the page as leaving from beforeunload, or from a Navigation API navigation to another document that your app does not intercept or cancel. While it is leaving, the SDK starts none of its own loads (its chunks, rrweb and the body worker), so it never holds up the next page; a load the leave cancelled is asked for again once the page has stayed. During a leave:

  • a body answered after the leave began is recorded as left at once, unless a worker is already running (a page that cannot run a worker at all redacts it on the main thread as usual);
  • an XHR the leave aborts is recorded as the browser leaves it: status 0, no response body;
  • a GraphQL request whose term code has not loaded is recorded with the term body:*, and nothing is logged;
  • init() never waits on a load the leave holds. If the leave holds rrweb's import, init() resolves, but no DOM events are recorded and nothing is sent until rrweb loads after the leave ends: the page's network calls are recorded and held, as for an offline start (8), and dropped if rrweb then fails to load. If the leave never ends (below), nothing from that page is sent, and nothing is logged.

A route your single-page app intercepts with the Navigation API is not a leave. Otherwise the leave ends only on proof that the page stayed: Chromium aborting the navigation (a cancelled "leave page?" prompt), a pageshow from the back/forward cache, or your script starting a capture. So after a link answered 204, a download, a cancelled prompt in Firefox or WebKit, or a mailto: link in Chromium, the page counts as leaving until one of those happens. A continuous capture's next session, which the visitor's click or key press starts, is not such proof.

15. The SDK wraps the History API​

To record single-page-app navigations, the SDK now replaces these methods with wrappers while it captures:

  • history.pushState, replaceState, back, forward and go;
  • where the browser has the Navigation API, navigation.back, forward and traverseTo.

A router that wraps any of them after the SDK keeps its wrapper when the capture stops. If the page has made one of them impossible to replace, the SDK wraps none of them and writes a KUI_E_NAVIGATION_UNWRAPPED warning to the console. Route changes are then still recorded, with less detail.

A single-page app's visit becomes one flow per route. 3.0.1 recorded no navigation at history.pushState, so a visit that changed route by script was a single flow, on the page where it landed. 3.1.0 records each route change, and a flow never spans a navigation. The same visit is now one flow per route, each holding the steps taken there. Tests or dashboards that expect one flow per visit should look at the flow for each route instead. This is by design, not an SDK defect: Keploy ties the visit back together by chaining a session's flows across client-side navigations into one journey, and journeys, not single flows, are what Keploy's replay (in beta) runs, so a visit such as "add to cart → cart → checkout" is replayed end to end (subject to the redacted-value limit in 17).

16. Network event timestamps​

A fetch event's timestamp is now when the response's headers arrived, not when its body finished. A stream's body can end minutes later; the exchange keeps its place in the recording.

17. Redaction is wider, in every privacy mode​

Redaction happens in the recorded copy only; the requests your page sends are not modified.

What 3.0.1 did. It redacted JSON body values under credential key names (password, token, secret, apikey, auth, session, cookie, pin, ssn, cvv, otp and names ending in password, secret, token and the like), the values of eleven credential-named query parameters, and six default headers. It ran its built-in patterns (JWTs, email addresses, US phone numbers, SSNs, IPv4 addresses, card numbers) over header values, JSON string values and other bodies. It redacted nothing in the DOM or the page's own URL.

What 3.1.0 adds:

  • One name rule everywhere. The same credential-name rule now reads JSON keys, form fields, multipart part names, name=value pairs in text bodies, header names, and query and fragment parameters, so 3.0.1's JSON-key names now apply to forms, query strings and headers too. (The page's own URL and the DOM's URLs keep auth, session, cookie, pin and sig as an app's own parameters: under balanced and off such a value is scrubbed there only when it is shaped like a token (a JWT, or 32 or more letters and digits) or matches a built-in pattern, so ?pin=4821 or a 16-character ?session= value there is recorded.) It also adds names 3.0.1 had nowhere, such as code_verifier, passphrase, totp, passcode, one-time-code names (reset_code, verification_code, oobCode), card expiry names (exp_month, ccExp; in JSON, a bare expiry only beside a card field), an OAuth token exchange's code, and names ending in otp, signature, jwt or credential (the README's "Names" list has the rest). So form posts, FormData, URLSearchParams and XHR string bodies, which 3.0.1 recorded with password=, client_secret and refresh_token in clear, are now redacted.
  • URLs and name=value text inside bodies. A JSON string value that holds a URL has the URL's credential values redacted, and one that holds name=value pairs has a credential pair redacted where the pair starts the string or follows ?, & or a # after a path; a string that is itself JSON is redacted as JSON. In HTML, XML and other text bodies, absolute URLs, link attributes and CSS url()s are read the same way (a relative URL inside prose is not). A presigned S3, GCS or Azure link loses its signing parameters (X-Amz-Signature, X-Amz-Credential, X-Amz-Security-Token, sig), every other byte kept. 3.0.1 only scanned these with its built-in patterns.
  • Headers whose name reads as a credential's (X-Access-Token, X-Csrf-Token, Api-Key, X-Session-Id and the like), on top of the six defaults. A header that carries a URL (Location, Content-Location, Link, Refresh) has that URL's query values redacted as a request URL's are.
  • Provider keys. The built-in patterns now also match keys whose prefix names them (Keploy kep_ keys, GitHub, GitLab, Slack, Stripe, OpenAI and Anthropic keys, npm tokens, webhook secrets, AWS key ids, Google API keys), in headers, bodies and the page. They also run over form bodies, as sent and decoded.
  • Request URLs, which 3.0.1 read only for eleven query names: a credential anywhere in a pair's value (nested or encoded, as in ?next=/reset?token=…) replaces that pair's whole value, a path's ;jsessionid= is redacted, user name and password are dropped, and a credential from the page's own URL is scrubbed from them (below).
  • The page's own URL, the session's referrer and the URLs in the DOM, which 3.0.1 recorded as they were:
    • credential-named query and fragment values (but see the five names above), a token-shaped path segment after a reset, invite, verify or magic-link segment (/reset-password/<token>), and every OAuth authorization response's code and state;
    • values shaped like a token (a JWT, or 32 or more letters and digits that are not a slug; a UUID, or any value under an *id name, is kept) and values a built-in pattern matches (?email=ada%40x.com);
    • the page URL's fragment is dropped unless it is a hash router's route (#/cart), so #reviews is no longer recorded;
    • a URL's user name and password are dropped;
    • a crafted URL (path, query and route over 64 KiB, or more than 32 credential values) is recorded as its origin and /[REDACTED].
  • Credentials from the page's URL are scrubbed from every event, wherever the page or rrweb copied them: DOM, network bodies and headers, and custom events. Inside JSON a number holding one becomes the string "[REDACTED]"; a header or custom-event key holding one is renamed (a second key that becomes the same name gets a #2 suffix), and a DOM attribute so named is dropped. An event the scrub cannot read is dropped rather than sent.
  • The DOM, in every mode. Every text node, and every attribute, is scanned for JWTs and provider keys. Attributes that hold text (title, alt, placeholder, label, aria-label and the other aria-* text, a data-* that is not a URL, a <meta>'s content, a button's or option's value) are also scanned for emails, phone numbers, SSNs, IPv4 addresses and card numbers. Matches become [REDACTED].

Kept now, where 3.0.1 redacted: a paging cursor (pageToken, nextPageToken, NextToken, continuationToken) is recorded as sent, so a replay asks for the next page the recording holds; a flag (true/false) under a credential's name is kept; and an object under otp is read rather than replaced whole, so {"otp":{"enabled":true}} is recorded as sent (its inner code still goes).

Known over-redaction: a few names the rule takes hold some apps' plain data, such as Adyen's public clientKey, a tokenId or Twilio's sid. Their values are recorded as [REDACTED], and a replay serves that string where the app had its value. In the same way, a presigned upload or download URL your app receives in a response is recorded with its signature redacted, so a replay serves a link that no longer works.

Known under-redaction: this is recognition, not a guarantee. A credential in a shape the rules do not recognise (an unusual parameter name, a token that is a dictionary word or digits alone, a short token in a path) is recorded. Past 32 credential values in one page URL, the rest are not scrubbed from other events. In a browser without the Navigation API, a credential the page puts in its URL through a pushState the SDK did not wrap, and hides again before the next recorded event, is not collected. Declare such routes with privacy.secretRoutes, and name a credential parameter like one (anything ending in token).

How recorded bodies are written changed too:

  • a JSON body is redacted in its own text: only the values it replaces change, and every other byte (whitespace, key order, escapes, an integer past 2^53) is kept as the server sent it. 3.0.1 parsed and re-serialised it, which changed whitespace and escapes and rounded large integers;
  • a FormData body is recorded URL-encoded (a+b=c%26d), a file's note included (%5BFile%3A+name%2C+N+bytes%5D). 3.0.1 wrote its fields and the [File: name, N bytes] note raw (k=v&...);
  • a body sent as multipart/form-data that does not parse into its fields is recorded as [Unreadable body], never as it came.

Redacted values and replay. Keploy's hosted service keys the flows it stores, and so the beta tests that replay them, by canonical-key v1, under which a recorded value matches only itself; v1 leaves out of the key only the eleven query names 3.0.1 redacted (and a few volatile ones, such as nonce). So a request whose URL 3.1.0 now redacts beyond those (every query value under strict; under balanced, a credential-named parameter such as ?session=, ?auth_token= or ?pin=, a pair replaced whole for a credential nested in it, a path's ;jsessionid=, or a credential from the page's URL) is recorded with [REDACTED] in its key and does not match the live request at replay. A replay also opens each page at its recorded URL, query included, so a page recorded under strict opens as ?q=[REDACTED], and under balanced a reset link opens as ?token=[REDACTED]. A redacted value matches any live value only under canonical-key v2, which reads it as a wildcard and which the hosted service does not use yet.

Two new options let you correct it. privacy.secretRoutes declares routes whose segments are credentials, for example "/invites/:key". privacy.keepRoutes declares routes whose segments are your own IDs and must be kept. A route the SDK cannot parse stops the capture with KUI_E_PRIVACY_ROUTE_INVALID before anything is sent. See "Known limits" for what declared routes cost.

Because of all this, a page URL recorded by 3.1.0 can differ from the same page recorded by 3.0.1.

18. Warnings are console.warn, not console.error​

3.0.1 wrote its two warnings, KUI_E_EVENT_UNSERIALISABLE and KUI_E_EVENT_OVERSIZED, with console.error. 3.1.0 writes them, and its four new warnings (KUI_E_EVENT_OVERSIZED_SCRUBBING, KUI_E_NAVIGATION_UNWRAPPED, KUI_E_REQUEST_TERM_FAILED and KUI_E_BODY_WORKER_UNAVAILABLE), with console.warn, in the same line format with its evidence JSON. console.error is kept for an error that ends the capture: an init() that is refused (its line written once per page load for each code, see 3), or a server rejection. If you filter the SDK's lines by level, match the KUI_E_ code instead. One more console.warn line has no code: [keploy] the capture's next session could not start:, followed by the error, when a continuous capture's next session fails to start.

19. The SDK leaves half the keepalive quota to the page​

Browsers refuse a keepalive fetch or a sendBeacon once more than 64 KiB of keepalive bodies are in flight from the page (measured as 65,536 bytes in Chromium, Firefox and WebKit; Firefox does not count sendBeacon). 3.0.1 let its own uploads use the whole quota, so a page's own lead-form POST or analytics beacon could be refused while an SDK upload was on the wire.

3.1.0 uses at most half the quota, 32 KiB, counting an upload still on the wire, and leaves the rest to the page. Behaviour changes:

  • An upload over 32 KiB gzipped is sent without keepalive (3.0.1: over 64 KiB). A navigation before it completes cancels it, although a tab close does not (measured in Chromium on a 50 KB/s uplink, a 90 KB gzipped upload: 0 of 40 arrived across a navigation, 5 of 5 across a tab close).
  • The pagehide request carries at most 32 KiB of queued events; in 3.0.1 it carried 64 KiB. An event over 32 KiB (with its envelope) is posted the moment it is queued, as 3.0.1 did for one over 64 KiB.
  • So that a visitor who leaves with more than that queued loses as little as possible, a queue larger than the pagehide request can carry is sent at once, as a plain fetch (never keepalive), one upload at a time, until it is back under. So a busy page can make more uploads than one per batchInterval.
  • A failed upload waiting to be re-sent is sent first at pagehide, whole and as it was first posted, and nothing is sent past it: later DOM events are changes against it, so a recording that skipped it could not replay past the gap. If that upload's body alone is over 32 KiB, nothing goes at pagehide, as in 3.0.1 for one over 64 KiB.

New​

GraphQL requests​

Every recorded network event now carries a requestTerm field:

  • graphql:<operationName>#<16 hex> for a GraphQL request sent as a JSON body. The hex is a SHA-256 over the query document, taken after every string and number literal has been blanked, so no variable or literal value is recorded in it.
  • graphql:<operationName>#pq for a persisted query.
  • "" for no body, a form, or a text body that is not a GraphQL request. This includes GraphQL sent as a GET, as a JSON array (a batch) or as raw application/graphql.
  • body:* when the term is unknown: a body that is not text (a Blob, a buffer, a stream), a text body over 4 Mi characters, a body the SDK could not read or hash, a request made while the page is leaving before the term code has loaded (see 14), or one refused by the memory bound while the term code's load hangs (below).

The field is absent only if computing it threw. In that case a KUI_E_REQUEST_TERM_FAILED warning goes to the console once per capture.

Hashing needs SubtleCrypto, which browsers provide only in secure contexts (HTTPS or localhost). On a plain-HTTP page, a GraphQL document is therefore recorded as body:*.

Keploy's hosted service accepts the field but does not use it yet. It keys the flows it stores, and so the beta tests that replay them, by canonical-key v1, which has no term: those tests answer GraphQL calls of one method and URL in the order they were recorded, whatever operation each runs.

The code that computes the term is a separate chunk of about 1.2 kB gzipped (1.4 kB for CommonJS), @keploy/capture-sdk/request-term. You do not import it yourself. The SDK loads it once, the first time a request body could be a GraphQL request: a JSON object whose text holds "query" (as a key or a value), persistedQuery, or a \u escape. A search API that posts {"query": "…"} loads it too. A page that sends no such body never loads it.

How the chunk resolves:

  • Bundlers that read the package's exports map resolve the subpath from it.
  • Bundlers that ignore the exports map, such as webpack 4 (as used by Create React App 4) and Parcel 2 with its default settings, resolve it through request-term/package.json, which the package ships.
  • No bundler. Serve dist/ as it is; the SDK loads dist/request-term.mjs from beside dist/index.mjs, and honours an import-map entry for @keploy/capture-sdk/request-term first.
  • CSP. If your bundler emits the chunk as its own file, your CSP's script-src must allow it, as it allows your app's other chunks.

If the chunk cannot load, the capture continues. Those requests are recorded with requestTerm: "body:*", KUI_E_REQUEST_TERM_FAILED is logged once, and the load is not retried for the life of the page.

If the chunk's load hangs, GraphQL exchanges waiting for their term count against the same memory bound as bodies waiting for redaction (see 14). Past it, a new request's term is body:* at once, and an exchange that cannot wait is recorded at once with its bodies cut. What waits is recorded, with the term body:*, when the page leaves, the capture pauses or stop() settles; a hidden tab alone does not end the wait. A page whose chunk has loaded keeps every term.

Single-page-app navigations​

A route change without a page load is now recorded the way rrweb records a page load: as a Meta event (rrweb's type 4) with the new URL. A route change's Meta event also carries a cause:

causewhat moved the page
pushpushState, or the Navigation API reporting a push
replacea replaceState that changes the URL
traverseBack or Forward
hasha hash-route change the History API did not make (only where the browser has the Navigation API; elsewhere it reads as traverse)

rrweb's own Meta events, written with every full snapshot, carry no cause. A route change's Meta event can carry two more fields:

  • userInitiated, where the browser has the Navigation API;
  • initiator: "script", when the page's own script called history.back(), forward() or go(), or the Navigation API's back(), forward() or traverseTo().

A change of the query string alone is not recorded as a navigation. See 15 for the wrapping this requires.

continuous​

continuous: true (default false) keeps a long-lived tab recording, one session at a time. A new session starts at the visitor's next click, tap or key press after the previous session ends. A session ends:

  • at maxSessionDuration;
  • or when the server answers that it has completed the session (409 session_completed) or that the session is full (413 session_full). Keploy's ingest sends that reason; an ingest server too old to send it keeps the refusal terminal.

A tab nobody uses posts nothing. sampleRate is rolled once, when init() starts the capture: each session that follows a recorded one is recorded too, with no new roll. continuous has no effect when you set sessionIdGenerator.

Error codes​

These five new codes reach onError:

codewhen
KUI_E_DOM_RECORDER_UNAVAILABLErrweb could not be loaded (see 8)
KUI_E_STRICT_ATTRIBUTES_UNAVAILABLEunder strict, its attribute allow-list chunk could not be loaded; nothing was recorded (see 5)
KUI_E_PRIVACY_ROUTE_INVALIDa secretRoutes or keepRoutes entry is not a route (see 17)
KUI_E_CAPTURE_DECLINEDthe browser sent DNT or GPC (see 2)
KUI_E_PRIVACY_CONFLICTstrict mode together with maskNetworkBodies: false (see 1)

These four new codes are console warnings only. They never reach onError, and the capture continues:

codewhen
KUI_E_EVENT_OVERSIZED_SCRUBBINGan event became too large to send once credentials were scrubbed from it, so it was dropped
KUI_E_NAVIGATION_UNWRAPPEDthe SDK could not wrap the History API (see 15)
KUI_E_REQUEST_TERM_FAILEDcomputing a request's requestTerm threw, or the term chunk could not load; the request is recorded without its term, or as body:*. Most body:* terms come with no warning (see "GraphQL requests")
KUI_E_BODY_WORKER_UNAVAILABLEthe body worker could not run, or the body chunk could not load (see 13); said once per page for each part

Every error now also carries remedy.docs, a link to that error's section of the Keploy docs (https://keploy.io/docs/ui-capture/errors#<code>, in lower case with - for _).

Input events say who made them​

Each input event rrweb records now carries userTriggered: true for the visitor's own input, false for a value the page's script wrote (a form cleared after a submit, the other radios of a group, a date picker's write).

Fixes​

  • fetch(new Request(url, { body })) works with the SDK. In 3.0.x the SDK consumed such a Request to inspect it, so the page's own fetch() threw Cannot construct a Request with a Request object that has already been used. That is how ky and axios's fetch adapter send every POST. A FormData inside such a Request is now redacted by field; 3.0.1 recorded it as raw multipart, passwords included.
  • Credentials in non-JSON bodies are redacted (see 17). 3.0.1 sent a form's password, an OAuth refresh's refresh_token and client_secret, and an XHR string body's password= as typed.
  • The pattern scanners run in linear time. 3.0.1's email pattern could block the page's main thread for a long time on a large body (measured: 49–68 s on a 256 KB body). The scanners now run in time linear in the text they scan.
  • Create React App 4 (webpack 4 with babel-loader) records the DOM. There, import("rrweb") arrives as { default: module.exports }. 3.0.1 read record off it, found nothing, and recorded no page activity, silently, while still recording network calls. 3.1.0 takes the default, for rrweb and for its own chunks.
  • Requests leave at once. 3.0.1 read the request body (a Blob's text, or a whole copy of a Request, file bytes included) before it called the browser's fetch, so uploads started later and the body was held in memory twice. 3.1.0 calls the browser's fetch first.
  • Streamed responses reach the page as they arrive (see 11).
  • An ingest outage no longer slows the page: what the SDK holds is capped in bytes, failed batches are dropped oldest first past the cap, and uploads back off (see 9, 10).
  • Batches that fill go sooner. A batch that fills while an upload is on the wire is now sent as soon as that upload settles. In 3.0.1 it waited for the next batchInterval, and a tab killed meanwhile lost it.

Other changes​

  • Bundle format. The bundle now ships fully minified, with source maps (dist/*.map) beside it that map back to the SDK's sources.
  • Private names are shortened. The build shortens the names of the SDK classes' private members. Code that reached into SDK internals at run time (for example a transport's queue) breaks; nothing public changes, and the type declarations are unchanged by it.
  • New package entry points. exports gains ./request-term, ./strict-attributes, ./body-redact and ./body-worker-start, with package.json stubs for bundlers that ignore exports. The package also sets unpkg and jsdelivr to dist/index.mjs, a browser field and a Parcel alias for the worker start. You do not import any of these yourself.

Known limits​

  • Declared routes cost main-thread time. With secretRoutes or keepRoutes, scrubbing a string costs time in proportion to its length times the number of long declared values it holds, and a crafted link can declare up to 32. Measured in Chromium: 300 such links made init() take 2.6 s where it took 0.18 s without them.
  • The DOM's URLs are scrubbed on every DOM event, in every mode. This runs on the page's main thread. The SDK's tests bound the scrub of a synthetic 50,000-element snapshot holding 30,000 URLs to under a second of CPU time in Node; it has not been timed on a page.
  • A page whose snapshot is too large to send is serialised again every 60 s while it stays that large (see 9).
  • Bodies past the redaction bound are recorded cut (see 14).

Size​

dist/index.mjs is about 40.9 kB gzipped (40,927 B; the CommonJS dist/index.js is 41.1 kB, 41,121 B, and dist/index.bundler.mjs, which the module field names, 40.9 kB, 40,905 B), with rrweb not included. Measured on the repository's build; the published files differ by a few bytes, since they carry the version string. The budgets are 40,960 B (both ESM builds) and 41,316 B (CommonJS).

Other files load only when needed:

  • dist/body-redact.mjs (about 9.7 kB; 9.9 kB for CommonJS) at init(), and the worker dist/body-worker.js (about 9.3 kB) in the next idle period, for every capture that records bodies, which is the default (see 13);
  • strict's attribute allow-list (about 1.3 kB; 1.5 kB for CommonJS), under privacyMode: "strict" alone (strict loads neither body file);
  • the GraphQL term chunk (about 1.2 kB; 1.4 kB for CommonJS), on pages that send a body that could be GraphQL (see "GraphQL requests").

For comparison, 3.0.1 shipped unminified at 26.2 kB gzipped (ESM), with body redaction inside it. The same 3.0.1 file minified, as a production bundler would minify it, is 12.3 kB. In a minified production build, expect about 28.6 kB more gzipped JavaScript in the bundle on every page that loads the SDK (about 27.9 kB for CommonJS), and, under the default balanced mode, about 19 kB more fetched at run time for the body worker and chunk.

If you ran a release candidate​

Since 3.1.0-rc.2:

  • The page gets the network's own Response for every fetch (see 11). rc.2 handed the page a Response it built around the body (unless bodies were masked whole, or for HEAD, 204, 205 and 304), read each body ahead of the page up to maxBodySize, and recorded every body, read or not. Now:
    • a body the page never reads is recorded as [Response body not read by the page], and later (see 11). That includes one consumed by cache.put() or WebAssembly.instantiateStreaming(), which rc.2 recorded whole;
    • in Chromium, a response your page reads whole is no longer reported as net::ERR_ABORTED in DevTools and request-failure handlers, as rc.1 and rc.2 could report a chunked one. A body your page reads to its end through res.body can still be reported so, as without the SDK;
    • a Cache API round trip keeps the response's url and type, and WebAssembly.instantiateStreaming() sees the URL;
    • a fetch wrapper installed before the SDK that reads or clones the Response after handing it on no longer finds the body taken;
    • a body read only through a clone's stream is recorded as not read;
    • a body that fails part-way while your page reads it whole keeps nothing, where rc.2 kept what had arrived;
    • a page that takes res.body before the body chunk arrives gets the browser's stream, and may be recorded "not captured: early" (see 14).
  • A refused init() reaches onError in a task of its own, paced and bounded (see 3). rc.2 called onError synchronously inside init() for a declined visitor and a conflicting config, and in init()'s microtasks for the other refusals at start; a load that failed after an offline start or a held leave was handed over from its loader, after init() had resolved. It wrote a refused init()'s console.error line every time, and built each error as its refusal happened. A handler that re-inited the same config for every code recursed until the browser's call stack ran out, or kept the page busy until it stopped responding. The SDK's error spec moves from sdk-errors v4 to v5.
  • Bodies waiting for redaction are bounded (see 14). Past the bound they are recorded cut; rc.2 held them without limit.
  • A hung GraphQL term chunk is bounded the same way (see "GraphQL requests"); rc.2 held every waiting exchange until the page closed.
  • A body passed in a plain-object init is no longer copied once more by the browser to build the SDK's own Request, in every mode, and a Request object's body is read after fetch() returns, not inside it.
  • No body worker outlives its captures. After stop(), or under a capture that records no bodies, the SDK keeps no worker and no poll.
  • The CommonJS files and the worker now run in strict mode, as their sources are written. rc.2's dist/index.js, request-term.js, strict-attributes.js and body-worker.js shipped without "use strict", so they ran in sloppy mode wherever the consumer did not add it. ESM builds are unchanged.
  • Private names are shortened in the build (see "Other changes").
  • Sizes: rc.2's 40.7 / 40.9 / 40.6 kB are now 40.9 / 41.1 / 40.9 kB, and dist/body-redact.mjs moved from 9.4 to 9.7 kB, since the res.body relay moved into it.

Since 3.1.0-rc.1, besides the above:

  • strict's attribute allow-list and KUI_E_STRICT_ATTRIBUTES_UNAVAILABLE (5). rc.1 had 9 error codes, 6 classes and 5 warning codes; 3.1.0 has 10, 7 and 6 (7);
  • warnings as console.warn (18), and the keepalive share (19);
  • body redaction in a Web Worker, with the no-bundler and CDN loading, and PrivacyEngine.maskNetworkData() no longer redacting bodies by itself (13);
  • the module field moved to dist/index.bundler.mjs; the ./strict-attributes, ./body-redact and ./body-worker-start subpaths and their stubs; the unpkg, jsdelivr, browser and alias fields;
  • the body chunk requested at init(), the "not captured" notes and the leave handling (14);
  • bodies masked whole decided without reading them (6), and HEAD, 204, 205 and 304 handed over untouched;
  • full batches sent as an upload settles;
  • sizes: rc.1 was 41.4 kB (ESM) and 41.7 kB (CommonJS), with body redaction inside the bundle.