@keploy/capture-sdk reference: options and API
The public API of @keploy/capture-sdk 3.1.0: the files the package ships, the methods of KeployCapture, every option init takes, the errors onError receives, and what each batch carries. The guides explain each one in context: Install the SDK, Sessions and sampling, Privacy and masking and Network calls and bodies.
Entry points
You import the package by its name. Which file that loads depends on how your build reads the package:
| You load it with | File | Used by |
|---|---|---|
import (the exports map) | dist/index.mjs | Vite, webpack 5, Next.js and esbuild, and a page with no bundler, which imports it by its path |
require (the exports map, and main) | dist/index.js | CommonJS builds, such as a server build of your app, and Node |
The module field | dist/index.bundler.mjs | Bundlers that read module and not the exports map: webpack 4, and Parcel 2 by default |
types | dist/index.d.ts | TypeScript |
The unpkg and jsdelivr fields | dist/index.mjs | Those CDNs; Assets on a CDN says which URLs work |
dist/index.bundler.mjs is the same SDK, built so that webpack 4 never reads import.meta, and it loads none of the SDK's files from beside it: a bundler resolves them by name.
The SDK loads its other files itself, when a capture needs them: @keploy/capture-sdk/request-term, /strict-attributes, /body-redact, /body-worker-start, and the body worker dist/body-worker.js. Your bundler emits each as a file of your build, where it can: Bundlers and frameworks says where the worker is missing. For bundlers that ignore the exports map, the package also ships request-term/package.json, strict-attributes/package.json, body-redact/package.json and body-worker-start/package.json. Bundlers and frameworks says what each setup needs, and Content-Security-Policy and workers when each file loads.
There is no script-tag build: the only way in is an import. The package's only dependency is rrweb, ^2.1.6.
KeployCapture
KeployCapture holds the page's one capture. It has static methods only: you never construct it.
import {KeployCapture} from "@keploy/capture-sdk";
await KeployCapture.init({endpoint, apiKey}); // start; the only call you need
KeployCapture.pause(); // keep the session, record nothing more
KeployCapture.resume();
KeployCapture.getSessionId(); // "" when no session is live
KeployCapture.getCaptureIdentity(); // the backend join, or why there is none
KeployCapture.getInstance(); // the capture, or null
await KeployCapture.stop(); // stop recording and send what is queued
init(config)
static init(config: CaptureConfig): Promise<KeployCapture>
Starts the capture and resolves to it. config is a CaptureConfig: endpoint and apiKey are required. While a capture is live, another init() returns that same capture and changes nothing, so call it once per page load, not per route. An init() made while a continuous capture waits for its next session starts that session at once, and a pause() in force carries into it.
init() does not reject when the SDK refuses to start, such as for a privacy signal or an invalid option: it resolves, and the error reaches you through onError, in a task of its own. Online, it resolves once rrweb has loaded. Don't make your app's rendering wait for it: see Call init once, as early as you can.
stop()
static stop(): Promise<void>
Ends the capture: recording stops and the queued events are sent. A body still being read gets up to one second to finish, and is then recorded cut. The promise resolves once the last send has settled; awaiting it is optional. stop() releases the capture, so a later init() starts a new session, and it ends a continuous capture's wait for its next session. When a session that ended on its own still has its last send in flight, stop() waits for it too, for at most 10 seconds.
pause() and resume()
static pause(): void
static resume(): void
pause() keeps the session and records nothing more: no DOM event, and no network call that starts or is answered while it is paused. A call still reading its body is recorded at once with what had arrived, cut and marked ...[truncated]. Between a continuous capture's sessions, a pause is kept for the next session. resume() records again; a tab that is hidden stays paused until it is shown. Pause, resume, stop and hidden tabs has the details.
getSessionId()
static getSessionId(): string
The live session's id: the SDK's UUID, or what your sessionIdGenerator returned. It is "" when no session is live: before init(), after stop(), and on a page that sampleRate left out. This is the id POST /ui/v1/sessions/<id>/complete takes, and the one uiCaptureStatus lists as sdkSessionId. Read it before you call stop(), which clears it.
getInstance()
static getInstance(): KeployCapture | null
The capture, a sampled-out one included. null before init(), after stop(), after a declined or refused init(), and between a continuous capture's sessions.
getCaptureIdentity()
static getCaptureIdentity():
| {identity: CaptureIdentity}
| {refusal: "no-csprng"}
| null
What lets Keploy join this recording to a backend recording of the same requests, exactly as the SDK sends it with each batch. identity holds captureId (the session id), sessionNonce (a random value that tells this run from another run of the same session id), t0WallMs (when the capture started, in Unix milliseconds) and appOrigins (the page's origin, or none when the page has no usable origin, such as a data: URL). {refusal: "no-csprng"} means the browser has no crypto.getRandomValues to mint the nonce with: the recording is still made, and cannot be joined. It is null before a capture has started, and after stop().
CaptureConfig
What init() takes. Only endpoint and apiKey are required.
| Option | Type | Default | What it does |
|---|---|---|---|
endpoint | string | required | The ingest endpoint the batches are posted to: https://api.keploy.io/ui/v1/ingest on Keploy Cloud, or your API server's URL followed by /ui/v1/ingest. The SDK's own requests to it are never recorded. |
apiKey | string | required | The app's ingest key, sent as X-API-Key with every batch. Never another kind of Keploy key. |
privacyMode | "balanced", "strict" or "off" | "balanced" | How much of the page is recorded. See Choose a privacy mode. |
sampleRate | number, 0 to 1 | 1 | The fraction of captures recorded, rolled when init() starts one. See Sampling. |
networkCapture | boolean | true | Records fetch and XMLHttpRequest calls. false records the page only. |
maxSessionDuration | number, milliseconds | 600000 | When a session ends on its own: 10 minutes. |
continuous | boolean | false | Keeps capturing for the life of the page, one session at a time. No effect with a sessionIdGenerator. See Keep capturing a long-open page. |
batchSize | number | 50 | Events per request, at most: clamped to 5,000, and a batch is also cut at 10 MiB. |
batchInterval | number, milliseconds | 5000 | How often queued events are sent when there is not a full batch; a full batch is sent at once. |
maxQueueSize | number | 5000 | Events held unsent. Past it, or past 16 MiB of events, the oldest are dropped. |
maxBodySize | number, UTF-16 code units | 524288 | How much of a request or response body is recorded (512 KB). See Large bodies. |
maskSelectors | string[] | none | CSS selectors whose text is masked, with every text node below them. Merged with privacy.maskSelectors. Input values are decided by privacyMode alone. |
unmaskSelectors | string[] | none | CSS selectors whose text is kept in the clear, overriding maskSelectors and "strict" below them. Text only: it cannot unmask an input value. Merged with privacy.unmaskSelectors. |
privacy | Partial<PrivacyConfig> | none | Finer privacy controls: see PrivacyConfig. |
sessionIdGenerator | () => string | none | Your own session id instead of the SDK's UUID: 1 to 200 characters of letters, digits, ., - and _, with no empty dot-separated part, returned synchronously. See Your own session ids. |
honorPrivacySignals | boolean | true | Records nothing for a browser that sends Do Not Track or Global Privacy Control, and reports KUI_E_CAPTURE_DECLINED. Set false only where your site has its own lawful basis and says so in its privacy policy. |
onError | (err: AnyCaptureError) => void | none | Called once when a condition ends the capture, or keeps it from starting, with a CaptureError. Warnings never call it. See Handle SDK errors and warnings. |
PrivacyConfig
What the privacy option takes. Every field is optional in privacy; the default is what applies when you leave it out.
| Field | Type | Default | What it does |
|---|---|---|---|
maskSelectors | string[] | [] | As CaptureConfig.maskSelectors, merged with it. |
unmaskSelectors | string[] | [] | As CaptureConfig.unmaskSelectors, merged with it. |
blockSelectors | string[] | [] | CSS selectors whose elements are left out of the recording entirely. See Mask, unmask and block elements. |
maskNetworkBodies | boolean | false | Records every request and response body as [MASKED], without reading the response. privacyMode: "strict" sets it, and refuses false beside it with KUI_E_PRIVACY_CONFLICT. See Mask every body. |
sensitiveHeaders | string[] | the six | Header names whose values are replaced with [REDACTED]. Adds to the six that are always redacted, authorization, cookie, set-cookie, x-api-key, x-auth-token and proxy-authorization, and cannot remove them. |
piiPatterns | PiiPattern[] | [] | Your own patterns, as {name: string, pattern: RegExp}, run over headers and bodies, never over URLs. See Your own patterns. |
secretRoutes | readonly string[] | [] | Routes of your app whose :name segments are credentials, such as "/invites/:key". See Credentials in URLs. |
keepRoutes | readonly string[] | [] | Routes whose :name segments are your app's own ids, which the SDK would otherwise take for a token, such as "/teams/invite/:teamId". |
A secretRoutes or keepRoutes entry that is not a valid route refuses the capture with KUI_E_PRIVACY_ROUTE_INVALID.
defaultPrivacyConfig() returns these defaults, the six headers included. Its maskNetworkBodies is false, so passing it whole beside privacyMode: "strict" is refused with KUI_E_PRIVACY_CONFLICT.
Errors and warnings
onError receives a CaptureError, one of these subclasses. Each carries code, status (the HTTP status, or null when the SDK refused before sending anything), serverMessage, issues, remedy ({command, manual, docs}, where docs links the code's section of UI Capture errors and warnings), evidence and message. In TypeScript, the handler's argument is AnyCaptureError, a union of the subclasses, so checking err.code narrows err.evidence to that code's fields.
| Class | Codes | evidence |
|---|---|---|
IngestRejection | KUI_E_INGEST_KEY_REJECTED, KUI_E_INGEST_ENDPOINT_NOT_FOUND, KUI_E_SESSION_CONFLICT, KUI_E_INGEST_REJECTED | status, serverMessage, endpoint, sessionId, issues when the server sent them |
SessionIdRefusal | KUI_E_SESSION_ID_INVALID | sessionId, received, rule |
DomRecorderRefusal | KUI_E_DOM_RECORDER_UNAVAILABLE | reason |
StrictAttributesRefusal | KUI_E_STRICT_ATTRIBUTES_UNAVAILABLE | reason |
PrivacyRouteRefusal | KUI_E_PRIVACY_ROUTE_INVALID | option, received, rule |
CaptureDeclined | KUI_E_CAPTURE_DECLINED | signal: "doNotTrack" or "globalPrivacyControl" |
PrivacyConflict | KUI_E_PRIVACY_CONFLICT | privacyMode, option |
Warnings are not errors: the capture goes on, onError is not called, and the SDK writes one console.warn line with the code. Two tables list every code with its summary, its remedy and its evidence fields:
SDK_ERRORS: the ten error codes above.SDK_WARNINGS: the six warning codes,KUI_E_EVENT_UNSERIALISABLE,KUI_E_EVENT_OVERSIZED,KUI_E_EVENT_OVERSIZED_SCRUBBING,KUI_E_NAVIGATION_UNWRAPPED,KUI_E_REQUEST_TERM_FAILEDandKUI_E_BODY_WORKER_UNAVAILABLE.
Two helpers read an ingest server's answer as the SDK does: codeForStatus(status) returns the code a status ends the capture with, or null for a 2xx, a 429 or a 5xx, which are not errors; parseServerError(body) returns the server's sentence and its issues.
Other exports
The package also exports these, by name:
- Privacy:
PrivacyEngine, which runs the SDK's masking over your own strings (see Try your configuration), anddefaultPrivacyConfig. - Session ids:
isValidSessionId,SESSION_ID_PATTERN,SESSION_ID_MAX_LENGTH(200) andSESSION_ID_RULE, the rule as the server words it. - Capture identity:
CaptureIdentityBuilder,mintSessionNonceandcurrentOrigin. - The parts
KeployCaptureis built from:KeployCaptureRecorder,NetworkInterceptorandTransport. - A helper:
describeValue. - Types:
CaptureConfig,PrivacyConfig,PiiPattern,SessionEvent,SessionEventType,NetworkEvent,NetworkRequestType,SessionMetadata,CaptureSession,TransportPayload,TransportConfig,EventCallback,NetworkEventCallback,RecorderState,OnEventCallback,OnSessionEndCallback,CaptureIdentity,IdentityRefusal, and the error typesAnyCaptureError,CaptureErrorCode,CaptureWarningCode,CaptureRemedy,CaptureEvidence,CaptureWarningEvidence,IngestEvidence,SessionIdEvidence,DomRecorderEvidence,PrivacyRouteEvidence,CaptureDeclinedEvidence,PrivacyConflictEvidence,PrivacySignal,ServerAnsweredCode,ServerErrorandServerIssue.
What a batch carries
Each request the SDK posts to endpoint has the ingest key in its X-API-Key header, and a JSON body, gzipped when the browser has CompressionStream, of this shape (TransportPayload):
| Field | What it is |
|---|---|
sessionId | The session's id. |
batchId | The batch's own id, minted once and sent unchanged with the same events on every retry, so a batch sent twice is stored once. |
events | The batch's events, each a SessionEvent: id, sessionId, timestamp (Unix milliseconds), type ("dom", "network" or "custom"), data, and seq, its place in the session. |
metadata | The page's url, userAgent, viewport, referrer, language, devicePixelRatio and the timestamp the session started. |
sdk | {name, version}: version is the SDK's, such as 3.1.0. |
captureIdentity | The capture identity, or null when the capture cannot be joined. |
A "dom" event's data is an rrweb event. A "network" event's data is a NetworkEvent: method, url, requestHeaders, requestBody, responseHeaders, responseBody, statusCode, duration (milliseconds), type ("fetch" or "xhr") and requestTerm (see GraphQL), every value masked as Privacy and masking describes. What leaves the browser says what else the SDK sends, and to whom.
Version differences
This page describes 3.1.0. 3.0.1 has no continuous, honorPrivacySignals, privacy.secretRoutes or privacy.keepRoutes, its remedy has no docs, and it raises fewer codes: the note at the top of UI Capture errors and warnings lists them. The 3.1.0 release notes list everything 3.1.0 changes, and the TypeScript changes that can stop a 3.0.1 handler from compiling are in its section 7.