Script Tag

Load the agent from the Faultsense CDN or self-host it. No build tools required.

CDN (recommended)

Add two tags to your <head>:

<script
  id="fs-agent"
  src="https://cdn.faultsense.com/v0/faultsense-agent.min.js"
  data-release-label="2.4.1"
  data-collector-url="https://collector.example.com/events"
  data-api-key="fs_secret_..."
  defer>
</script>

The single <script> tag both loads the agent and provides configuration via data attributes. The agent reads id="fs-agent" on DOMContentLoaded and auto-initializes.

Or load the script and call init() yourself:

<script src="https://cdn.faultsense.com/v0/faultsense-agent.min.js" defer></script>
<script>
  window.addEventListener('DOMContentLoaded', () => {
    Faultsense.init({
      releaseLabel: '2.4.1',
      collectorURL: 'https://collector.example.com/events',
      apiKey: 'fs_secret_...',
    });
  });
</script>

The /v0/ URL floats to the latest 0.x release automatically. Updates are cached at the edge and propagate within minutes of a new release.

Pin for production

Lock to an exact version so updates never surprise you:

<script src="https://cdn.faultsense.com/v0.5.0/faultsense-agent.min.js" defer></script>

Exact-version URLs are immutable — the response carries Cache-Control: public, max-age=31536000, immutable. Once a version ships, its bundle never changes.

Subresource Integrity (SRI)

If your security policy requires SRI, generate the hash from the pinned bundle:

curl -s https://cdn.faultsense.com/v0.5.0/faultsense-agent.min.js \
  | openssl dgst -sha384 -binary | openssl base64 -A

Then add it to the script tag:

<script
  src="https://cdn.faultsense.com/v0.5.0/faultsense-agent.min.js"
  integrity="sha384-<hash from above>"
  crossorigin="anonymous"
  defer>
</script>

SRI only works with pinned versions (/v0.5.0/), not the floating /v0/ URL — the hash changes when a new version ships.

Self-host

Download the bundle and serve it from your own origin:

curl -O https://cdn.faultsense.com/v0.5.0/faultsense-agent.min.js

Serve it from any path — /js/, /vendor/, /static/ — and reference it in the script tag:

<script src="/js/faultsense-agent.min.js" defer></script>

Self-hosting avoids third-party blocking (ad blockers, tracker lists, corporate proxies) and keeps the agent subject to the same TLS, caching, and access-log policies as the rest of your site.

Data attributes

When using the id="fs-agent" script tag, the agent reads configuration from data attributes:

See configuration for the full option reference.

Content Security Policy

Faultsense runs with a strict CSP. Two directives matter:

script-src 'self';
connect-src 'self' https://collector.example.com;

• script-src 'self' works when self-hosting. If loading from the CDN, add https://cdn.faultsense.com to script-src.
• connect-src must include the collector URL so fetch/sendBeacon calls are allowed.
• No inline scripts, no eval, no dynamic code evaluation in the agent.

Collectors

The agent needs a collector to receive assertion results. See collectors for how to add the panel or console collector alongside the agent script tag.

Verify

After loading the agent, add one instrumented element:

<button
  fs-assert="sanity/install-check"
  fs-trigger="click"
  fs-assert-added=".install-receipt">
  Click me
</button>
<div class="install-receipt" hidden></div>

Wire the click handler to unhide .install-receipt, click the button, and check your collector for a sanity/install-check event with status: pass.