Skip to main content

Frontend Setup: JavaScript/TypeScript via CDN

Enterprise Configuration

This guide installs the SF Veritas Recorder SDK directly from the jsdelivr CDN via a single <script> tag — no npm install, no bundler, no code changes. Useful for static sites, Shopify / WordPress / Webflow embeds, server-rendered pages, and any frontend where adding a build dependency isn't practical.

If your frontend already has a build step (React, Vue, Angular, etc.), prefer the npm install path — you get TypeScript types, the Babel source-map plugin, and smaller per-request download via your existing bundler.

Minimal snippet​

Drop this into your page's <head> (or just before </body>) and you're done:

<script
  src="https://cdn.jsdelivr.net/npm/@sailfish-ai/recorder@1.11.6"
  data-api-key="<see-api-key-from-your-account-settings-page>"
  data-service-identifier="acme-corp/web-app/index.html"
  data-service-version="1.0.0"
  data-domains-to-propagate-header-to="*"
></script>

That's it. The UMD build auto-initializes when the script executes — any data-* attributes on the <script> tag are picked up and forwarded to initRecorder(...) automatically.

The URL has no /dist/... suffix

@sailfish-ai/recorder's package.json declares a jsdelivr entry, so cdn.jsdelivr.net/npm/@sailfish-ai/recorder@<version> resolves directly to the UMD build. Shorter + future-proof if the internal filename ever changes.

How data-* attributes map to initRecorder options​

The auto-init reads the <script> tag's dataset and forwards each entry to the initRecorder({ ... }) call that the npm path would let you write explicitly. The mapping follows the standard HTML5 dataset convention: a camelCase option named fooBarBaz lives at data-foo-bar-baz="...". Lower-case every word, hyphen between word boundaries.

A few examples:

initRecorder optiondata-* attribute
apiKeydata-api-key
serviceIdentifierdata-service-identifier
serviceVersiondata-service-version
domainsToPropagateHeaderTodata-domains-to-propagate-header-to
enableFiberTrackingdata-enable-fiber-tracking
captureResponseBodyMaxMbdata-capture-response-body-max-mb

All supported attributes are listed below.

Singular Header, not plural

The frontend SDK's option is named domainsToPropagateHeaderTo (singular "Header"). The backend SDK uses the plural domainsToPropagateHeadersTo. They're two separate options in two separate SDKs — make sure you copy the right one when moving code between frontend and backend examples.

Because attribute values are always strings in HTML, non-string options are coerced:

  • Arrays (e.g. data-domains-to-propagate-header-to): comma-separated values. Spaces around commas are trimmed. Example: data-domains-to-propagate-header-to="*.acme.com,api.acme.com".
  • Booleans (e.g. data-enable-fiber-tracking): the literal string "true" enables the flag; anything else (including "false" or the attribute being absent) leaves the SDK default.
  • Numbers (e.g. data-capture-response-body-max-mb): parsed with Number(). Non-numeric values are silently ignored.

Full attribute reference​

Required​

AttributeTypeDescription
data-api-keystringYour Sailfish Enterprise API key. Auto-replaced for logged-in readers as <ApiKey />.

Service identification​

AttributeTypeDefaultDescription
data-service-identifierstring""Unique identifier in <org>/<repo>/<path> format.
data-service-versionstring""Version of your application.
data-git-shastringAuto-detectedGit commit SHA for version tracking. Usually set by your build pipeline.

Domain allowlist / blocklist​

