Installation

Before you can collect in-app feedback with Encatch, install the Encatch Web SDK (@encatch/web-sdk) on your site once. After that, create and configure feedback forms, targeting rules, and automatic triggers in the Encatch dashboard without redeploying your app.

What you need from the Encatch dashboard

Locate your publishable SDK key

In the Encatch dashboard (route: Settings → Security → Publishable SDK Keys):

1. Open your Encatch project.
2. Click Create Publishable SDK Key (or select an existing key under the Active keys tab).
3. Fill in Basic Information — Key Name and Application Name / Identifier (each max 25 characters).
4. Expand Access Configuration — set Expiry Period and Allowed Domains / Packages (required).
5. Optionally expand Security Configuration — Secret Key (server-side only, for HMAC identifyUser signatures) and Session time (minutes).

Copy Your Publishable SDK Key on the confirmation step, then click Close. See Publishable SDK Keys.

Pass the key to _encatch.init('your-publishable-sdk-key'). Only the first init() call runs — Encatch logs [Encatch] SDK already initialized. Ignoring init call. on duplicate calls.

Installation options

Encatch supports two ways to load @encatch/web-sdk:

Both methods expose the same _encatch API — modal form iframes, user identification, trackScreen / trackEvent, session management, and source tracking.

Complete setup in one of the method guides below, then use the sections on this page for identify, launch, and troubleshooting.

Minimal init (either method)

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

Form Slug (from Triggers → Manual Trigger) must be 15–100 characters, start with a lowercase letter, and use only a–z, 0–9, -, and _. Alternatively pass the Feedback Configuration UUID from the same screen.

After a successful identifyUser(), Encatch calls startSession() internally — you do not need startSession() before identify.

Identify users

Encatch uses identified users for in-app targeting, manual segments, user traits, and response attribution.

Call identifyUser after init():

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

userName must match Encatch server validation: 1–50 characters, only letters, digits, and ., _, @, -. The Encatch admin app uses the signed-in user's internal ID as userName and $set: { email, name } for traits.

On success, Encatch stores the user pair in localStorage and starts a session automatically. Method-specific examples:

• Identify users with CDN / Script Tag
• Identify users with NPM Package

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

Launch feedback forms

Manual launch — showForm() with the slug or UUID from Triggers → Manual Trigger:

_encatch.showForm('your-form-slug-or-uuid');
_encatch.showForm('your-form-slug-or-uuid', {
  reset: 'always',
  context: { plan: 'team', feature: 'checkout' },
});

Automatic launch — enable an Automatic Trigger in the dashboard. The SDK evaluates launch rules (page visit, tracked event, delay, and more) without a manual showForm() call.

Subscribe to lifecycle events with _encatch.on() — for example form:show, form:submit, form:complete, form:ctaTriggered. See Client Reference for all event types.

Track pages and events

_encatch.trackScreen('Dashboard');
_encatch.trackEvent('checkout_completed');

Both calls are no-ops until a device id exists — establish one with startSession() or a successful identifyUser() first. With an active session, SPA navigations (pushState, replaceState, popstate) also trigger trackScreen with the full page URL.

Merge UTM and campaign params with addSourceTracking() before showForm() — see source tracking.

Troubleshoot installation

If Encatch forms do not appear or API calls fail:

1. Publishable key — Value in init() must match an Active key (Settings → Security → Publishable SDK Keys → Active keys tab). Check the key is not Expired, Deleted, or Inactive (shown in Info and Actions on the key row).
2. Allowed Domains / Packages — Page origin must match an entry on that key (for example https://your-app.com). Avoid * in production.
3. Form published — Publish the feedback form in the dashboard before testing. Slug must pass validation (15–100 chars, rules above) or use the configuration UUID.
4. Client-side only — Call init() in the browser after window is available (not during SSR). See NPM Package — Next.js.
5. Init timing — Call init() early. Encatch queues calls until form.encatch.com/s/sdk/v1/encatch.js loads.
6. Content Security Policy — Allow form.encatch.com and api.encatch.com; add cdn.jsdelivr.net only for CDN / Script Tag. See Content Security Policy.
7. Session stopped — After stopSession(), call startSession() or identifyUser() again. stopSession() persists across reloads until you restart tracking.
8. Silent tracking — trackEvent / trackScreen do nothing (no error) if no device id exists yet — call startSession() or identifyUser() first.

Step-by-step setup: CDN / Script Tag · NPM Package

Rate limits

When using the Encatch Web SDK to track user data and collect feedback responses, these limits apply to production projects:

Sandbox projects use 50 / 10 / 50 per minute (project / contact / IP). Encatch returns 429 Too Many Requests when exceeded, with X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset on API responses. See SDK Rate Limits.

Next steps

• Client Reference — full _encatch API (addToResponse, themes, session control, custom form UX)
• CDN / Script Tag · NPM Package — detailed install and init
• Build a feedback form
• Automatic Trigger — launch forms from dashboard rules without code changes