NPM Package

The official @encatch/web-sdk npm package is the recommended way to integrate Encatch in React, Vue, Next.js, Astro, and other apps with a JavaScript build step. Install the package, import _encatch, and call init() with your publishable SDK key.

The npm package ships the ES module loader (dist/encatch.es.js) and TypeScript types (dist/index.d.ts). Like the CDN loader, it is a stub — when you call _encatch.init(), Encatch injects the remote implementation from https://form.encatch.com/s/sdk/v1/encatch.js. API calls go to https://api.encatch.com by default. Commands sent before that remote script finishes loading are queued and replayed automatically.

What you need from the Encatch dashboard

Before installing the package:

1. 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.
2. 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.
3. 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.

Install the package

Navigate to your project root and install with your preferred package manager:

npm install @encatch/web-sdk

yarn add @encatch/web-sdk

pnpm add @encatch/web-sdk

The package exposes the ES module entry as "import": "./dist/encatch.es.js" and TypeScript definitions at dist/index.d.ts. Re-exported types include EncatchConfig, UserTraits, IdentifyOptions, Theme, ShowFormOptions, and event payload types.

Initialize the client

Import _encatch and call init() with your publishable SDK key as early as possible on the client (browser) side:

import { _encatch } from '@encatch/web-sdk';

_encatch.init('your-publishable-sdk-key');
_encatch.startSession();
_encatch.showForm('your-form-slug-or-uuid');

You can also use the default export:

import _encatch from '@encatch/web-sdk';

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 init(); 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():

import { _encatch } from '@encatch/web-sdk';

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

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

Next.js

Load and initialize the SDK on the client only. The Encatch loader relies on window and document, which are not available during server-side rendering.

'use client';

import { useEffect } from 'react';
import { _encatch } from '@encatch/web-sdk';

export default function EncatchProvider({ children }) {
  useEffect(() => {
    _encatch.init('your-publishable-sdk-key', { theme: 'system' });
    _encatch.startSession();
  }, []);

  return children;
}

Mount this provider once at your app root (similar to how the Encatch admin app wraps the tree in EncatchSdkRoot). Alternatively, use next/dynamic with { ssr: false } for components that import @encatch/web-sdk directly.

Vue.js

Import the package in a client-only lifecycle hook so init() never runs during SSR:

import { _encatch } from '@encatch/web-sdk';

export default {
  name: 'YourVueComponent',
  mounted() {
    _encatch.init('your-publishable-sdk-key');
    _encatch.startSession();
  },
};

For Vue 3 Composition API, call init() inside onMounted().

Astro / Starlight

For documentation sites, see the full Astro Starlight guide — it installs @encatch/web-sdk and initializes the SDK in a React island with PUBLIC_ENCATCH_SDK_PUBLISHABLE_KEY.

Identify users

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

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

userName must be an ASCII identifier (1–50 characters: letters, digits, ., _, @, -). Email addresses and internal user IDs work when they match this format. The Encatch admin app identifies signed-in users with their internal user ID and sets $set: { email, name }.

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

When you install via npm, you do not need jsDelivr in CSP — the loader is bundled in your app. After init(), Encatch still loads a module script from form.encatch.com and opens form iframes on that host:

Content-Security-Policy:
  script-src 'self' https://form.encatch.com;
  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.