AttributeTypeDefaultDescription
data-domains-to-propagate-header-toCSV[]Domains that SHOULD receive tracing headers. Supports wildcards (*.example.com, api.example.com/v1/*). Auto-replaced for logged-in readers as <AllowedDomainsCsv />.
data-domains-to-not-propagate-header-toCSVsee belowDomains to EXCLUDE from header propagation.

By default, tracing headers are not propagated to common third-party services (Twitter, Gravatar, Zendesk, AWS, etc.) to avoid CORS issues. See the Header Propagation section of the npm guide for the default exclusion list.

Network body capture​

AttributeTypeDefaultDescription
data-capture-streaming-response-bodybooleantrueCapture a limited prefix of streaming response bodies. Set to "false" to disable.
data-capture-response-body-max-mbnumber10Maximum response body size (MB) to capture.
data-capture-stream-prefix-kbnumber64Maximum prefix size (KB) to capture from streaming responses.
data-capture-stream-timeout-msnumber10000Timeout (ms) for streaming prefix capture.

Performance​

AttributeTypeDefaultDescription
data-defer-recordingbooleantrueDefer heavy DOM recording until after the page is interactive.
data-chunk-snapshotbooleanfalseBreak the initial full-DOM snapshot into async chunks.
data-use-ws-workerbooleanfalseRoute the WebSocket ingest through a Web Worker to keep it off the main thread.

Tracking​

AttributeTypeDefaultDescription
data-enable-fiber-trackingbooleantrueEnable React Fiber tracking — adds data-sf-source attributes to DOM elements. Has no effect if React isn't present.
data-enable-ip-trackingbooleanfalseFetch visitor IP in the background for session metadata.

Issue reporting​

AttributeTypeDefaultDescription
data-custom-base-urlstring—Custom base URL for the triage / report-issue interface.
data-show-eng-ticket-fields-in-report-issue-modal-defaultbooleanfalseShow engineering-ticket fields (stack trace, session ID, etc.) in the report-issue modal by default.

Advanced / internal​

AttributeTypeDefaultDescription
data-librarystring"JS/TS SNIPPET"Identifier telemetry uses to tag which integration sent the event. Leave as default unless you have a specific need to override.

Options only available via npm​

Two initRecorder options take structured-object values that HTML data-* attributes can't reasonably carry:

  • serviceAdditionalMetadata — a Record<string, any> of custom metadata merged onto every session.
  • reportIssueShortcuts — a Partial<ShortcutsConfig> controlling keyboard shortcuts for the report-issue modal.

If you need either of these, switch to the npm install path and call initRecorder({ ... }) directly. Everything else from the CDN snippet is equally available via npm.

Verifying the setup​

  1. Deploy your page with the <script> added.
  2. Load the page in a browser. Open devtools → Network and confirm the request to cdn.jsdelivr.net/npm/@sailfish-ai/recorder@<RecorderVersion /> returns 200.
  3. Open the Sailfish dashboard and trigger some activity on the page — you should see telemetry appearing within a few seconds.

Troubleshooting​

Script 404s on jsdelivr​

Double-check the version pin. @<RecorderVersion /> in the snippet above is substituted by the docs site to the current published version when you're signed in; if you copy the markdown source verbatim (unsubstituted), replace it with a concrete version from npm.

Script blocked by Content Security Policy (CSP)​

Allow cdn.jsdelivr.net in your script-src directive:

Content-Security-Policy: script-src 'self' https://cdn.jsdelivr.net;

If you use a strict nonce-based policy, add the nonce to the <script> tag: <script nonce="..." src="..." data-...></script>.

Tracing headers not appearing on cross-origin requests​

Browser CORS rules only allow the sailfish-trace header through if your server explicitly opts in via Access-Control-Allow-Headers: sailfish-trace. Add that header on the receiving service, or include it in the preflight response. The allowlist (data-domains-to-propagate-header-to) controls which domains the SDK attempts to add the header to — the browser's CORS layer has the final say.

Nothing appears in the Sailfish dashboard​

  1. Confirm data-api-key is set and the value is correct (or <ApiKey /> rendered to a real UUID for logged-in readers).
  2. Check the browser console for errors prefixed with Sailfish.
  3. Verify the script loads before the events you want to capture. If you load it late (e.g. deferred, lazy-loaded after user interaction), the SDK will miss everything prior.

Next steps​