CDN / Script Tag

Load the Encatch Web SDK from jsDelivr with a script tag — no build step required

The Encatch Web SDK (@encatch/web-sdk) can be loaded from jsDelivr as an IIFE bundle. Add one <script> tag to your HTML and use the global _encatch object — no npm install or bundler required.

This method suits static sites, marketing pages, documentation sites (for example Astro Starlight), and legacy apps where you cannot add npm dependencies.

How the loader works

The jsDelivr file is a loader stub, not the full SDK. When you call _encatch.init(), Encatch injects the remote implementation from https://form.encatch.com/s/sdk/v1/encatch.js (a module script). API calls go to https://api.encatch.com by default. Commands you send before that remote script finishes loading are queued and replayed automatically.

What you need from the Encatch dashboard

Before adding the script tag:

Publishable SDK key — In your Encatch project, go to Settings → Security → Publishable SDK Keys and click Create Publishable SDK Key. Copy the full key when shown — Encatch displays it only once at creation.
Allowed Domains / Packages — On the same key, add your site origin (for example https://app.example.com). Up to 10 entries per key. Avoid * in production.
Form slug or UUID — Open your feedback form in the dashboard, go to Triggers → Manual Trigger, and copy the Form Slug or Feedback Configuration UUID for showForm().

See Publishable SDK Keys and Form Builder for details.

Add the script tag

Pin the CDN version to the @encatch/web-sdk release you intend to use. Add the loader in your HTML <head> or before the closing </body> tag:

<script src="https://cdn.jsdelivr.net/npm/@encatch/web-sdk@1.4.0/dist/encatch.iife.js"></script>

The IIFE build registers _encatch on window (Vite library name _encatch, output file dist/encatch.iife.js).

Version pinning

Always pin a specific version in the URL (for example @1.4.0) rather than @latest, so production sites do not pick up breaking changes unexpectedly. The jsdelivr field in @encatch/web-sdk points to dist/encatch.iife.js.

Initialize the client

After the loader script tag, call init() with your publishable SDK key:

<script src="https://cdn.jsdelivr.net/npm/@encatch/web-sdk@1.4.0/dist/encatch.iife.js"></script>
<script>
  _encatch.init('your-publishable-sdk-key');
  _encatch.startSession();
  _encatch.showForm('your-form-slug-or-uuid');
</script>

Replace 'your-publishable-sdk-key' with the key from Settings → Security → Publishable SDK Keys.

Replace 'your-form-slug-or-uuid' with either:

Form Slug — 15–100 characters, lowercase letters, digits, hyphens, and underscores; must start with a letter (configured under Triggers → Manual Trigger in the dashboard), or
Feedback Configuration UUID — the read-only UUID on the same Manual Trigger screen

Only the first init() call runs — Encatch logs [Encatch] SDK already initialized. Ignoring init call. if init() is called again. After a successful identifyUser(), Encatch starts a session automatically; you do not need startSession() before identify.

You may call _encatch methods immediately after the loader script; calls made before the remote script from form.encatch.com loads stay in the internal queue until the implementation is ready.

Optional configuration

Pass a config object as the second argument to init():

<script>
  _encatch.init('your-publishable-sdk-key', {
    theme: 'system',
    debugMode: false,
    onBeforeShowForm: async (payload) => {
      // Return false to skip the built-in modal iframe
      return true;
    },
  });
</script>

Option	Default	Description
`webHost`	`https://form.encatch.com`	Host that serves `/s/sdk/v1/encatch.js` and form iframes
`apiBaseUrl`	`https://api.encatch.com`	Base URL for Encatch API requests
`theme`	`'system'`	Form theme: `'light'`, `'dark'`, or `'system'`
`debugMode`	`false`	Log SDK diagnostic messages to the console
`onBeforeShowForm`	—	Return `false` to block the built-in iframe and use a custom UI

Override webHost or apiBaseUrl only for non-production Encatch environments (for example dev or UAT). See Initialization in the client reference.

Identify users

Encatch uses identified users for in-app targeting, segments, and response attribution. Call identifyUser after init():

<script>
  _encatch.identifyUser('user@example.com', {
    $set: { name: 'Alice', plan: 'team' },
  });
</script>

userName must be an ASCII identifier (1–50 characters: letters, digits, ., _, @, -). Email addresses and internal user IDs work when they match this format.

For $set, $setOnce, $increment, secure HMAC signatures (optional Secret key on the publishable SDK key), and full username rules, see Identify users.

Content Security Policy

If your site sends CSP headers, allow both the jsDelivr loader and Encatch hosts. After init(), Encatch loads a module script from form.encatch.com and opens form iframes on the same host:

Content-Security-Policy:
  script-src 'self' https://form.encatch.com https://cdn.jsdelivr.net;
  connect-src 'self' https://api.encatch.com;
  frame-src 'self' https://form.encatch.com;

If you set custom webHost or apiBaseUrl in init(), whitelist those hosts in script-src / frame-src and connect-src respectively.

See the full Content Security Policy section in the client reference.

Next steps

Once installation and initialization are working, explore the full client API in the Client Reference — automatic triggers, form events, pre-fill (addToResponse), source tracking, and session control.