Skip to main content

@keploy/capture-sdk reference: options and API​

View as Markdown
FreeTeamsScaleEnterpriseSelf-HostedDedicated

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 withFileUsed by
import (the exports map)dist/index.mjsVite, 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.jsCommonJS builds, such as a server build of your app, and Node
The module fielddist/index.bundler.mjsBundlers that read module and not the exports map: webpack 4, and Parcel 2 by default
typesdist/index.d.tsTypeScript
The unpkg and jsdelivr fieldsdist/index.mjsThose 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.

OptionTypeDefaultWhat it does
endpointstringrequiredThe 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.
apiKeystringrequiredThe 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.
sampleRatenumber, 0 to 11The fraction of captures recorded, rolled when init() starts one. See Sampling.
networkCapturebooleantrueRecords fetch and XMLHttpRequest calls. false records the page only.
maxSessionDurationnumber, milliseconds600000When a session ends on its own: 10 minutes.
continuousbooleanfalseKeeps capturing for the life of the page, one session at a time. No effect with a sessionIdGenerator. See Keep capturing a long-open page.
batchSizenumber50Events per request, at most: clamped to 5,000, and a batch is also cut at 10 MiB.
batchIntervalnumber, milliseconds5000How often queued events are sent when there is not a full batch; a full batch is sent at once.
maxQueueSizenumber5000Events held unsent. Past it, or past 16 MiB of events, the oldest are dropped.
maxBodySizenumber, UTF-16 code units524288How much of a request or response body is recorded (512 KB). See Large bodies.
maskSelectorsstring[]noneCSS selectors whose text is masked, with every text node below them. Merged with privacy.maskSelectors. Input values are decided by privacyMode alone.
unmaskSelectorsstring[]noneCSS 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.
privacyPartial<PrivacyConfig>noneFiner privacy controls: see PrivacyConfig.
sessionIdGenerator() => stringnoneYour 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.
honorPrivacySignalsbooleantrueRecords 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) => voidnoneCalled 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.

FieldTypeDefaultWhat it does
maskSelectorsstring[][]As CaptureConfig.maskSelectors, merged with it.
unmaskSelectorsstring[][]As CaptureConfig.unmaskSelectors, merged with it.
blockSelectorsstring[][]CSS selectors whose elements are left out of the recording entirely. See Mask, unmask and block elements.
maskNetworkBodiesbooleanfalseRecords 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.
sensitiveHeadersstring[]the sixHeader 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.
piiPatternsPiiPattern[][]Your own patterns, as {name: string, pattern: RegExp}, run over headers and bodies, never over URLs. See Your own patterns.
secretRoutesreadonly string[][]Routes of your app whose :name segments are credentials, such as "/invites/:key". See Credentials in URLs.
keepRoutesreadonly 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.

ClassCodesevidence
IngestRejectionKUI_E_INGEST_KEY_REJECTED, KUI_E_INGEST_ENDPOINT_NOT_FOUND, KUI_E_SESSION_CONFLICT, KUI_E_INGEST_REJECTEDstatus, serverMessage, endpoint, sessionId, issues when the server sent them
SessionIdRefusalKUI_E_SESSION_ID_INVALIDsessionId, received, rule
DomRecorderRefusalKUI_E_DOM_RECORDER_UNAVAILABLEreason
StrictAttributesRefusalKUI_E_STRICT_ATTRIBUTES_UNAVAILABLEreason
PrivacyRouteRefusalKUI_E_PRIVACY_ROUTE_INVALIDoption, received, rule
CaptureDeclinedKUI_E_CAPTURE_DECLINEDsignal: "doNotTrack" or "globalPrivacyControl"
PrivacyConflictKUI_E_PRIVACY_CONFLICTprivacyMode, 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_FAILED and KUI_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), and defaultPrivacyConfig.
  • Session ids: isValidSessionId, SESSION_ID_PATTERN, SESSION_ID_MAX_LENGTH (200) and SESSION_ID_RULE, the rule as the server words it.
  • Capture identity: CaptureIdentityBuilder, mintSessionNonce and currentOrigin.
  • The parts KeployCapture is built from: KeployCaptureRecorder, NetworkInterceptor and Transport.
  • 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 types AnyCaptureError, CaptureErrorCode, CaptureWarningCode, CaptureRemedy, CaptureEvidence, CaptureWarningEvidence, IngestEvidence, SessionIdEvidence, DomRecorderEvidence, PrivacyRouteEvidence, CaptureDeclinedEvidence, PrivacyConflictEvidence, PrivacySignal, ServerAnsweredCode, ServerError and ServerIssue.

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):

FieldWhat it is
sessionIdThe session's id.
batchIdThe batch's own id, minted once and sent unchanged with the same events on every retry, so a batch sent twice is stored once.
eventsThe batch's events, each a SessionEvent: id, sessionId, timestamp (Unix milliseconds), type ("dom", "network" or "custom"), data, and seq, its place in the session.
metadataThe 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.
captureIdentityThe 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.