{/* Helpful question + Yes/No pills */}
{/* Suggest edits + Raise issue buttons */}
);
}
```
Copy the complete component from the [example repo](https://github.com/get-encatch/astro-starlight-examples/blob/main/src/components/DocsPageFeedback.tsx).
***
## Step 5: Override Starlight components [#step-5-override-starlight-components]
### PageFrame — initialize the SDK [#pageframe--initialize-the-sdk]
`src/components/EncatchPageFrame.astro` wraps the default frame and mounts `EncatchInit` as a client island:
```astro
---
import Default from '@astrojs/starlight/components/PageFrame.astro';
import { EncatchInit } from './EncatchInit';
const locale = Astro.currentLocale ?? 'en';
---
` (optionally `data-encatch-form-id="your-form-slug-or-uuid"`). Falls back to modal when no host matches at show time.
```javascript
_encatch.showForm('customer-satisfaction-survey-2024', { selector: '#feedback-slot' });
```
`isFullScreen` and inline placement are mutually exclusive.
In **full-screen mode**, `trackEvent()`, `trackScreen()`, and background ping are disabled — use modal or inline placement when you need session tracking or automatic triggers.
***
## Other actions [#other-actions]
### Locale [#locale]
Set the user's preferred language as comma-separated ISO 639-1 codes. Call before `identifyUser()` when possible.
```javascript
_encatch.setLocale('fr');
_encatch.setLocale('fr,en,es');
```
Or pass `locale` in `identifyUser` options:
```javascript
_encatch.identifyUser('user@example.com', undefined, { locale: 'fr' });
```
### Country [#country]
Set a two-letter ISO 3166 country code for country targeting.
```javascript
_encatch.setCountry('FR');
```
Or pass `country` in `identifyUser` options:
```javascript
_encatch.identifyUser('user@example.com', undefined, { country: 'FR' });
```
### Theme [#theme]
Override the theme set at `init()`:
```javascript
_encatch.setTheme('dark'); // 'light' | 'dark' | 'system'
```
### Track events [#track-events]
Track custom events for [automatic triggers](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger). Requires a device id from `startSession()` or successful `identifyUser()` — otherwise the call is a no-op.
```javascript
_encatch.trackEvent('button_clicked');
```
Encatch records event occurrence only — attributes cannot be attached to events.
### Track screens [#track-screens]
Track page or screen views. With an active session, SPA navigations (`pushState`, `replaceState`, `popstate`) call `trackScreen` with the full page URL automatically.
```javascript
_encatch.trackScreen('Dashboard');
```
Requires a device id from `startSession()` or successful `identifyUser()` — otherwise the call is a no-op.
### Source tracking [#source-tracking]
Merge UTM or campaign params into the in-memory source tracking store (web SDK only). Values override URL query params on key collision. Persists for the page session.
```javascript
_encatch.addSourceTracking({ utm_campaign: 'spring-sale' });
_encatch.showForm('customer-satisfaction-survey-2024');
```
On each `showForm()`, Encatch merges URL query params with `addSourceTracking()` values. Filtered keys are auto-injected into `submitForm` for custom UIs.
### Listen to form events [#listen-to-form-events]
Subscribe with `_encatch.on()`. Returns an unsubscribe function.
```javascript
const unsubscribe = _encatch.on((eventType, payload) => {
console.log(eventType, payload.formId, payload.data);
});
unsubscribe();
```
| Event | When it fires |
| --------------------- | -------------------------------------------- |
| `form:show` | Form displayed |
| `form:started` | User starts interacting |
| `form:submit` | Form submitted |
| `form:complete` | Form fully completed |
| `form:close` | Form closed |
| `form:dismissed` | Dismissed without completion |
| `form:error` | Error occurred |
| `form:section:change` | Section changed |
| `form:answered` | Question answered |
| `form:remindmelater` | "Remind me later" tapped (hides iframe only) |
| `form:ctaTriggered` | Completion CTA on thank-you or exit screen |
For `form:ctaTriggered`, handle `app_navigate` in your app — the SDK closes the form after emitting the event. `redirect_internal` and `redirect_external` are handled by the SDK. See [Call to action](/docs/feedback-management/form-builder/call-to-action).
```javascript
_encatch.on((eventType, payload) => {
if (eventType !== 'form:ctaTriggered') return;
if (payload.data?.action === 'app_navigate') {
router.push(payload.data.route);
}
});
```
### Pre-fill responses [#pre-fill-responses]
Stage answers with `addToResponse()` before `showForm()`. Pass the question UUID or slug and the raw answer value (pass `5` for a rating, not `{ rating: 5 }`).
```javascript
_encatch.addToResponse('email_question', 'user@example.com');
_encatch.addToResponse('nps_question', 10);
_encatch.showForm('customer-satisfaction-survey-2024');
```
Staged values apply on the next `showForm()`, or immediately if a form iframe is already open. Works for **22 of 27** question types — use option **Value** / data identifier from the form builder, not the label. Test in the builder via [logic jumps](/docs/feedback-management/form-builder/logic-jumps#test-logic-jumps).
Not supported: signature, file upload, video/audio/photo, scheduler, Q\&A with AI.
### Dismiss form [#dismiss-form]
Close the visible form and report dismissal to the Encatch API.
```javascript
_encatch.dismissForm();
_encatch.dismissForm('feedback-configuration-uuid');
```
Safe to call when no form is visible — it has no effect.
### Form interceptor [#form-interceptor]
Return `false` from `onBeforeShowForm` to block the built-in iframe and render your own UI. Staged `addToResponse()` values are cleared when `false` is returned.
```javascript
_encatch.init('your-publishable-sdk-key', {
onBeforeShowForm: async (payload) => {
// payload.formId, payload.formConfig, payload.triggerType,
// payload.resetMode, payload.prefillResponses, payload.context
if (payload.triggerType === 'automatic' && shouldBlock) return false;
return true;
},
});
```
| Payload field | Description |
| ------------------ | ----------------------------------------- |
| `formId` | Form slug or Feedback Configuration UUID |
| `formConfig` | Show-form API response |
| `triggerType` | `'manual'` or `'automatic'` |
| `resetMode` | `'always'`, `'on-complete'`, or `'never'` |
| `prefillResponses` | Values from `addToResponse()` |
| `context` | Serialized `showForm` context |
### Session [#session]
Control the session lifecycle. Session ids use a **24-hour rolling expiry**.
```javascript
_encatch.startSession();
_encatch.startSession({
skipImmediatePing: true, // skip first ping; 30s interval still runs
skipImmediateTrackScreen: true, // skip initial trackScreen (default: true)
});
```
```javascript
_encatch.pauseSession(); // pause background ping (not persisted)
_encatch.resumeSession(); // resume ping
_encatch.stopSession(); // stop ping, URL listeners, dismiss open forms (persists across reloads)
_encatch.clearAll(); // wipe all persisted SDK data and reset in-memory state
```
| Method | Effect |
| ------------------------------------ | --------------------------------------------------------------------------------------------------- |
| `startSession()` | New session id; starts 30s ping interval and URL listeners |
| `pauseSession()` / `resumeSession()` | Temporarily pause/resume ping only |
| `stopSession()` | Full suspension; identity preserved; re-enable with `startSession()` |
| `resetUser()` | Clear user identity (use on logout) |
| `clearAll()` | Full reset — stronger than `resetUser()`; tracking stops until `startSession()` or `identifyUser()` |
The SDK pings every \~30 seconds to maintain sessions and check for triggered forms. Ping is suppressed while a form is visible.
If a prior session or user exists in browser storage, Encatch restores identifiers on load and may restart the session unless it was explicitly stopped.
***
## Advanced options [#advanced-options]
### Build your own form UI [#build-your-own-form-ui]
For fixed, predictable question sets, build your own HTML/CSS/JS and submit via `submitForm()`, `emitEvent()`, `refineText()`, `uploadFile()`, and `qnaWithAi()`. Use `onBeforeShowForm` returning `false` to skip the built-in iframe.
### Content Security Policy [#content-security-policy]
Whitelist Encatch hosts in your CSP headers.
**NPM:**
```http
script-src 'self' https://form.encatch.com;
connect-src 'self' https://api.encatch.com;
frame-src 'self' https://form.encatch.com;
```
**CDN / script tag** — also allow `https://cdn.jsdelivr.net` in `script-src`.
If you set custom `webHost` or `apiBaseUrl`, whitelist those hosts instead.
***
## Troubleshooting [#troubleshooting]
Forms not appearing? API calls failing silently? See [Troubleshoot](/docs/sdk-reference/web/troubleshoot) for debug mode, console diagnostics, and step-by-step fixes.
***
## API quick reference [#api-quick-reference]
| Method | Description |
| ------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `init(apiKey, config?)` | Initialize with publishable SDK key |
| `identifyUser(userName, traits?, options?)` | Identify a user |
| `setLocale(locale)` | Set locale (ISO 639-1, comma-separated) |
| `setCountry(country)` | Set country (ISO 3166) |
| `setTheme(theme)` | Set form theme |
| `trackEvent(eventName)` | Track a custom event |
| `trackScreen(screenName)` | Track screen navigation |
| `showForm(formId, options?)` | Show a form (modal, inline, or full-screen) |
| `dismissForm(formConfigurationId?)` | Dismiss the current form |
| `addToResponse(questionId, value)` | Pre-fill a question (22 of 27 types) |
| `addSourceTracking(values)` | Merge source tracking params |
| `startSession(options?)` | Start a new session |
| `pauseSession()` | Pause background ping |
| `resumeSession()` | Resume background ping |
| `stopSession()` | Suspend SDK activity |
| `resetUser()` | Reset user identity |
| `clearAll()` | Wipe all persisted SDK data |
| `on(callback)` | Subscribe to lifecycle events |
| `init(..., { debugMode: true })` | Enable console diagnostic logs — see [Troubleshoot](/docs/sdk-reference/web/troubleshoot) |
| `submitForm(params)` | Submit a custom form |
| `emitEvent(eventType, payload)` | Emit a lifecycle event (custom UI) |
| `refineText(params)` | AI text refinement |
| `uploadFile(params)` | Upload a file (custom forms) |
| `qnaWithAi(params)` | Q\&A with AI |
| `streamQnaWithAi(params, callbacks)` | Streaming Q\&A with AI |
# Installation (/docs/sdk-reference/web/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](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger) in the Encatch dashboard without redeploying your app.
Publishable SDK keys are designed for client-side use — protect them with **Allowed Domains / Packages**. The optional **Secret Key** for HMAC `identifyUser` signatures is server-side only; never ship it in browser code.
Both installation methods ship a **loader stub** (`dist/encatch.iife.js` from CDN or `dist/encatch.es.js` from npm). When you call `_encatch.init('your-publishable-sdk-key')`, Encatch injects the full implementation from `https://form.encatch.com/s/sdk/v1/encatch.js` as a module script. API requests go to `https://api.encatch.com` by default. Commands sent before that remote script finishes loading are **queued** in `_q` and replayed when the implementation loads.
***
## What you need from the Encatch dashboard [#what-you-need-from-the-encatch-dashboard]
1. **Publishable SDK key** — **Settings → Security → [Publishable SDK Keys](/docs/settings/security/publishable-sdk-keys)** → **Create Publishable SDK Key**. Copy **Your Publishable SDK Key** when shown — Encatch displays the full key only once at creation.
2. **Allowed Domains / Packages** — On that key, add your site origin (for example `https://app.example.com`). Up to **10** entries per key (each up to 100 characters). Avoid `*` in production.
3. **Form slug or UUID** — Open your feedback form → **Triggers → Manual Trigger**. Use the **Form Slug** or **Feedback Configuration UUID** in `showForm()`.
4. **Targeting (optional)** — Configure [in-app targeting](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback) and [triggers](/docs/feedback-management/targeting-and-triggers/triggers) for automatic launches.
### Locate your publishable SDK key [#locate-your-publishable-sdk-key]
In the Encatch dashboard (**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](/docs/settings/security/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 [#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](/docs/sdk-reference/web#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) [#minimal-init-either-method]
```javascript
_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 [#identify-users]
Encatch uses identified users for [in-app targeting](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback), [manual segments](/docs/segmentation/manual), [user traits](/docs/settings/user-data/user-traits), and response attribution.
Call `identifyUser` after `init()`:
```javascript
_encatch.identifyUser('user@example.com', {
$set: { name: 'Alice', plan: 'team' },
});
```
`userName` must match Encatch server validation: **1–50 characters**, only letters, digits, and `.`, `_`, `@`, `-`.
On success, Encatch starts a session automatically. Method-specific examples:
* [Identify users with CDN / Script Tag](/docs/sdk-reference/web/installation-methods/cdn-script-tag#identify-users)
* [Identify users with NPM Package](/docs/sdk-reference/web/installation-methods/npm-package#identify-users)
For `$set`, `$setOnce`, `$increment`, secure HMAC signatures (optional **Secret Key** on the publishable SDK key), and full rules, see [Identify & track users](/docs/sdk-reference/web#identify--track-users).
***
## Launch feedback forms [#launch-feedback-forms]
**Manual launch** — `showForm()` with the slug or UUID from **Triggers → Manual Trigger**:
```javascript
_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](/docs/feedback-management/targeting-and-triggers/triggers/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](/docs/sdk-reference/web) for all event types.
***
## Track pages and events [#track-pages-and-events]
```javascript
_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](/docs/sdk-reference/web#source-tracking).
***
## Troubleshoot installation [#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](/docs/sdk-reference/web/installation-methods/npm-package#nextjs).
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](/docs/sdk-reference/web/installation-methods/cdn-script-tag). See [Content Security Policy](/docs/sdk-reference/web#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](/docs/sdk-reference/web/installation-methods/cdn-script-tag) · [NPM Package](/docs/sdk-reference/web/installation-methods/npm-package)
***
## Rate limits [#rate-limits]
When using the **Encatch Web SDK** to track user data and collect feedback responses, these limits apply to **production** projects:
| Limit scope | Requests per minute |
| --------------------- | ------------------- |
| Per project | 40,000 |
| Per contact / user ID | 100 |
| Per IP address | 300 |
[Sandbox projects](/docs/sandbox-limits/rate-limits) 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](/docs/sandbox-limits/rate-limits).
***
## Next steps [#next-steps]
* [Client Reference](/docs/sdk-reference/web) — full `_encatch` API (`addToResponse`, themes, session control, custom form UX)
* [Troubleshoot](/docs/sdk-reference/web/troubleshoot) — debug mode, console logs, and common fixes when forms do not appear
* [CDN / Script Tag](/docs/sdk-reference/web/installation-methods/cdn-script-tag) · [NPM Package](/docs/sdk-reference/web/installation-methods/npm-package) — detailed install and init
* [Build a feedback form](/docs/feedback-management/form-builder/build-feedback-form)
* [Automatic Trigger](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger) — launch forms from dashboard rules without code changes
# Troubleshoot (/docs/sdk-reference/web/troubleshoot)
The Encatch Web SDK includes a built-in **Debug Mode** to help you track down installation, targeting, and form-display issues. When activated, the SDK writes diagnostic messages to your browser console so you can see whether the client loaded, whether users are identified, and whether API calls succeed.
For publishable key, allowed domains, CSP, and init timing, see [Troubleshoot installation](/docs/sdk-reference/web/installation#troubleshoot-installation).
Enable `debugMode` only in local or staging environments — console output can include SDK and user state. When sharing logs with support, redact `X-Api-Key` and `X-User-Signature` from Network screenshots. The optional **Secret Key** on a publishable SDK key is for server-side HMAC only — never ship it in client code.
***
## Debug Mode [#debug-mode]
When Debug Mode is on, Encatch emits extra `console.warn` messages prefixed with `[Encatch]`, `[IFRAME-MANAGER]`, `[EVENT-HANDLER]`, or `[Encatch API]`. Use these logs together with the checks in [Debug Panel](#debug-panel) below to confirm your installation is healthy.
Encatch does **not** show a floating on-page debug overlay. Inspect state in DevTools and subscribe to form events with `_encatch.on()` instead.
### Activate Debug Mode [#activate-debug-mode]
The simplest way to enable Debug Mode is to pass `debugMode: true` when you call `init()`:
```javascript
import { _encatch } from '@encatch/web-sdk';
_encatch.init('your-publishable-sdk-key', {
debugMode: true,
});
```
CDN / script tag:
```html
```
You can also enable Debug Mode from the browser console **after** `init()` has run on the current page:
```javascript
window._encatch._config.debugMode = true;
```
Debug Mode stays active for the rest of that **page session** (until you reload or close the tab). It is useful while debugging SPA navigation or [automatic triggers](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger) on the same page. After a full page reload, pass `debugMode: true` in `init()` again — a console toggle does not persist across reloads.
To disable Debug Mode on the current page:
```javascript
window._encatch._config.debugMode = false;
```
Or pass `debugMode: false` (the default) on your **first** `init()` call when the page loads. A second `init()` is ignored — Encatch logs `[Encatch] SDK already initialized. Ignoring init call.` and does not change config.
Unlike some other SDKs, Encatch does not support a `?debug=true` URL flag. Pass `debugMode: true` in `init()` or toggle `window._encatch._config.debugMode` in the console.
### Debug Panel [#debug-panel]
Encatch does not render a visual debug panel in the corner of the browser. Use the following DevTools checks as your debug panel — they tell you whether the client installed correctly, whether you are identifying users, and whether the remote SDK loaded.
**1. Confirm the SDK is on the page**
```javascript
typeof window._encatch
// Expected: "object"
```
**2. Confirm `init()` ran**
```javascript
window._encatch._initialized
// Expected: true
```
**3. Check identification mode**
```javascript
localStorage.getItem('encatch_user_name')
// null → anonymous (Visitors targeting)
// non-null string → identified after a successful identifyUser() (Logged-in Users targeting)
```
**4. Subscribe to form lifecycle events**
```javascript
const off = _encatch.on((eventType, payload) => {
console.log('[Encatch event]', eventType, payload);
});
// Later: off();
```
**5. Confirm the remote SDK script loaded**
After `init()`, Encatch injects `https://form.encatch.com/s/sdk/v1/encatch.js`. In **Network**, filter for `encatch.js` and confirm status **200**.
If checks 1–2 pass but no requests reach `api.encatch.com`, reload the page and try again. If it still fails, see [Debug Tip #1](#debug-tip-1-check-if-sdk-is-loaded) below.
### Debug Logs [#debug-logs]
In addition to the checks above, enabling Debug Mode generates detailed logs in the browser console.
Open **Developer Tools → Console**:
| Browser | Windows / Linux | macOS |
| ------------- | ------------------ | ---------------- |
| Chrome / Edge | `Ctrl + Shift + J` | `Option + ⌘ + J` |
| Firefox | `Ctrl + Shift + K` | `Option + ⌘ + K` |
Filter by `Encatch` to narrow results.
**What Debug Mode logs**
| Prefix | Typical topics |
| ------------------ | ---------------------------------------------------- |
| `[Encatch]` | Selectors, localStorage, session restore, API errors |
| `[IFRAME-MANAGER]` | Form iframe messaging and visibility |
| `[EVENT-HANDLER]` | Form iframe postMessage handling |
| `[Encatch API]` | User ID persistence |
**Messages that can appear even when Debug Mode is off**
| Message | When |
| -------------------------------------------------------- | ----------------------------------------- |
| `[Encatch] SDK already initialized. Ignoring init call.` | Second `init()` call (loader stub) |
| `[Encatch] Failed to initialize SDK:` | Loader stub when remote script load fails |
| `[Encatch] Failed to load SDK from …` | Script `onerror` in the loader |
| `[SDK] showForm requires a formId` | `showForm()` called without an ID |
| `[SDK] show-form API error:` | Show-form request failed |
When contacting support, a screenshot of the Console and Network tabs is helpful — redact `X-Api-Key` and any signature headers first.
***
## Troubleshooting Tips [#troubleshooting-tips]
### Debug Tip #1: Check if SDK is loaded [#debug-tip-1-check-if-sdk-is-loaded]
If forms do not appear and you see no Encatch logs, the client was most likely not loaded into your page.
Open the **Elements** tab in Developer Tools and search for `encatch`. With the [CDN / Script Tag](/docs/sdk-reference/web/installation-methods/cdn-script-tag) method you should see a jsDelivr script tag. With the [NPM Package](/docs/sdk-reference/web/installation-methods/npm-package) method, the stub is bundled into your app JavaScript.
In the **Console**, confirm:
```javascript
window._encatch?._initialized === true
```
If this is `false` or `window._encatch` is `undefined`, verify your install steps and that `init()` runs in the browser — not during server-side rendering.
***
### Debug Tip #2: Test with a newly opened Incognito Window [#debug-tip-2-test-with-a-newly-opened-incognito-window]
The Encatch Web SDK uses **localStorage** to persist device IDs, session state, and user identity between page loads. That cached state can affect whether a form shows again after you change targeting or throttling in the dashboard.
Always test Encatch in a **newly opened Incognito / Private window** when debugging targeting or throttling. Alternatively, call `_encatch.clearAll()` in the console (see [Debug Tip #4](#debug-tip-4-reset-user-data-in-your-account-to-start-over)).
***
### Debug Tip #3: Check if you are using the audience type [#debug-tip-3-check-if-you-are-using-the-audience-type]
The Web SDK runs in one of two modes:
| Mode | How it is set | Dashboard targeting |
| -------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Anonymous** | No `encatch_user_name` in localStorage (or after `resetUser()`) | Enable [Visitors](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/visitors) |
| **Identified** | Successful `identifyUser()` stores `encatch_user_name` | Enable [Logged-in Users](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/logged-in-users) (and optional [segments](/docs/segmentation/overview)) |
When you can identify your users in code, **Logged-in Users** is the right audience choice.
When you cannot identify users — for example on a marketing site — enable **Visitors**.
Check your current mode in the console:
```javascript
localStorage.getItem('encatch_user_name')
```
Also review [country](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/country), [device type](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/device-type), [user language](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/user-language), and [past interaction](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/past-interaction) — any of these can prevent a form from launching.
***
### Debug Tip #4: Reset user data in your account to start over [#debug-tip-4-reset-user-data-in-your-account-to-start-over]
You will often want to test a feedback form again after you already completed or dismissed it. Dashboard rules such as [throttling](/docs/feedback-management/advanced-options/throttling), [response limit](/docs/feedback-management/advanced-options/response-limit), and [past interaction](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/past-interaction) can block repeat views.
You have two ways to start with a blank slate:
**1. Reset in the browser (fastest for local testing)**
```javascript
_encatch.clearAll();
```
This wipes persisted SDK data and stops background ping. Call `startSession()` or `identifyUser()` before testing [automatic triggers](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger) again.
For logout flows — clear identity but keep the device:
```javascript
_encatch.resetUser();
```
**2. Reset in the Encatch dashboard**
* Remove or filter out test responses in **Reports** for that form, or
* Relax throttling and past-interaction rules while testing.
In both cases, open a **new Incognito window** for further testing so no old browser state remains.
***
### Debug Tip #5: Inspect network tab [#debug-tip-5-inspect-network-tab]
Use Developer Tools → **Network** to inspect communication between your browser and Encatch servers.
Set the filter to **Fetch/XHR** and search for `encatch` or `api.encatch.com`. You should see requests such as:
| Request | When it fires |
| --------------- | -------------------------------------------------------------------------- |
| `identify-user` | After `identifyUser()` |
| `track-screen` | After `trackScreen()`, or on SPA navigation when a session is active |
| `track-event` | After `trackEvent()` |
| `ping` | After `startSession()` or successful `identifyUser()` (\~every 30 seconds) |
| `show-form` | When a form is displayed |
| `dismiss-form` | When a form is dismissed |
The remote SDK script loads separately as a module script (not XHR): `https://form.encatch.com/s/sdk/v1/encatch.js` after `init()`.
Successful responses return **200** or **201**. Encatch returns **429** when [rate limits](/docs/sandbox-limits/rate-limits) are exceeded.
If any request returns a **4xx** or **5xx** error, click it and read the response body. For key, domain, session, and CSP issues, work through [Troubleshoot installation](/docs/sdk-reference/web/installation#troubleshoot-installation).
`trackEvent()` and `trackScreen()` send **no request** until a device ID exists — call `startSession()` or `identifyUser()` first. This is expected behavior.
When contacting support, capture the status code and response body. Redact `X-Api-Key` and signature headers before sharing.
***
## Related [#related]
* [Installation — Troubleshoot installation](/docs/sdk-reference/web/installation#troubleshoot-installation)
* [Client Reference](/docs/sdk-reference/web) — `clearAll()`, `resetUser()`, session control, event subscriptions
* [Content Security Policy](/docs/sdk-reference/web#content-security-policy)
* [Targeting](/docs/feedback-management/targeting-and-triggers/targeting)
# AI Topics (/docs/settings/global-settings/ai-topics)
**AI Topics** helps you organize open-text feedback across your project. You set up **groups** and **topics** here—the AI handles the rest. When people leave written answers, it finds **aspects** (specific things they mention), maps them to your setup, and uses that for sentiment, summary reports, and Feedback Studio.
## Where to find it [#where-to-find-it]
1. Open your project in the encatch dashboard.
2. Go to **Settings**.
3. Under **Global Settings**, open **AI Topics**.
Don't see **AI Topics**? Ask your organization admin—you might need access, or the feature may not be turned on for your environment yet.
**Page description:** Create groups, organize topics, and control which group each topic belongs to. Aspects are managed automatically by the system.
## How it fits together [#how-it-fits-together]
Think of AI Topics in three layers:
| Level | Who sets it up | What it's for |
| ---------- | -------------- | ------------------------------------------------------------------------------ |
| **Group** | You | Big themes—like Product, Support, or Billing. |
| **Topic** | You | Smaller themes inside a group—like Checkout or Onboarding. |
| **Aspect** | AI | Specific things people actually say—like "slow loading" or "confusing layout". |
You only manage groups and topics on this page. Aspects show up on their own when the AI reads responses—you don't create or edit them here.
## What you'll see on the page [#what-youll-see-on-the-page]
Groups are listed in expandable sections. Each header shows the group name and how many topics are inside.
* **Group** — Add a new top-level group.
* **+** (on a group row) — Add a topic to that group.
* **Pencil** (on a group or topic) — Edit the name or description.
If you haven't created anything yet, you'll see **No groups yet** and a **Create group** button to get started.
### Uncategorized [#uncategorized]
**Uncategorized** is a built-in group for topics that aren't in a custom group yet. New topics with no group land here, and topics you move out of a group end up here too. Drag them into the right group whenever you're ready—or leave them here if that works for you.
## Create or edit a group [#create-or-edit-a-group]
1. Click **Group**, the **+** on a group row, or **Create group** if you're starting from scratch.
2. Fill in the dialog:
* **Name** (required) — What you want to call this group.
* **Description** (optional) — A short note about what belongs here. It shows under the group name and helps the AI sort responses into the right place.
3. Click **Save**.
## Create or edit a topic [#create-or-edit-a-topic]
1. Click **+** on the group where the topic should go (including **Uncategorized**).
2. In the **Add topic** dialog:
* **Name** (required) — What you want to call this topic.
* **Description** (optional) — Shows under the topic on each card. You can write up to **8,000** characters.
3. Click **Save**.
When responses are analyzed, the AI attaches aspects to your topics automatically.
## Move topics between groups [#move-topics-between-groups]
Grab a topic by the handle on the left and drag it to another group. You can drop it on other topics or on an empty area that says **Drop topics here**.
After you move things around, a bar appears at the bottom:
* **Discard** — Undo your moves and go back to the last saved layout.
* **Save changes** — Keep the new arrangement.
Names and descriptions save right away when you edit them in a dialog. Only drag-and-drop moves need **Save changes**.
## User and AI badges [#user-and-ai-badges]
Some topics show a small badge for how they were created:
| Badge | Meaning |
| -------- | ------------------------------------------------ |
| **User** | Someone on your team added it. |
| **AI** | The system created it while analyzing responses. |
Either way, you can rename topics and move them between groups like any other.
## Where your setup shows up [#where-your-setup-shows-up]
Once groups and topics are in place, they feed into AI analysis across the project.
### AI text insights on text questions [#ai-text-insights-on-text-questions]
In the form builder, turn on **AI text insights** for **long answer** or **short answer** questions. The summary report then includes:
* **Aspects & sentiment** — Maps answers to your AI Topics. Each aspect gets a sentiment score and a salience score (basically, how much that aspect stands out). Salience also affects overall sentiment in summaries and per-response views.
* **Word cloud** — A quick view of the words that come up most often.
You can optionally pick **Groups** on the question to limit aspects & sentiment to certain groups only. Those groups are the ones you set up here.
Each time analysis runs, it uses **1 AI Credit**.
### Feedback Studio [#feedback-studio]
Open **Feedback Studio → AI Topic intelligence** to browse groups, topics, and aspects for the whole project—how often they're mentioned, how people feel, and the responses behind them.
### Summary report [#summary-report]
Each text question's summary uses the same setup, filtered by your date range and any group filters on that question.
## Who can use this [#who-can-use-this]
What you can do depends on your role. Some people can view groups and topics only; others can create, edit, and move them.
If AI Topics isn't enabled in your environment, the page shows **Feature unavailable** instead of the settings.
## Tips [#tips]
* Start small—pick a few groups that match how your team already talks about feedback (product areas, journeys, teams).
* Add descriptions where you can. They really help the AI place free-text answers in the right spot.
* Check **Uncategorized** now and then and drag stray topics where they belong.
* On text questions, leave **Groups** empty to use everything, or tick specific groups to narrow the analysis.
## Best practices [#best-practices]
* Use clear, consistent names so reports and Feedback Studio are easy to scan.
* Try not to duplicate the same theme in multiple groups—it splits your numbers.
* If you've moved topics around, hit **Save changes** before you leave the page.
# Experiments (/docs/settings/global-settings/experiments)
**Experiments** let you define A/B/N rollout groups for your project. Each experiment has variants with named percentile ranges so you can control how users are bucketed—for example a control group and one or more test groups.
## Where to find it [#where-to-find-it]
1. Open your project in the encatch dashboard.
2. Go to **Settings**.
3. Under **Global Settings**, open **Experiments**.
If you do not see **Experiments**, contact your organization administrator—you may need additional access.
**Page description:** Configure A/B/N rollout. Define variants with named percentile ranges to control feature rollouts.
## Experiments list [#experiments-list]
The left panel shows all experiments in the project and how many exist. Select an experiment to edit it on the right, or create a new one.
* **New Experiment** / **Create Experiment** — Opens the create dialog (subject to your plan’s experiment limit).
* If the list is empty, you see **No experiments yet** with a prompt to create your first experiment for A/B/N rollouts.
* When nothing is selected on the right, the page prompts you to **Select an experiment from the list or create your first experiment**.
Each list item shows the experiment **name** and **slug**.
If you reach your plan’s experiment limit, you will see **Experiments limit reached** and need to upgrade before creating more.
## Create an experiment [#create-an-experiment]
1. Click **New Experiment** or **Create Experiment**.
2. In the **Create Experiment** dialog, fill in:
* **Slug** (required) — Lowercase letters, numbers, and underscores only. Cannot be changed after creation.
* **Name** (optional) — Display name.
* **Description** (optional).
3. Click **Create**.
You are taken to the experiment detail view to configure variants and ranges.
## Experiment details [#experiment-details]
After selecting an experiment, the **Experiment Details** panel includes:
| Field | Description |
| --------------- | ------------------------------------ |
| **Slug** | Read-only system identifier. |
| **Name** | Editable display name. |
| **Description** | Optional notes about the experiment. |
Click **Save** to apply changes to name, description, and variants.
Use the **⋮** menu for:
* **Details** — View name, description, variant summary, created/updated timestamps, and who created or last updated the experiment.
* **Delete experiment** — Permanently remove the experiment (cannot be undone).
If the experiment is in use as an active master reference, you may see a notice that editing this document does not automatically change live feedback—you need to update the experiment in **Advanced Options** on the relevant form for changes to take effect there.
## Variants and ranges [#variants-and-ranges]
Under **Variants & Ranges**, define how users are split (up to **10 variants** per experiment).
1. Click **Add Variant** to add a variant group.
2. For each variant, set:
* **Variant name** — e.g. Default, Variant A.
* **Ranges** — One or more named slices with **start** and **end** percentages (0–100).
Use **Add Range** inside a variant to add another range row. Each range has a name (e.g. Control, Test) and a percent band such as `0`–`50` and `50`–`100`.
Ranges within a variant must:
* Start at **0%** for the first range.
* Be **contiguous** (no gaps or overlaps between ranges).
* Have start less than end, and end not above **100%**.
* Cover up to 100% total (partial coverage such as 0–50% only is allowed).
If validation fails, an error message appears before you can save—for example missing ranges, overlapping bands, or end above 100%.
Use **Remove variant** or the trash icon on a range row to delete items you no longer need.
## Typical workflow [#typical-workflow]
1. Create an experiment with a stable **slug**.
2. Add variants and percentile ranges that match your rollout design.
3. **Save** the experiment.
4. Attach the experiment in feedback **Advanced Options** where you want A/B/N behavior (update there when you change variant definitions used in production).
## Best practices [#best-practices]
* Use clear slugs (e.g. `checkout_rollout_v1`) and do not change them after the experiment is referenced elsewhere.
* Keep range names meaningful (Control, Treatment A) so reports and targeting are easy to understand.
* Start with two variants and two contiguous ranges (e.g. 0–50% and 50–100%) for a simple A/B split.
# Global Throttling (/docs/settings/global-settings/global-throttling)
**Global Throttling** lets you limit how often feedback forms can be shown and submitted. Use it to reduce survey fatigue, protect response quality, and cap usage of AI-powered **Refine text** on long-answer fields.
## Where to find it [#where-to-find-it]
1. Open your project in the encatch dashboard.
2. Go to **Settings**.
3. Under **Global Settings**, open **Global Throttling**.
If you do not see **Global Throttling**, contact your organization administrator—you may need additional access.
**Page description:** Configure throttling settings to control feedback views and responses globally, per user, or per feedback.
## Save your changes [#save-your-changes]
After editing any section, click **Save settings** to apply. Use **Reset** to discard unsaved changes and restore the last saved values. You will see a confirmation when settings are saved successfully.
On plans where throttling is not included, the **Throttle globally**, **Throttle per user**, and **Throttle per feedback** cards show as locked. Upgrade your plan to configure those limits. **Throttle AI Refine Text** remains available to configure.
## Throttle globally [#throttle-globally]
Limits apply across the whole project for the selected time window.
Turn the section **Enabled**, then set:
| Setting | Description |
| --------------------------- | --------------------------------------------------------------- |
| **Time frame** | Rolling window for the limits (from 15 minutes up to 365 days). |
| **Max. views** | Maximum number of feedback form views allowed in that window. |
| **Max. feedback responses** | Maximum number of feedback submissions allowed in that window. |
**Apply these limits on** — Choose where the rule applies (at least one required):
* **Shareable** — Shareable link experiences.
* **Manual** — Manually launched feedback.
* **Auto** — Automatically triggered feedback.
## Throttle per user [#throttle-per-user]
Limits apply separately to each user.
Turn the section **Enabled**, then set **Time frame**, **Max. views**, and **Max. feedback responses** as above.
Additional option:
### Gap time between views [#gap-time-between-views]
| Setting | Description |
| -------------------------- | ---------------------------------------------------------------------------- |
| **Gap time between views** | Minimum minutes between two feedback views for the same user (up to 7 days). |
**Gap time between views** applies only to **Auto** (automatically triggered) feedback. It does not affect **Shareable** or **Manual** feedback, even if those options are selected under **Apply these limits on**.
Gap time between views must be less than or equal to the selected **Time frame** when **Auto** is enabled. For example, if the time frame is 15 minutes, gap time cannot be 30 minutes. This field is only shown when **Auto** is checked under **Apply these limits on**.
Use **Apply these limits on** to choose **Shareable**, **Manual**, and/or **Auto** (at least one required). The gap-time cooldown is enforced only when feedback is shown via an automatic trigger.
## Throttle per feedback [#throttle-per-feedback]
Limits apply per feedback form (each form has its own counters).
Turn the section **Enabled**, then set **Time frame**, **Max. views**, **Max. feedback responses**, and **Apply these limits on** (**Shareable**, **Manual**, **Auto** — at least one required). There is no gap-time setting for this section.
## Throttle AI Refine Text [#throttle-ai-refine-text]
This section is always **Enabled**. It limits how often users can use **Refine text** on long text response fields (Refine text must be turned on in your form configuration).
| Setting | Description |
| ---------------------------- | ------------------------------------------------------------------------- |
| **Window** | Fixed at **5 minutes** from the first Refine text click. |
| **Per identified users** | Maximum attempts per signed-in or identified user in that window (1–100). |
| **Visitors / unknown users** | Maximum attempts per visitor in that window, counted by IP (1–100). |
From the first Refine text click, identified users and visitors each get up to their configured number of attempts within the 5-minute window.
## Time frame options [#time-frame-options]
When a throttle section is enabled, **Time frame** can be set to:
* 15 minutes, 30 minutes, 45 minutes
* 1 hour, 12 hours, 24 hours
* 7 days, 14 days, 30 days, 90 days, 180 days, 365 days
## Tips [#tips]
* Enable only the throttle types you need. **Throttle per user** is a common choice to avoid showing the same person too many surveys in a short period.
* For **Throttle per user**, combine a **Time frame** with **Gap time between views** so users are not prompted again immediately after dismissing an automatically triggered form. Remember that gap time applies to **Auto** feedback only.
* Under **Apply these limits on**, select only the delivery types you want to restrict (for example **Auto** only).
* Keep **Max. feedback responses** at or below **Max. views** when both matter for your use case.
# Pause Feedbacks (/docs/settings/global-settings/pause-feedbacks)
Use **Pause Feedbacks** to temporarily stop all feedback forms from showing for a given app in your project. This is useful when you need to disable surveys on one channel (for example web only) while keeping them active on others.
## Where to find it [#where-to-find-it]
1. Open your project in the encatch dashboard.
2. Go to **Settings**.
3. Under **Global Settings**, open **Pause Feedbacks**.
If you do not see **Pause Feedbacks**, contact your organization administrator—you may need additional access.
**Page description:** Manage feedback configuration for each app in your project. Edit settings per row and save when ready.
## Pause feedbacks by app [#pause-feedbacks-by-app]
The table lists each app configured for your project. Use the **Pause Feedbacks** switch on a row to pause or resume all feedback forms for that app.
| Column | Description |
| ------------------- | -------------------------------------------------------------------------------------------------------- |
| **App** | The application name (from your [publishable SDK keys](/docs/settings/security/publishable-sdk-keys)). |
| **Pause Feedbacks** | When **Yes**, all feedback forms are paused for that app. When **No**, feedback forms can show as usual. |
Apps are grouped into:
* **Shareable** — shareable link experiences.
* **In App** — in-app SDK experiences.
### Pause all in-app feedbacks [#pause-all-in-app-feedbacks]
Under **In App**, the **All** row lets you pause or resume feedback forms for every in-app app at once. When **All** is set to **Yes**, individual in-app rows are disabled until you turn **All** back to **No**.
If your product runs on multiple channels (for example Android, iOS, and web) with a separate app name per channel, you can pause feedback only for the web app while Android and iOS keep showing forms. App names are defined when you create API keys.
## Save your changes [#save-your-changes]
1. Turn **Pause Feedbacks** on or off for the apps you need.
2. Changed rows are highlighted until you save.
3. Click **Save all** to apply. Use **Reset** to discard unsaved changes and restore the last saved values.
Pausing feedback for one app does not affect other apps in the same project.
## Before you can configure apps [#before-you-can-configure-apps]
If no apps appear, you need at least one app configured for the project (typically by creating a [publishable SDK key](/docs/settings/security/publishable-sdk-keys) with an application name). The page shows **No app is configured yet** until apps are available.
# Retention (/docs/settings/global-settings/retention)
**Retention** controls when encatch automatically removes old user profiles and their associated data—such as feedback responses, traits, and activity records—from your project environment.
## Where to find it [#where-to-find-it]
1. Open your project in the encatch dashboard.
2. Go to **Settings**.
3. Under **Global Settings**, open **Retention**.
If you do not see **Retention**, contact your organization administrator—you may need additional access.
**Page description:** Automatically remove old user profiles and all associated data (feedback responses, traits, activity records) from this environment.
## Data retention policy [#data-retention-policy]
The **Data Retention Policy** card has two settings. Each uses the same list of retention periods.
### Users with feedback responses [#users-with-feedback-responses]
How long to keep user profiles that have submitted at least one feedback response.
### All other user profiles [#all-other-user-profiles]
How long to keep user profiles that have **not** submitted feedback (for example users who were identified or tracked but never responded).
## Retention period options [#retention-period-options]
For each setting, choose one of:
| Option | Meaning |
| -------------------------------- | --------------------------------------------------------------------------------- |
| **Until plans retention period** | Follow your subscription plan’s default retention (no project-specific override). |
| **Remove after 30 days** | Delete profiles after 30 days. |
| **Remove after 90 days** | Delete profiles after 90 days. |
| **Remove after 180 days** | Delete profiles after 180 days. |
| **Remove after 1 year** | Delete profiles after one year. |
| **Remove after 2 years** | Delete profiles after two years. |
| **Remove after 3 years** | Delete profiles after three years. |
You can set different periods for users with feedback responses and for all other user profiles—for example, keep respondents longer for reporting while removing inactive profiles sooner.
Deleting user profiles removes associated feedback responses, traits, and activity for those users in this environment. Review your compliance and reporting needs before shortening retention.
## Save your changes [#save-your-changes]
1. Choose a retention period for **Users with feedback responses** and **All other user profiles**.
2. Click **Save policy** to apply. You will see a confirmation when the policy is saved successfully.
3. Click **Reset** to discard unsaved changes and restore the last saved policy.
# Admin API Keys (/docs/settings/security/admin-api-keys)
**Admin API keys** authenticate trusted server-side requests to Encatch. Keep them on your backend and never include them in browser code, mobile apps, or client SDK configuration.
## Create an admin API key [#create-an-admin-api-key]
1. Open **Settings → Admin API Keys**.
2. Select **New**.
3. Enter a key name, optional description, and application identifier.
4. Choose the expiry period.
5. Set the contact creation policy described below.
6. Create the key and copy its value when it is shown.
## Contact creation policy [#contact-creation-policy]
Each Admin API key can control whether a request using that key may create a contact that does not already exist.
* **Allow contact creation** — The key can create new contacts and update existing contacts.
* **Existing contacts only** — The key can update contacts that already exist without creating new records.
Use **Existing contacts only** for integrations that should enrich records already managed by another system. Enable contact creation when Encatch is an intended entry point for new contacts.
The policy is attached to the key, so separate integrations can use different rules. Rotate or replace a key when an integration's responsibility changes.
## Security practices [#security-practices]
* Store the key in a server-side secret manager.
* Give each integration its own key and descriptive application identifier.
* Use the shortest practical expiry and rotate before it ends.
* Delete a key immediately if it is exposed.
For client-side SDK credentials, use [Publishable SDK Keys](/docs/settings/security/publishable-sdk-keys).
# Publishable SDK Keys (/docs/settings/security/publishable-sdk-keys)
**Publishable SDK keys** authenticate your encatch SDKs with our servers so you can collect in-app and web feedback securely. Keys are meant for client-side SDK integration; pair them with a server-side secret only when you use signature validation.
## Where to find it [#where-to-find-it]
1. Open your project in the encatch dashboard.
2. Go to **Settings**.
3. Under **Security**, open **Publishable SDK Keys**.
If you do not see **Publishable SDK Keys**, contact your organization administrator—you may need additional access.
**Page description:** Manage your project's publishable SDK keys. Create, view, and delete publishable SDK keys for secure access to your services.
## Keys list [#keys-list]
The table shows keys for the selected tab:
| Tab | Description |
| ---------------- | ------------------------------------------------- |
| **Active keys** | Keys currently in use. |
| **Deleted keys** | Keys you have deleted (see retention note below). |
| Column | Description |
| -------------------- | ----------------------------------------------------------------- |
| **App name** | Application name / identifier linked to the key. |
| **Key identifier** | The name you gave the key when creating it. |
| **Expires In** | When the key expires, or **Never** if no expiry. |
| **Key Suffix** | Short suffix to cross-reference with the full key (`..._suffix`). |
| **Info and Actions** | Open details, view status, or delete an active key. |
Use **Create Publishable SDK Key** at the top to add a new key (subject to your plan’s publishable SDK key limit).
If you reach your plan limit, you will see **Publishable SDK Keys limit reached** and need to upgrade before creating more.
### Deleted keys [#deleted-keys]
On the **Deleted keys** tab, deleted or expired keys are listed. They are **permanently removed after 15 days** and cannot be restored.
## Create a publishable SDK key [#create-a-publishable-sdk-key]
1. Click **Create Publishable SDK Key**.
2. Fill in the dialog sections below, then click **Create**.
**Dialog description:** Publishable SDK keys authenticate your SDKs with our servers, enabling secure communication for in-app feedback collection.
### Basic information [#basic-information]
| Field | Description |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Key name** (required) | Descriptive name (max 25 characters), e.g. `Production SDK`. |
| **Description** (optional) | Notes about the key (max 100 characters). |
| **Application name / identifier** (required) | Short id for the app (max 25 characters), e.g. `myapp` or `shop01`. Links feedback forms and settings such as [Pause Feedbacks](/docs/settings/global-settings/pause-feedbacks) to this app. |
A warning may appear if you use a reserved application name—use those identifiers only when intended (for example shareable or in-app reserved names).
### Access configuration [#access-configuration]
| Field | Description |
| ----------------------------------------- | ------------------------------------------------------------------------- |
| **Expiry period** (required) | 1 day, 1 week, 1 month, 3 months, 6 months, 1 year, or a **custom date**. |
| **API key prefix** | Read-only prefix shown on the generated key (depends on environment). |
| **Allowed domains / packages** (required) | Origins or app bundle ids allowed to use this key. Add up to 10 entries. |
Examples for allowed domains / packages:
* `*` — all origins (not recommended for production)
* `https://app.example.com`
* `https://*.example.com`
* Android: `com.mycompany.myapp`
Using `*` in **Allowed domains / packages** allows all domains to access this publishable SDK key.
### Security configuration (optional) [#security-configuration-optional]
| Field | Description |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Secret key** | Generate a secret for hashing user IDs and signature validation. **Never expose this on the client**—store it only on your server. |
| **Session time (minutes)** | Session timeout for validation. Set to **0** to disable (default). |
### After creation [#after-creation]
You see **Your Publishable SDK Key** once. Copy it immediately—you will not be able to view the full key again. Use the show/hide and copy controls, then click **Close**.
If you lose a key, create a new one with the same **application name** and update your app, then delete the old key.
## Key details and delete [#key-details-and-delete]
Open **Info and Actions** (⋮) on a row to see:
* **Status** — Active, Expired, Deleted, or Inactive
* **Allowed domains / packages**
* **Created by** / **Updated by** with timestamps
Active, non-expired keys can be deleted via **Delete Publishable SDK Key** (confirmation required).
## Best practices [#best-practices]
* Restrict **Allowed domains / packages** to your real sites and app bundle ids; avoid `*` in production.
* Rotate keys before **Expiry period** ends; keep the same **application name** when replacing a key.
* Publishable keys are safe to embed in client apps, but treat optional **secret keys** as server-only credentials.
* Test keys follow your plan’s test/production rules and may not count the same toward usage limits.
For rate limits on SDK and API traffic, see [Rate Limits](/docs/sandbox-limits/rate-limits).
# Cache Management (/docs/settings/feedback-settings/cache-management)
Encatch caches feedback configurations so your SDK can load them quickly. When you update forms or settings and need those changes to show up right away in your app, use **Cache Management** to reset the application cache for your project.
## Where to find it [#where-to-find-it]
1. Open your project in the encatch dashboard.
2. Go to **Settings**.
3. Under **Feedback Settings**, open **Cache Management**.
If you do not see **Cache Management**, contact your organization administrator—you may need additional access to reset cache.
## Reset application cache [#reset-application-cache]
The **Cache management** page lets you reset cache for the current project.
**Page description:** Reset application cache to refresh data sources and fix display issues. Your configurations and saved data will not be affected.
### Cache reset information [#cache-reset-information]
Before you reset, read the notice on the page:
> Resetting the cache will clear all stored data and changes will be instantly visible. This action is useful when you need to refresh data sources or fix display issues. Your configurations and saved data will not be affected.
### How to reset cache [#how-to-reset-cache]
1. In the **Reset cache** card, find **Reset Application Cache**.
2. Click **Reset Cache**.
3. In the confirmation dialog, review the message: resetting clears cached data but does not affect your configurations.
4. Note the warning that this action cannot be undone, then confirm with **Reset Cache**.
After a successful reset, you will see a success message. If reset fails, try again or contact support.
The system will automatically rebuild necessary caches as needed—you do not need to change anything in your application code.
Resetting cache does not delete your feedback forms or saved responses. Only cached copies are cleared so the latest configurations can be loaded again.
## When to use cache reset [#when-to-use-cache-reset]
Use **Reset cache** when:
* You changed feedback forms or project settings and your SDK still shows older content.
* You need to refresh data sources or fix display issues in your app.
If your changes are not urgent, you can wait for your SDK’s next config sync instead of resetting cache immediately.
# Data Settings (/docs/settings/user-data/data-settings)
Data Settings controls which automatic fields encatch collects from your users — things like device type, browser, or country. You pick what goes on the **user profile** and what gets **attached to survey responses**.
Use this page to stay within your PII policy. Only turn on fields you actually need.
## Where to find it [#where-to-find-it]
1. Open your project in the encatch dashboard.
2. Go to **Settings**.
3. Under **User Data**, open **Data Settings**.
If you do not see **Data Settings**, contact your organization administrator — you may need additional access.
## Contact Info & Feedback Response [#contact-info--feedback-response]
The table lists fields encatch can capture automatically. Each row has two optional checkboxes:
| Column | What it does |
| --------------------- | ----------------------------------------------------------------------------------- |
| **Contact Info** | Saved on the user's profile when they are identified or interact with your app. |
| **Feedback Response** | Sent along with each survey submission. Useful when filtering responses in Reports. |
A dash (—) means that field cannot be used for that column.
Changes are not applied until you click **Save settings**. Use **Reset** to undo unsaved edits.
Some fields (such as device and session metadata) are controlled from [Data Settings](/docs/settings/user-data/data-settings) under **Feedback Response**, not from the User Traits table.
## Managing traits [#managing-traits]
### Create a trait [#create-a-trait]
1. Go to **Settings → User Data → User Traits** for the project.
2. Click **Create Trait**.
3. In the **Create New Trait** dialog, enter:
* **Slug** – Lowercase, letters, numbers, and underscores only. Must be unique in the project.
* **Name** – Human-readable label.
* **Data type** – Text, Numeric, Datetime, or Boolean.
* **Include in feedback response** – Optional; subject to the project limit (see below).
4. Click **Create**.
### Rename a trait [#rename-a-trait]
Edit the **Name** field in the table and save. The slug (system identifier) does not change. System-generated traits can be renamed; only the display name is updated.
### Include in feedback response [#include-in-feedback-response]
Use the **Feedback Response** checkbox for each trait to include it in feedback response payloads. This is useful for filtering or grouping feedback in Reports.
* A maximum of **25** traits per project can be included in the feedback response. Once the limit is reached, you must uncheck another trait before checking a new one.
* Some system traits may not be available for feedback response.
* Traits reserved for [Data Settings](/docs/settings/user-data/data-settings) show as controlled by Data Settings and cannot be toggled here.
### Usage information [#usage-information]
The **In Use** column shows whether a trait is referenced in:
* **Segments** – Used in [data-driven segment](/docs/segmentation/data-driven) conditions (User Traits and System fields).
* **Feedback** – Used in feedback-related configuration.
Click the usage indicator to see details. Traits that are **in use** cannot be disabled or deleted until they are removed from those usages.
### Disable a trait [#disable-a-trait]
For traits that support it, use the **Pause** (disable) action. Disabled traits are ignored for new incoming data. System-generated traits and traits that are in use cannot be disabled. Use **Play** to enable again.
### Delete a trait [#delete-a-trait]
Use the **Delete** action for custom traits that are **not** in use. Deleting removes the trait from the project. System-generated traits cannot be deleted.
## Feedback response limit [#feedback-response-limit]
Only a limited number of traits per project can be marked as **Include in feedback response** (up to 25). Choose the traits that are most useful for filtering and reporting. You can change which traits are included at any time within the limit.
## Best practices [#best-practices]
* **Slugs**: Use clear, stable slugs (e.g. `plan`, `country`, `signup_date`). Avoid changing them in your app after traits are in use.
* **Allow new traits**: Turn **Allow new traits from clients** off if you want to restrict which attributes are stored and avoid accidental trait proliferation.
* **Feedback response**: Only include traits you actually need in reports and integrations to stay within the feedback response limit.
# undefined (/docs/administrative-guide/form-builder/appearance)
# Consent (/docs/feedback-management/question-types/choice/consent)
The **Consent** element collects agreement to terms, a privacy policy, or other acknowledgement text you write in markdown. It is a fixed **agree / disagree** pattern **without** custom option labels (unlike **[Yes / No](/docs/feedback-management/question-types/choice/yes-no)**, where you can rename both choices). In the form builder it appears under **Choice** as **Consent**.
## When to use [#when-to-use]
* Privacy policy, terms of service, or data-processing notices
* Mandatory checkboxes before continuing the form
* Any short legal or compliance copy where respondents must explicitly agree
## Customization options [#customization-options]
When editing a Consent question, you can configure the following properties:
| Option | Description |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Internal display label** | Required label used in the builder and internal lists (not the main legal copy). You can insert variables from the picker where supported. |
| **Consent content** | Required body text shown to respondents; **markdown** is supported (up to 500 characters in the editor). This is where you place the terms, policy summary, or acknowledgement wording. |
| **Slug** | Optional URL-friendly identifier for the question. |
| **Error Message** | The message shown when validation fails (e.g. required consent not given). Keep it clear and actionable. |
| **Next button label** | Label for the button that advances past this question after the respondent agrees. |
| **Consent alignment** | **Left** — content aligned to the start. **Justify** — full-width justified block text (often better for long paragraphs than centering). |
| **Required field** | When enabled, respondents must agree before continuing. |
| **Hidden question** | When enabled, the question can be hidden from respondents where your form logic allows. |
## Viewing responses [#viewing-responses]
Consent responses appear in the [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary) for your form. You can see who agreed or did not, filter by time period or segment, and audit acknowledgement over time.
# Multiple Choice (/docs/feedback-management/question-types/choice/multiple-choice)
The **Multiple Choice** element lets respondents select one or more options from a predefined list (e.g. checkboxes). Use it when you need to capture multiple selections—such as "Which devices do you use to access this application?", "What features do you use most?", or "Select all that apply"—that you can analyze and visualize in charts.
## When to use [#when-to-use]
* "Select all that apply" questions
* Feature usage, interests, or multi-select preferences
* Questions where respondents may legitimately choose several options
## Customization options [#customization-options]
When editing a Multiple Choice question, you can configure the following properties:
| Option | Description |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Question Text** | The main question displayed to the respondent (required). |
| **Description** | Optional helper text or context below the question (up to 100 characters). |
| **Answer Options** | The list of choices (required). Each option has an **Option Label** (what respondents see) and an **Option Value** (what gets stored). Use "+ Add Option" to add more choices, or the trash icon to remove one. |
| **Error Message** | The message shown when validation fails (e.g. required field not filled, invalid selection). Keep it clear and actionable for better user experience. Default: "Please complete this required question". |
| **Required field** | When enabled, the respondent must select at least one option before submitting the form. |
| **Minimum Selections** | The minimum number of options the respondent must select (e.g. 0 for optional, 1+ for required). |
| **Maximum Selections** | The maximum number of options the respondent can select (e.g. 2 to limit choices). |
| **Display Mode** | How the options are presented—e.g. **Checkboxes** or **List**. Choose the style that fits your form layout. |
| **Allow "Other" option** | When enabled, respondents can choose "Other" and provide a custom response outside the predefined options. |
## Viewing responses [#viewing-responses]
Multiple-choice responses appear in the [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary) for your form. You can view them as bar charts or pie charts, filter by time period or user segment, and track trends over time.
# Nested Selection (/docs/feedback-management/question-types/choice/nested-selection)
The **Nested Selection** element lets respondents choose from hierarchical dropdown options—selecting a parent category first, then drilling down into child options. Use it when you need structured, multi-level choices—such as "Select your department and the main function you use in the application", "Choose your region and office", or "Pick a product category and subcategory"—that you can analyze and visualize in charts.
## When to use [#when-to-use]
* Department and function selection within an organization
* Region and location hierarchies
* Product or service category trees
* Any question where options are logically grouped under parent categories
## Customization options [#customization-options]
When editing a Nested Selection question, you can configure the following properties:
| Option | Description |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Question Text** | The main question displayed to the respondent (required). |
| **Description** | Optional helper text or context below the question (up to 100 characters). |
| **Placeholder Text** | The text shown in the dropdown before a selection is made. Default: "Select an option". |
| **Error Message** | The message shown when validation fails (e.g. required field not filled, invalid selection). Keep it clear and actionable for better user experience. Default: "Please complete this required question". |
| **Required field** | When enabled, the respondent must make a selection before submitting the form. |
| **Show parent labels in selection** | When enabled, the selected option displays its parent label(s) in the dropdown for clarity (e.g. "Parent Option 1 › Child Option A"). |
| **Dropdown Options** | The hierarchical list of choices (required). Each option has a **Label** (what respondents see), **Option Hint Text** (optional helper text), and **Value** (what gets stored). Use "+ Add Option" to add top-level options, the "+" icon next to an option to add child options, or the trash icon to remove an option. Options can be expanded or collapsed to manage the hierarchy. |
## Managing dropdown options [#managing-dropdown-options]
* **Add Option** — Creates a new top-level parent option.
* **Add Child Option** — Adds a nested option under the selected parent. Use the expand/collapse arrow to reveal child options.
* **Label** — The text displayed to respondents in the dropdown.
* **Option Hint Text** — Optional hint shown below the label to provide additional context.
* **Value** — The value stored for analytics and reporting.
## Viewing responses [#viewing-responses]
Nested selection responses appear in the [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary) for your form. You can view them as bar charts or pie charts, filter by time period or user segment, and track trends over time.
# Picture Choice (/docs/feedback-management/question-types/choice/picture-choice)
The **Picture choice** element (labeled **Picture Choice** in the form builder) shows respondents a grid of options defined by an **image**, **label**, and optional **hint** per option. Respondents tap one or more images depending on your settings.
## When to use [#when-to-use]
* Visual preference tests, product concepts, logos, or mood boards
* When images communicate choices faster than text alone
## Customization options [#customization-options]
| Option | Description |
| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Question Text** | Main question (required). |
| **Description** | Optional markdown. |
| **Error Message** | Validation failure message. |
| **Required field** | At least one selection required when enabled. |
| **Options** | Up to **30** options. For each: image (asset picker), internal value, label, optional hint. Reorder via drag handle. |
| **Allow multiple selections** | When on, respondents can pick more than one image. |
| **Supersize images** | Larger image presentation in the form. |
| **Show labels** | Toggle visibility of option labels under images. |
| **Randomize option order** | Shuffle options per session. |
| **Allow Other** | Adds an “Other” path with configurable placeholder text for free-text follow-up (translations supported). |
| **Next button label**, **Show question title**, **Text alignment**, **Slug** | Standard question chrome. |
| **Secondary settings** | Validations and visibility where supported. |
## Viewing responses [#viewing-responses]
Selections appear with your other choice-type questions in [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary).
For global form options, see [Other Fields Configuration](/docs/feedback-management/question-types/other-fields-configuration).
# Ranking (/docs/feedback-management/question-types/choice/ranking)
The **Ranking** element asks respondents to order a list of items (for example features, priorities, or preferences). You define the options; respondents assign ranks.
## When to use [#when-to-use]
* Priority lists, feature voting, or “order these from most to least important”
* When relative order matters more than a single score per item
## Customization options [#customization-options]
| Option | Description |
| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Question Text** | Main question (required). |
| **Description** | Optional markdown context. |
| **Error Message** | Shown when validation fails. |
| **Required field** | A complete ranking may be required before submit. |
| **Options** | Add, remove, and reorder items (up to **30** options). Each option has a value and label (labels support translations). |
| **Randomize option order** | Shuffle the initial order shown to each respondent. |
| **Display style** | **Drag and drop** or **↑ ↓ arrows** to change order. |
| **Limit ranking to top N items** | Optional: respondents rank only their top *N* choices instead of the full list. |
| **Next button label**, **Show question title**, **Text alignment**, **Slug** | Same patterns as other question types. |
| **Secondary settings** | Validations and visibility where supported. |
## Viewing responses [#viewing-responses]
Ranking data is reflected in your form’s reporting; use [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary) to review collected answers.
See also [Other Fields Configuration](/docs/feedback-management/question-types/other-fields-configuration) for global form display options.
# Single Choice (/docs/feedback-management/question-types/choice/single-choice)
The **Single Choice** element lets respondents select exactly one option from a predefined list (e.g. radio buttons or a list). Use it when you need structured, comparable answers—such as "How many departments in your organization?", "Where did you hear about us?", or "What is your preferred method of interacting with the application?"—that you can analyze and visualize in pie and bar charts.
## When to use [#when-to-use]
* Demographics, category selection, or preference questions
* When only one answer is valid (e.g. "Which plan are you on?")
* Questions where you need comparable, structured data across respondents
## Customization options [#customization-options]
When editing a Single Choice question, you can configure the following properties:
| Option | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Question Text** | The main question displayed to the respondent (required). |
| **Description** | Optional helper text or context below the question (up to 100 characters). |
| **Answer Options** | The list of choices. Each option has a **Label** (what respondents see) and a **Value** (what gets stored). Use "+ Add Option" to add more choices, or the trash icon to remove one. |
| **Error Message** | The message shown when validation fails (e.g. required field not filled). Keep it clear and actionable for better user experience. |
| **Required field** | When enabled, the respondent must select an option before submitting the form. |
| **Display Style** | How the options are presented—e.g. **Radio Button** or dropdown. Choose the style that fits your form layout. |
| **Allow "Other" option** | When enabled, respondents can choose "Other" and provide a custom response outside the predefined options. |
## Viewing responses [#viewing-responses]
Single-choice responses appear in the [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary) for your form. You can view them as bar charts or pie charts, filter by time period or user segment, and track trends over time.
# Yes / No (/docs/feedback-management/question-types/choice/yes-no)
The **Yes / No** element collects a **binary** answer: two options you label yourself (defaults **Yes** and **No**). Use it for quick confirmations, screening questions, or any clear either/or decision. In the form builder it appears under **Choice** as **Yes / No**.
It is similar to **[Single Choice](/docs/feedback-management/question-types/choice/single-choice)** with exactly two options, but optimized for a simple affirmative/negative pattern. For terms or policy text with a standard agree/disagree flow and no custom button labels, use **[Consent](/docs/feedback-management/question-types/choice/consent)** instead.
## When to use [#when-to-use]
* Quick filters or qualifiers (“Do you currently use feature X?”)
* Simple confirmations before follow-up questions
* Any question that should read naturally as yes/no rather than a longer option list
## Customization options [#customization-options]
When editing a Yes / No question, you can configure the following properties:
| Option | Description |
| --------------------- | --------------------------------------------------------------------------------------------------------- |
| **Question Text** | The main question displayed to the respondent (required). |
| **Description** | Optional helper text below the question; supports markdown (up to 500 characters in the editor). |
| **Slug** | Optional URL-friendly identifier for the question. |
| **Yes label** | Text for the affirmative option (default: "Yes"). Up to 100 characters. |
| **No label** | Text for the negative option (default: "No"). Up to 100 characters. |
| **Error Message** | The message shown when validation fails (e.g. required field not answered). Keep it clear and actionable. |
| **Display style** | **Horizontal** — both options in a row. **Vertical** — options stacked. |
| **Next button label** | Label for the button that advances past this question. |
| **Text alignment** | How the question block is aligned (e.g. left or center). |
| **Required field** | When enabled, the respondent must choose Yes or No before continuing. |
| **Hidden question** | When enabled, the question can be hidden from respondents where your form logic allows. |
## Viewing responses [#viewing-responses]
Yes / No responses appear in the [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary) for your form. You can view counts and splits between the two options, filter by time period or segment, and track trends over time.
# Address (/docs/feedback-management/question-types/contact/address)
The **Address** element collects a **structured postal address**: lines for street and unit, **city**, **state or region**, **postal code**, and **country**. Each sub-field can be **enabled**, marked **required**, and given its own **caption** and **placeholder** (with translations per language).
## When to use [#when-to-use]
* Shipping, billing, physical service areas, or compliance where you need separate fields
## Customization options [#customization-options]
### Address lines [#address-lines]
For **Address line 1**, **Address line 2**, **City**, **State / region**, **Postal code**, and **Country**:
* **Enabled** — Whether the sub-field appears.
* **Required** — Whether the respondent must fill it (only meaningful when enabled).
* **Caption** and **placeholder** — Labels and hints for each line (translatable).
### Default country [#default-country]
You can set a **default country** used when the form loads (primary language configuration in the editor).
### Standard question fields [#standard-question-fields]
**Question text**, **description**, **error message**, **required** (for the question as a whole), **next button label**, **show question title**, **text alignment**, **hidden question**, and **secondary settings** follow the same patterns as other blocks.
## Viewing responses [#viewing-responses]
Structured address fields export and display alongside other contact data; review them in [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary).
For numbering, titles, and button labels across the form, see [Other Fields Configuration](/docs/feedback-management/question-types/other-fields-configuration).
# Email (/docs/feedback-management/question-types/contact/email)
The **Email** element collects a single email address. The runtime validates the format; you can set a **placeholder** and **pre-filled value** to reduce friction.
## When to use [#when-to-use]
* Login identifiers, support contacts, newsletter opt-in, or any workflow that needs a deliverable address
## Customization options [#customization-options]
| Option | Description |
| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **Question Text** | Main question (required). |
| **Description** | Optional markdown. |
| **Placeholder** | Hint inside the field (per language, up to **150** characters in the editor). |
| **Pre-filled value** | Optional default email shown to the respondent (they can change it). |
| **Error Message** | Shown when the address is missing or invalid. |
| **Required field** | Must be filled before submit. |
| **Next button label**, **Show question title**, **Text alignment**, **Slug** | Standard chrome. |
| **Secondary settings** | Validations and visibility where supported. |
## Viewing responses [#viewing-responses]
Email values appear with other responses in [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary).
See [Other Fields Configuration](/docs/feedback-management/question-types/other-fields-configuration) for form-wide labels and display options.
# Phone Number (/docs/feedback-management/question-types/contact/phone-number)
The **Phone number** element collects a telephone number with an international **country code**. Respondents can pick or change the country when **Allow country change** is enabled; otherwise the field stays on the configured default.
## When to use [#when-to-use]
* Callback numbers, SMS consent flows, or regional support routing
## Customization options [#customization-options]
| Option | Description |
| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| **Question Text** | Main question (required). |
| **Description** | Optional markdown. |
| **Placeholder** | Hint text in the national number input (per language). |
| **Default country code** | Optional **ISO-style two-letter** code used as the initial prefix (normalised in the editor). |
| **Allow country change** | When off, respondents cannot switch away from the default country (useful for single-country campaigns). |
| **Pre-filled value** | Optional default national number. |
| **Error Message** | Shown when validation fails. |
| **Required field** | Must be completed before submit. |
| **Next button label**, **Show question title**, **Text alignment** | Standard chrome. |
| **Hidden question** | Hide the block while still storing configuration (where supported). |
| **Secondary settings** | Validations and visibility where supported. |
## Viewing responses [#viewing-responses]
Phone answers are listed with your other contact fields in [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary).
For global form options, see [Other Fields Configuration](/docs/feedback-management/question-types/other-fields-configuration).
# Signature (/docs/feedback-management/question-types/contact/signature)
The **Signature** element collects a legally oriented **signature**. Respondents can **draw**, **type**, or **upload** a signature depending on which **modes** you allow. You can tune drawing **colours**, **pen width**, **canvas height**, and optional **signer email** collection.
## When to use [#when-to-use]
* Terms acceptance with a captured signature, contracts, or field paperwork
## Customization options [#customization-options]
### Modes and defaults [#modes-and-defaults]
| Option | Description |
| ----------------- | -------------------------------------------------------------------------------- |
| **Allowed modes** | Toggle **Draw**, **Type**, and **Upload**; order reflects tab order in the form. |
| **Default mode** | Which tab opens first (must be one of the allowed modes). |
### Draw and upload copy [#draw-and-upload-copy]
| Option | Description |
| -------------------------------------- | ---------------------------------------------------- |
| **Hint on empty draw canvas** | Message when the canvas is blank. |
| **Upload tab — idle prompt** | Text when no file is selected. |
| **Upload tab — prompt while dragging** | Text during drag-over. |
| **Clear button label** | Label for clearing the canvas (for example “Clear”). |
### Drawing appearance (primary configuration) [#drawing-appearance-primary-configuration]
| Option | Description |
| ---------------------------- | ----------------------------------- |
| **Pen colour** | Stroke colour for drawn signatures. |
| **Canvas background colour** | Colour behind the stroke. |
| **Pen width** | Thickness of the pen. |
| **Canvas height** | Vertical size of the drawing area. |
### Other [#other]
| Option | Description |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| **Collect signer email address** | Optional extra field to store an email with the signature. |
| **Placeholder** | Hint for typed-name mode (per language). |
| **Question Text**, **Description**, **Error Message**, **Required**, **Next button label**, **Show question title**, **Text alignment**, **Secondary settings** | Same patterns as other questions. |
## Viewing responses [#viewing-responses]
Signature assets and metadata appear in your form’s reporting; open [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary) for the submission list.
See [Other Fields Configuration](/docs/feedback-management/question-types/other-fields-configuration) for global form chrome.
# Website (/docs/feedback-management/question-types/contact/website)
The **Website** element collects a **URL**. Use it when you need a web address rather than arbitrary text.
## When to use [#when-to-use]
* Portfolio links, company homepages, or referral URLs
## Customization options [#customization-options]
| Option | Description |
| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **Question Text** | Main question (required). |
| **Description** | Optional markdown. |
| **Placeholder** | Hint inside the field (per language, up to **150** characters in the editor). |
| **Pre-filled value** | Optional default URL (for example your domain). |
| **Error Message** | Shown when the value fails validation. |
| **Required field** | Must be provided before submit. |
| **Next button label**, **Show question title**, **Text alignment**, **Slug** | Standard chrome. |
| **Secondary settings** | Validations and visibility where supported. |
## Viewing responses [#viewing-responses]
URLs appear with other answers in [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary).
See [Other Fields Configuration](/docs/feedback-management/question-types/other-fields-configuration) for form-wide display settings.
# File Upload (/docs/feedback-management/question-types/advanced/file-upload)
The **File upload** element lets respondents attach **one or more files**. You can restrict **MIME types and extensions** using presets or custom entries, cap **size per file**, and limit how many files are accepted when **multiple** uploads are enabled.
## When to use [#when-to-use]
* Screenshots, receipts, résumés, or any evidence that belongs with the response
## Customization options [#customization-options]
### Types and size [#types-and-size]
| Option | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Allowed file types** | Toggle presets for **Images**, **Documents**, **Video**, and **Audio**; each adds a curated list of MIME types or extensions. Leave all presets off and add nothing to accept **any** file type. |
| **Custom types** | Add arbitrary entries (for example `application/json` or `.csv`); shown as removable tags. |
| **Max file size (MB)** | **Required** upper bound per file. |
| **Allow multiple files** | When on, respondents can upload more than one file. |
| **Max files** | When multiple is on, optional cap on the number of files. |
### Copy and behaviour [#copy-and-behaviour]
| Option | Description |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- |
| **Upload area placeholder** | Text inside the drop zone (per language). |
| **Question Text**, **Description**, **Error Message**, **Required**, **Next button label**, **Show question title**, **Text alignment**, **Hidden question** | Standard chrome. |
| **Secondary settings** | Validations and visibility where supported. |
## Viewing responses [#viewing-responses]
Uploaded files are linked from [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary) alongside the rest of the submission.
See [Other Fields Configuration](/docs/feedback-management/question-types/other-fields-configuration) for global form options.
# Q&A with AI (/docs/feedback-management/question-types/advanced/qna-with-ai)
The **Q\&A with AI** element adds a **conversational block** where respondents ask questions and receive answers grounded in a **knowledge base** text you provide. You control chat **limits**, **button labels**, and several **status messages** for empty states and usage counters.
## When to use [#when-to-use]
* Product FAQs, policy clarifications, or onboarding help without building a full chatbot elsewhere
## Customization options [#customization-options]
### Knowledge and input [#knowledge-and-input]
| Option | Description |
| -------------------- | ------------------------------------------------------------------------------ |
| **Knowledge base** | Long-form text the model uses to answer (character count shown in the editor). |
| **Placeholder** | Hint inside the ask field (per language). |
| **Ask button label** | Optional label for the submit action (per language, up to **50** characters). |
### Chat UI copy (per language) [#chat-ui-copy-per-language]
| Option | Description |
| ------------------------- | ------------------------------------------------------------ |
| **Empty chat hint** | Message before the first exchange. |
| **Counter — under limit** | Template when the respondent still has Q\&A pairs remaining. |
| **Counter — at limit** | Template when the exchange cap is reached. |
### Limits (primary language) [#limits-primary-language]
| Option | Description |
| ----------------------- | ------------------------------------------------------------------------ |
| **Max response length** | Optional cap on answer length in **characters**. |
| **Max Q\&A exchanges** | Optional cap on how many question–answer **pairs** a respondent may use. |
### Standard fields [#standard-fields]
**Question text**, **description**, **error message**, **required**, **next button label**, **show question title**, **text alignment**, **hidden question**, and **secondary settings** behave like other questions.
## Viewing responses [#viewing-responses]
Chat transcripts are stored with the submission; review them in [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary).
See [Other Fields Configuration](/docs/feedback-management/question-types/other-fields-configuration) for form-wide display settings.
# Scheduler (/docs/feedback-management/question-types/advanced/scheduler)
The **Scheduler** element embeds a live booking experience using either **Google Calendar** or **Calendly**. You paste the **calendar or event URL**, configure optional **intro** behaviour, and can **autofill** name and email from earlier questions.
## When to use [#when-to-use]
* Sales demos, support calls, interviews, or any workflow that ends in a booked slot
## Customization options [#customization-options]
### Provider and URL [#provider-and-url]
| Option | Description |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Provider** | **Google Calendar** or **Calendly**. |
| **Google booking page link** | For Google: paste the appointment **booking page URL** from Calendar (the editor reminds you to use Appointment schedule → Save, then copy the link). |
| **Calendly embed URL** | For Calendly: paste the full **event-type URL** (for example `https://calendly.com/you/30min`). |
### Respondent experience [#respondent-experience]
| Option | Description |
| ------------------------------------- | ---------------------------------------------------------------------------- |
| **Show intro screen before calendar** | When on, respondents see an intermediate step before the embedded scheduler. |
| **Schedule a meeting — button text** | Optional label for the primary scheduling action (per language). |
| **Placeholder** | Hint when the scheduler area is loading or idle (per language). |
### Autofill [#autofill]
| Option | Description |
| -------------------------------- | ----------------------------------------------------------------------- |
| **Autofill name from question** | Pick an earlier question whose answer fills the scheduler’s name field. |
| **Autofill email from question** | Pick an earlier question for the email field. |
### Standard fields [#standard-fields]
**Question text**, **description**, **error message**, **required**, **next button label**, **show question title**, **text alignment**, **hidden question**, and **secondary settings** follow the same patterns as other blocks.
## Viewing responses [#viewing-responses]
Booking outcomes appear with the submission in [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary).
For global button labels and layout options, see [Other Fields Configuration](/docs/feedback-management/question-types/other-fields-configuration).
# Video / Audio / Photo (/docs/feedback-management/question-types/advanced/video-audio)
The **Video/Audio/Photo** element (builder label **Video/Audio/Photo**) collects **video**, **audio**, **photo**, or **text** responses depending on which **modes** you enable. You can set a **default mode**, tune **recording duration**, allow **file upload** as an alternative to the camera or mic, and customize many on-screen labels.
## When to use [#when-to-use]
* Verbal feedback, video testimonials, photo proof, or async user research clips
## Customization options [#customization-options]
### Modes and defaults [#modes-and-defaults]
| Option | Description |
| ----------------- | -------------------------------------------------------------------------------------------------- |
| **Allowed modes** | Enable any combination of **Video**, **Audio**, **Photo**, and **Text**; order controls tab order. |
| **Default mode** | Which experience opens first (must be allowed). |
### Recording and upload [#recording-and-upload]
| Option | Description |
| -------------------------------- | -------------------------------------------------------------------------------- |
| **Limit max recording duration** | Optional cap for **video and audio**; set minutes and seconds. |
| **Allow upload** | When on, respondents may upload a file instead of only recording in the browser. |
| **Max file size (MB)** | Applies when upload is allowed. |
### Labels and hints (per language) [#labels-and-hints-per-language]
Examples include: **Record** button, **Upload file** button, idle hints over the video or photo areas, **Use camera**, **Upload image**, and related prompts. These let you match your brand voice.
### Other [#other]
**Question text**, **description**, **placeholder**, **error message**, **required**, **next button label**, **show question title**, **text alignment**, **hidden question**, and **secondary settings** behave like other question types.
## Viewing responses [#viewing-responses]
Media attachments and metadata surface in [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary).
See [Other Fields Configuration](/docs/feedback-management/question-types/other-fields-configuration) for form-wide controls.
# Matrix (multiple per row) (/docs/feedback-management/question-types/matrix/matrix-multiple-choice)
The **Matrix (multiple per row)** element is a **grid** of **rows** and **columns** where respondents may select **more than one column per row**—similar to **[Multiple Choice](/docs/feedback-management/question-types/choice/multiple-choice)** (“select all that apply”), but repeated for each row with the same column headers. In the form builder it appears under **Matrix** as **Matrix (multiple per row)**.
Compare with **[Matrix (single per row)](/docs/feedback-management/question-types/matrix/matrix-single-choice)**, which allows only **one** column selection per row.
## When to use [#when-to-use]
* Each row is a topic or item, and respondents may tick **several** applicable columns (for example features used, issues seen, or reasons that apply)
* You want one matrix instead of many separate multiple-choice questions with the same options
## Customization options [#customization-options]
When editing a Matrix (multiple per row) question, you can configure the following properties:
| Option | Description |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Question Text** | The main question displayed to the respondent (required). |
| **Description** | Optional helper text below the question; supports markdown (up to 500 characters in the editor). |
| **Slug** | Optional URL-friendly identifier for the question. |
| **Error Message** | The message shown when validation fails (e.g. required rows not completed, or min/max selection rules not met). Default: "Please complete this required question". |
| **Rows** | The left-hand labels in the grid. Each row has a **label** (what respondents see) and an **identifier** (stored value for that row). Use **Add row** to add rows; remove extras with the trash control when more than one row exists. |
| **Columns** | The options shown across the top (shared by all rows). Each column has a **label** and an **identifier**. Use **Add column** to add columns; remove extras with the trash control when more than one column exists. |
| **Min selections per row** | Minimum number of columns that must be selected in **each** row (0 or higher). Leave empty to clear the minimum. |
| **Max selections per row** | Maximum number of columns selectable per row. Leave empty for no explicit maximum (subject to how many columns exist). |
| **Randomize rows** | When enabled, row order is shuffled for each respondent. |
| **Randomize columns** | When enabled, column order is shuffled for each respondent. |
| **Next button label** | Label for the button that advances past this question. |
| **Text alignment** | How the question block is aligned (e.g. left or center). |
| **Required field** | When enabled, respondents must satisfy validation for every row (including any min/max rules you set) before continuing. |
| **Hidden question** | When enabled, the question can be hidden from respondents where your form logic allows. |
## Viewing responses [#viewing-responses]
Matrix (multiple per row) responses appear in the [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary) for your form. You can analyze which columns were chosen **per row**, filter by time period or segment, and compare selection patterns across rows.
# Matrix (single per row) (/docs/feedback-management/question-types/matrix/matrix-single-choice)
The **Matrix (single per row)** element presents a **grid** of **rows** and **columns**. For each row, the respondent picks **exactly one** column—like a **[Single Choice](/docs/feedback-management/question-types/choice/single-choice)** per row, but with a shared set of column options. In the form builder it appears under **Matrix** as **Matrix (single per row)**. Use it when every row needs one answer from the same column labels (for example “Poor / Fair / Good” per feature).
This differs from **[Rating matrix](/docs/feedback-management/question-types/matrix/rating-matrix)**, which applies one numeric or Likert **scale** to each statement rather than arbitrary column labels.
## When to use [#when-to-use]
* Each row is a scenario, feature, or statement, and columns are mutually exclusive answers
* You want a compact matrix instead of many separate single-choice questions
* “Pick one option per line” from a fixed column set
## Customization options [#customization-options]
When editing a Matrix (single per row) question, you can configure the following properties:
| Option | Description |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Question Text** | The main question displayed to the respondent (required). |
| **Description** | Optional helper text below the question; supports markdown (up to 500 characters in the editor). |
| **Slug** | Optional URL-friendly identifier for the question. |
| **Error Message** | The message shown when validation fails (e.g. required rows not answered). Default: "Please complete this required question". |
| **Rows** | The left-hand labels in the grid. Each row has a **label** (what respondents see) and an **identifier** (stored value for that row). Use **Add row** to add more rows. When more than one row exists, you can remove a row with the trash control. |
| **Columns** | The choices shown across the top (shared by all rows). Each column has a **label** and an **identifier**. Use **Add column** to add columns; remove extras with the trash control when more than one column exists. |
| **Randomize rows** | When enabled, row order is shuffled for each respondent. |
| **Randomize columns** | When enabled, column order is shuffled for each respondent. |
| **Next button label** | Label for the button that advances past this question. |
| **Text alignment** | How the question block is aligned (e.g. left or center). |
| **Required field** | When enabled, respondents must select one column for every row before continuing. |
| **Hidden question** | When enabled, the question can be hidden from respondents where your form logic allows. |
## Viewing responses [#viewing-responses]
Matrix (single per row) responses appear in the [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary) for your form. You can analyze selections **per row** and **per column**, filter by time period or segment, and compare how often each column is chosen for each row.
# Rating matrix (/docs/feedback-management/question-types/matrix/rating-matrix)
The **Rating matrix** element shows several **statements** (rows) that share the same **scale** (columns). Respondents rate each statement in one pass—for example agreement with multiple UX statements on one Likert or star scale. In the form builder it appears under **Matrix** as **Rating matrix**. It is faster than adding a separate **[Rating](/docs/feedback-management/question-types/scale/rating)** question for every row.
## When to use [#when-to-use]
* Several related items should use the **same** scale (satisfaction, agreement, importance)
* UX or product surveys with multiple Likert-style statements
* Any case where you want a compact grid instead of repeated rating blocks
## Customization options [#customization-options]
When editing a Rating matrix question, you can configure the following properties:
| Option | Description |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Question Text** | The main question displayed to the respondent (required). |
| **Description** | Optional helper text below the question; supports markdown (up to 500 characters in the editor). |
| **Slug** | Optional URL-friendly identifier for the question. |
| **Error Message** | The message shown when validation fails (e.g. required rows not completed). Default: "Please complete this required question". |
| **Scale** | **Likert scale** — typically two endpoints (e.g. disagree / agree), shown as radio-style choices per row. **Rating scale** — numeric/star-style scale with default labels such as Poor through Excellent (depending on point count). **Custom scale** — you define each column’s **label** (what respondents see) and **identifier** (value stored for each option). |
| **Scale points** | Number of points on the shared scale: **2**, **3**, **4**, or **5**. |
| **Scale labels** | For each column, the text respondents see. On **Custom scale**, you can also set the stored **identifier** per column (numeric or other value, depending on what you enter). |
| **Statements** | The rows to rate. Each statement has a **label** (shown in the grid) and an **identifier** (stored value for that row). Use **Add statement** to add rows (up to **10** statements). Remove extra rows with the trash control when more than one statement exists. |
| **Randomize statement order** | When enabled, the order of statement rows is shuffled for each respondent. |
| **Next button label** | Label for the button that advances past this question. |
| **Text alignment** | How the question block is aligned (e.g. left or center). |
| **Required field** | When enabled, respondents must provide a rating for each statement before continuing. |
| **Hidden question** | When enabled, the question can be hidden from respondents where your form logic allows (e.g. for prefilled or conditional flows). |
## Viewing responses [#viewing-responses]
Rating matrix responses appear in the [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary) for your form. You can analyze ratings **per statement** (row), filter by time period or segment, and view distributions across the shared scale.
# Exit form (/docs/feedback-management/question-types/panels/exit-form)
The **Exit form** is a **silent** end marker: respondents **do not** see a screen when they reach it. In the form builder it appears under **Panels** as **Exit form**. Use it as the **Go to** target in a **[Logic jumps](/docs/feedback-management/form-builder/logic-jumps)** rule when a condition should **end the form immediately** without showing a **[Thank you screen](/docs/feedback-management/question-types/panels/thank-you-screen)**.
## When to use [#when-to-use]
* Screening or branching: send disqualified or “not applicable” respondents straight to the end
* Any flow where the form should stop with **no** closing UI for that path
## Placement and limits [#placement-and-limits]
In the builder, exit forms live only in the **Thank you & Exit Section** at the end of the form (the same terminal area as thank-you screens). The product enforces:
* **At most one** Exit form per form.
* **Order:** keep **all thank-you screens before** the Exit form when both exist in that section. The Exit form should be the **last** step for paths that hit it.
## Customization options [#customization-options]
The Exit form has **no respondent-visible UI**. In the builder you configure:
| Option | Description |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Title** | Builder-only label (up to **200** characters) so you can tell exit forms apart in the outline and logic jumps canvas. Not shown to respondents. |
| **Call to action** | Optional silent action when a logic jump routes here — close, redirect, or in-app navigation. Requires **Enable call to action**. See [Call to action](/docs/feedback-management/form-builder/call-to-action). |
The list label in the builder stays **Exit form** so you can recognize the marker in the outline.
## Viewing responses [#viewing-responses]
The Exit form does **not** collect answers. Responses are still stored for questions the respondent answered **before** the jump ended the session; see the [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary).
# Message panel (/docs/feedback-management/question-types/panels/message-panel)
The **Message panel** is a **non-question** screen you can place **between** other steps. It shows a **title**, optional **markdown** body, and a **continue** button so respondents read context or instructions before going on. In the form builder it appears under **Panels** as **Message panel**.
It uses the same editor pattern as the **[Welcome Panel](/docs/feedback-management/question-types/panels/welcome-screen)** and **[Thank you screen](/docs/feedback-management/question-types/panels/thank-you-screen)**, but it is meant for **mid-flow** content (disclaimers, section intros, rich notes)—not as the opening or closing screen of the form.
## When to use [#when-to-use]
* Instructions or context before a block of questions
* Disclaimers or “please read” copy without collecting an answer
* A styled pause between sections while keeping a single continue action
## Customization options [#customization-options]
When editing a Message panel, you can configure the following properties:
| Option | Description |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Title** | Main heading on the panel (required). Up to **200** characters. You can insert variables from the picker where supported. |
| **Description** | Optional body text; **markdown** is supported (up to **500** characters in the editor). |
| **Slug** | Optional URL-friendly identifier for this panel. |
| **Next button label** | Text on the button that continues the form (required). Up to **200** characters. The default placeholder is **Next**; you can override it (for example “Continue” or “I understand”). |
| **Title & description alignment** | **Left** or **Center** for the title and description block. |
Message panels are **not** used to store structured answers; the editor keeps them non-required.
## Viewing responses [#viewing-responses]
The Message panel does **not** collect responses. Analytics and exports reflect answers from **question** elements before and after the panel; see the [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary).
# Thank you screen (/docs/feedback-management/question-types/panels/thank-you-screen)
The **Thank you screen** is the **Thank you** panel type in the form builder (**Panels** → **Thank you screen**). It is shown when someone **finishes** your feedback form. Use it to thank respondents, confirm submission, or share a short next step.
In the builder, thank-you content lives in the **Thank you & Exit Section** at the end of the form. You can only add thank-you screens there, and they must stay in that terminal section (you cannot place them in the middle of survey pages). That section can also include an optional **[Exit form](/docs/feedback-management/question-types/panels/exit-form)** after your thank-you screens—a silent end marker you can target from **[Logic jumps](/docs/feedback-management/form-builder/logic-jumps)** when a branch should end without a thank-you screen.
## When to use [#when-to-use]
* Thank people for completing the form
* Confirm that their responses were received
* Point to support, a coupon, or a follow-up link in the description (markdown)
## Customization options [#customization-options]
When editing a Thank you screen, you can configure the following properties (same editor pattern as the **Welcome screen** panel):
| Option | Description |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Title** | Main heading shown on the screen (required). Up to **200** characters. You can insert variables from the picker where supported. |
| **Description** | Optional body text below the title; **markdown** is supported (up to **500** characters in the editor). |
| **Slug** | Optional URL-friendly identifier for this panel. |
| **Next button label** | Text on the primary action button (required). Up to **200** characters. The default placeholder for thank-you screens is **Close**; you can override it (for example “Done” or “Return to app”). Used as the close button when no [Call to action](/docs/feedback-management/form-builder/call-to-action) is configured. |
| **Title & description alignment** | **Left** or **Center** for the title and description block. |
| **Call to action** | Optional post-submit behavior — button labels, in-app navigation, redirects, auto-trigger, and secondary button. See [Call to action](/docs/feedback-management/form-builder/call-to-action). |
Thank you panels are **not** treated as required “questions” in the same way as data fields; the editor keeps them non-required by design.
## Viewing responses [#viewing-responses]
The thank-you screen does not collect answers. Response data comes from the questions **before** this screen; see the [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary) for submissions and analytics.
# Welcome Panel (/docs/feedback-management/question-types/panels/welcome-screen)
The **Welcome Panel** is the first screen respondents see when they start your feedback form. Use it to set context, explain the purpose of the survey, and set expectations.
## When to use [#when-to-use]
* Introduce the feedback topic or campaign
* Show estimated time to complete
* Display branding or a short instruction
## Configuration [#configuration]
You can customize the welcome screen appearance and behavior from the **Edit Welcome Screen** dialog. The following options are available:
### Welcome Title [#welcome-title]
The main heading shown on the welcome screen. Use this to greet respondents and introduce your feedback form.
**Example:** "Welcome to our application!"
### Welcome Description [#welcome-description]
The description body shown to users. Use this to explain the purpose of the feedback form, set expectations, or provide any additional context before respondents begin.
**Example:** "We're glad you're here. This feedback will help us serve you better."
### Welcome Button Text [#welcome-button-text]
The text displayed on the welcome button that respondents click to start the feedback form.
**Example:** "Get Started"
# CSAT (Rating) (/docs/feedback-management/question-types/scale/csat-rating)
The **CSAT (Rating)** element collects customer satisfaction on a short 1-to-N scale, where N is 2, 3, 4, or 5. Respondents pick one option—emoji faces by default, or text buttons if you switch the display style. In the form builder it sits under **Scale** with **[Rating](/docs/feedback-management/question-types/scale/rating)**, **[NPS](/docs/feedback-management/question-types/scale/nps)**, and **[Opinion scale](/docs/feedback-management/question-types/scale/opinion-scale)**.
CSAT is its own question type in the form and in reporting. It is built around satisfaction scoring, not generic star or icon ratings.
## When to use [#when-to-use]
* After a support ticket, chat, or call (transactional CSAT)
* After onboarding, checkout, or another key journey moment
* Quick “How satisfied were you?” checks where emoji or labeled buttons fit better than NPS
* Pairing with a follow-up **[Long Answer](/docs/feedback-management/question-types/text/long-answer)** (for example, “What influenced your score?”)
## Customization options [#customization-options]
When editing a CSAT question in the form builder:
| Option | Description |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Question Text** | Main question shown to the respondent (required). |
| **Description** | Optional markdown helper text below the question. |
| **Error Message** | Shown when validation fails. Default: "Please complete this required question". |
| **Required field** | Respondent must pick a score before continuing. |
| **Scale** | Number of points: **2**, **3**, **4**, or **5**. 2- and 4-point scales have no neutral middle; 5-point gives the most granularity. |
| **Display Style** | **Emoji** (default) shows a face or icon per point. **Text** shows labeled buttons instead. |
| **Custom emojis** | When display style is Emoji, turn this on to pick a different emoji for each scale point. See [Custom emojis](#custom-emojis) below. |
| **Multicolor scale** | Colors low, middle (on 3- and 5-point scales), and high scores differently—similar to NPS. |
| **Negative / Neutral / Positive colors** | Customize the three sentiment colors when multicolor is on. |
| **Show labels** | Show a label under each option. Always on for text style; optional for emoji style. |
| **Scale labels** | Text for each active point (for example “Very Unsatisfied” through “Very Satisfied” on a 5-point scale). Editable per language. |
| **Next button label** | Continue button text (per language when translations are enabled). |
| **Show question title** | Toggle title visibility. |
| **Text alignment** | Alignment for title and description. |
| **Slug** | Stable identifier for integrations or exports. |
## Custom emojis [#custom-emojis]
Out of the box, each scale size uses a standard set of satisfaction faces—unhappy at the low end, happy at the high end. If those defaults do not match your brand or the moment you are measuring, turn on **Custom emojis** in the question settings.
Custom emojis only work when **Display Style** is **Emoji**. Switching to **Text** turns them off.
### How to set them up [#how-to-set-them-up]
1. Add or edit a CSAT question and leave **Display Style** on **Emoji**.
2. Enable **Custom emojis**.
3. A preview strip appears with one emoji per scale point, ordered left to right from lowest to highest satisfaction.
4. Click a point in the strip to open the emoji picker. Pick a replacement from the available categories: Unhappy, Neutral, Happy, Gestures, Hearts, Symbols, and Celebration.
5. Repeat for any other points you want to change.
Each point gets its own emoji. The picker draws from a fixed CSAT palette—you cannot paste in arbitrary characters.
If you change the **Scale** size while custom emojis are on, Encatch keeps your picks for overlapping points and fills new slots with defaults. Turning **Custom emojis** off brings back the standard faces for that scale size.
### Default emoji sets [#default-emoji-sets]
When custom emojis are off, respondents see:
| Scale | Default emojis (low → high) |
| ------- | --------------------------- |
| 2-point | 😡 😄 |
| 3-point | 😡 😐 😄 |
| 4-point | 😡 😕 🙂 😄 |
| 5-point | 😡 😕 😐 🙂 😄 |
Custom emojis change how the question looks—they do not change the score itself, which is still a number from 1 through N on an N-point scale.
## Viewing responses [#viewing-responses]
CSAT responses appear in the [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary) for your form. You can view distribution across the scale, filter by time period or segment, and track trends over time.
# Net Promoter Score (NPS) (/docs/feedback-management/question-types/scale/nps)
The **NPS** (Net Promoter Score) element measures customer loyalty by asking respondents how likely they are to recommend your product or service on a scale of 0–10.
## What is NPS? [#what-is-nps]
The NPS question type in Encatch lets you measure customer loyalty through a single, industry-standard question. When you add an NPS element to your feedback form, respondents see a 0–10 scale and answer:
> How likely are you to recommend our product or service to a friend or colleague?
Encatch records each response and surfaces the data in the [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary), so you can track loyalty over time and across segments.
## How NPS is calculated [#how-nps-is-calculated]
Encatch uses the standard NPS methodology: responses are grouped into three buckets:
* **Detractors (0–6)** — Unlikely to recommend; may share negative experiences.
* **Passives (7–8)** — Satisfied but not enthusiastic; unlikely to actively promote.
* **Promoters (9–10)** — Highly likely to recommend; strong advocates.
The score is derived by subtracting the share of Detractors from the share of Promoters:
```
NPS = % Promoters – % Detractors
```
Scores range from -100 (everyone is a Detractor) to +100 (everyone is a Promoter).
## When to use [#when-to-use]
* Measure overall satisfaction and loyalty
* Track NPS over time or by segment
* Follow up with a qualitative question (e.g. "Why did you choose this score?")
* Compare feedback across user segments (e.g. plan type, region, lifecycle stage)
## Configuration [#configuration]
The NPS methodology is based on a standardized 0–10 scale. In Encatch, you can customize the question to fit your context:
| Option | Description |
| ------------------ | ------------------------------------------------------------------- |
| **Question title** | The main question text (e.g. "How likely are you to recommend us?") |
| **Description** | Optional helper text or context below the question |
| **Min label** | Label for 0 (default: "Not at all likely") |
| **Max label** | Label for 10 (default: "Extremely likely") |
| **Required** | Whether the question must be answered before submission |
## Viewing NPS results [#viewing-nps-results]
NPS responses appear in the [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary) for your form. For NPS questions, you can:
* View **average score** and **distribution** across the 0–10 scale
* Filter by **time period**, **user segment**, or **response value**
* Track **trends** over time
* Segment results by user attributes (e.g. subscription plan, region)
Consider adding a follow-up question (e.g. a [Long Answer](/docs/feedback-management/question-types/text/long-answer) such as "What could we improve?") after the NPS question to capture qualitative feedback from detractors or promoters.
# Opinion Scale (/docs/feedback-management/question-types/scale/opinion-scale)
The **Opinion scale** element collects a single value from a horizontal row of numbered buttons. The range is more flexible than NPS: you choose whether the scale starts at **0** or **1**, and how many **steps** (points) it has.
## When to use [#when-to-use]
* Agreement, likelihood, or satisfaction when you need a custom range (for example 1–5, 1–7, or 0–10)
* When NPS’s fixed 0–10 wording does not fit your survey
## Customization options [#customization-options]
When editing an Opinion scale question, you can configure the following properties:
| Option | Description |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Question Text** | The main question shown to the respondent (required). |
| **Description** | Optional markdown helper text below the question. |
| **Error Message** | Message shown when validation fails (for example if the question is required). |
| **Required field** | Respondent must pick a value before continuing. |
| **Start value** | **0** or **1** — the lowest number on the scale. |
| **Steps** | Number of points on the scale: **5** through **11**. The visible range is *start* through *start + steps − 1* (for example start 0 and 11 steps → 0–10). |
| **Minimum / Maximum labels** | Optional text at the low and high ends of the scale. |
| **Next button label** | Label for the continue action (per language when translations are enabled). |
| **Show question title** | Toggle visibility of the question title. |
| **Text alignment** | Alignment for title and description. |
| **Slug** | Stable identifier for integrations or exports. |
| **Secondary settings** | Validations and visibility rules where supported. |
## Viewing responses [#viewing-responses]
Scale responses appear in the [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary) for your form, alongside other quantitative questions.
For form-wide controls such as numbering and default button labels, see [Other Fields Configuration](/docs/feedback-management/question-types/other-fields-configuration).
# Rating (/docs/feedback-management/question-types/scale/rating)
The **Rating** element collects feedback on a scale, such as stars (e.g. 1–5), hearts, emojis, or other visual icons. Use it when you want a quick, visual scale instead of NPS or single choice.
## When to use [#when-to-use]
* Satisfaction, quality, or likelihood ratings
* When you want a quick, visual scale instead of NPS or single choice
## Customization options [#customization-options]
When editing a Rating question, you can configure the following properties:
| Option | Description |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Question Text** | The main question displayed to the respondent (required). |
| **Description** | Optional helper text or context below the question (up to 100 characters). |
| **Error Message** | The message shown when validation fails (e.g. required field not filled, invalid selection). Keep it clear and actionable for better user experience. Default: "Please complete this required question". |
| **Required field** | When enabled, the respondent must select a rating before submitting the form. |
| **Show labels** | When enabled, displays the minimum and maximum rating labels (e.g. "Poor" and "Excellent") at the ends of the scale. |
| **Minimum Rating Label** | The label shown for the lowest rating value (e.g. "Poor"). |
| **Maximum Rating Label** | The label shown for the highest rating value (e.g. "Excellent"). |
| **Number of Ratings** | The number of rating points on the scale (default: 5). |
| **Display Style** | The icon type used for the rating scale: **Star**, **Emoji**, **Heart**, **Diamond**, or **Thumbs Up**. |
| **Size of Rating Icons** | The size of the rating icons: **Small**, **Medium**, or **Large** (default: Medium). |
## Viewing responses [#viewing-responses]
Rating responses appear in the [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary) for your form. You can view them as charts, filter by time period or user segment, and track trends over time.
If you add the question from the builder as **[CSAT (Rating)](/docs/feedback-management/question-types/scale/csat-rating)**, it is still a Rating question in the form and in reporting—the name only helps you pick a satisfaction-oriented block from the **Scale** group.
# Date (/docs/feedback-management/question-types/text/date)
The **Date** element collects a structured date from respondents. You control how segments are ordered, which separator is used, whether **time** is included, and optional **minimum** and **maximum** dates.
## When to use [#when-to-use]
* Birth dates, deadlines, booking preferences, or any calendar-based answer
* When you need a consistent format instead of free-text dates
## Customization options [#customization-options]
### Format and display [#format-and-display]
| Option | Description |
| ---------------- | ------------------------------------------------------------------------------------ |
| **Date format** | **DD/MM/YYYY**, **MM/DD/YYYY**, or **YYYY/MM/DD**. |
| **Separator** | **/**, **-**, or **.** — applied in the displayed format string. |
| **Include time** | When enabled, respondents can also provide a time with the date. |
| **Placeholder** | Hint text in the input (per language). |
### Segment labels [#segment-labels]
| Option | Description |
| ------------------------------------- | ------------------------------------------------------------------------------ |
| **Day / Month / Year segment labels** | Accessible labels for each segment (defaults: Day, Month, Year). Translatable. |
### Bounds [#bounds]
| Option | Description |
| ---------------- | --------------------------------------- |
| **Minimum date** | Earliest selectable date (date picker). |
| **Maximum date** | Latest selectable date. |
### Common question fields [#common-question-fields]
**Question text**, **description** (markdown), **error message**, **required**, **next button label**, **show question title**, **text alignment**, **slug**, and **secondary settings** (validations, visibility) follow the same patterns as other elements.
## Viewing responses [#viewing-responses]
Date answers flow into [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary) with your other structured fields.
See [Other Fields Configuration](/docs/feedback-management/question-types/other-fields-configuration) for form-wide display and button defaults.
# Long Answer (/docs/feedback-management/question-types/text/long-answer)
The **Long Answer** element lets respondents provide detailed, multi-line text responses (e.g. comments, suggestions, or open-ended feedback). Use it when you need richer qualitative input—such as "Please describe your overall experience using this application. What works well and what could be improved?"—that goes beyond short answers.
## When to use [#when-to-use]
* Open-ended feedback, comments, or suggestions
* Detailed qualitative responses that require more than a few words
* When you want respondents to elaborate on their experience
## Customization options [#customization-options]
When editing a Long Answer question, you can configure the following properties:
| Option | Description |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Question Text** | The main question displayed to the respondent (required). |
| **Description** | Optional helper text or context below the question (up to 100 characters). |
| **Placeholder Text** | The hint text shown in the text area before the respondent types (e.g. "Enter your answer here"). |
| **Error Message** | The message shown when validation fails (e.g. required field not filled). Keep it clear and actionable for better user experience. Default: "Please complete this required question". |
| **Required field** | When enabled, the respondent must provide an answer before submitting the form. |
| **Minimum Characters** | The minimum number of characters the respondent must enter. Leave empty for no minimum. |
| **Maximum Characters** | The maximum number of characters allowed in the response. Default: 5000. |
| **Number of Rows** | The initial visible height of the text area (number of rows). Default: 4. |
| **Enable AI Response Enhancement** | When enabled, AI can enhance or refine the respondent's answer. |
## Viewing responses [#viewing-responses]
Long answer responses appear in the [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary) for your form. You can view them as text, filter by time period or user segment, and export for further analysis.
# Number (/docs/feedback-management/question-types/text/number)
The **Number** element collects a single numeric value. You can allow **decimals** and **negative** values, set **minimum** and **maximum**, add a short **unit** label (for example `%` or `kg`), and optionally **pre-fill** the field.
## When to use [#when-to-use]
* Quantities, scores, percentages, ages, or any answer that must be numeric
* When validation should reject non-numeric input
## Customization options [#customization-options]
| Option | Description |
| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| **Question Text** | Main question (required). |
| **Description** | Optional markdown. |
| **Placeholder** | Hint inside the input (per language). |
| **Error Message** | Shown when validation fails. |
| **Required field** | Value must be present and valid before submit. |
| **Minimum value** / **Maximum value** | Optional inclusive bounds. |
| **Allow decimals** | Permits fractional values (placeholder text in the editor adapts). |
| **Allow negative values** | Permits values below zero when bounds allow. |
| **Unit** | Short suffix next to the field (max **10** characters). |
| **Pre-filled value** | Optional default number shown to the respondent (respects decimal vs integer mode). |
| **Next button label**, **Show question title**, **Text alignment**, **Slug** | Standard chrome. |
| **Secondary settings** | Validations and visibility where supported. |
## Viewing responses [#viewing-responses]
Numeric responses appear in reporting alongside other fields; see [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary).
For global form options, see [Other Fields Configuration](/docs/feedback-management/question-types/other-fields-configuration).
# Short Answer (/docs/feedback-management/question-types/text/short-answer)
The **Short Answer** element captures a single line of text (e.g. name, email, or a brief reply). Use it when you need a concise, one-line response that you can validate and optionally enhance with AI.
## When to use [#when-to-use]
* Email, name, or short open-ended answers
* When you need a concise, one-line response
* When you want to enforce character limits or regex validation
## Customization options [#customization-options]
When editing a Short Answer question, you can configure the following properties:
| Option | Description |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Question Text** | The main question displayed to the respondent (required). |
| **Description** | Optional helper text or context below the question (up to 100 characters). |
| **Placeholder Text** | The hint text shown inside the input field before the respondent types (e.g. "Enter your answer here"). |
| **Error Message** | The message shown when validation fails (e.g. required field not filled, invalid selection). Keep it clear and actionable for better user experience. Default: "Please complete this required question". |
| **Required field** | When enabled, the respondent must provide an answer before submitting the form. |
| **Minimum Characters** | The minimum number of characters the respondent must enter. Leave empty for no minimum. |
| **Maximum Characters** | The maximum number of characters allowed (e.g. 200). Responses exceeding this limit will fail validation. |
| **Enable Regex Validation** | When enabled, you can apply custom regex patterns to validate the response format (e.g. email, phone number). |
| **Enable AI Response Enhancement** | When enabled, AI can enhance or refine the respondent's answer before it is stored. |
## Viewing responses [#viewing-responses]
Short answer responses appear in the [Response Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary) for your form. You can view them as text, filter by time period or user segment, and track trends over time.
# Channel Distribution (/docs/feedback-management/reports-and-export/charts/channel-distribution)
## Channel Distribution [#channel-distribution]
This report shows how your feedback is distributed across different **channels**, such as web, mobile web, iOS, Android, and other platforms.
### What You'll See [#what-youll-see]
* **Channel breakdown** — Percentage or count of views and submissions per channel
* **Comparison** — How each channel performs relative to others
### Use Cases [#use-cases]
* Understand which platforms drive the most feedback
* Prioritize improvements for high-traffic channels
* Identify channels with low engagement for targeted optimization
# Country Distribution (/docs/feedback-management/reports-and-export/charts/country-distribution)
## Country Distribution [#country-distribution]
This report shows how feedback is distributed across **countries**, based on user location or IP-derived geography.
### What You'll See [#what-youll-see]
* **Country breakdown** — Percentage or count of views and submissions per country
* **Top regions** — Which countries account for the most feedback
### Use Cases [#use-cases]
* Understand your audience's geographic spread
* Identify regional differences in engagement
* Plan region-specific campaigns or localization
# Engagement (/docs/feedback-management/reports-and-export/charts/engagement)
## Engagement [#engagement]
The Engagement report provides metrics on how users interact with your feedback forms, including view-to-submission conversion and completion rates.
### Key Metrics [#key-metrics]
* **Conversion rate** — Percentage of views that result in a submission
* **Completion rate** — Percentage of started forms that are fully completed
* **Drop-off points** — Where users abandon forms before submitting
### Use Cases [#use-cases]
* Identify forms with low conversion and optimize them
* Understand user behavior and friction points
* Compare engagement across different forms or segments
# Language Distribution (/docs/feedback-management/reports-and-export/charts/language-distribution)
## Language Distribution [#language-distribution]
This report shows how feedback is distributed across the **languages** your users have configured or that are detected from their environment.
### What You'll See [#what-youll-see]
* **Language breakdown** — Percentage or count of views and submissions per language
* **Top languages** — Which languages account for the most feedback
### Use Cases [#use-cases]
* Understand your audience's language mix
* Prioritize localization for high-volume languages
* Identify underserved language segments
# Submissions by Time (Daily) (/docs/feedback-management/reports-and-export/charts/submissions-by-time-daily)
## Submissions by Time (Daily) [#submissions-by-time-daily]
This report shows the number of **submitted** feedback responses on a daily basis. A submission is counted when a user completes and submits a feedback form.
### What You'll See [#what-youll-see]
* **Daily submission counts** — How many responses were received each day
* **Trend over time** — Whether submission volume is increasing, decreasing, or stable
* **Date range filtering** — Filter by custom date ranges to focus on specific periods
### Use Cases [#use-cases]
* Track response volume and completion rates over time
* Compare submission volume before and after campaigns or product changes
* Identify peak periods for user feedback
# Views by Time (Daily) (/docs/feedback-management/reports-and-export/charts/views-by-time-daily)
## Views by Time (Daily) [#views-by-time-daily]
This report shows the number of times your feedback forms were **viewed** on a daily basis. A view is counted when a form is displayed to a user, whether or not they submit a response.
### What You'll See [#what-youll-see]
* **Daily view counts** — How many times forms were shown each day
* **Trend over time** — Whether view volume is increasing, decreasing, or stable
* **Date range filtering** — Filter by custom date ranges to focus on specific periods
### Use Cases [#use-cases]
* Track form visibility and reach over time
* Compare view volume before and after campaigns or product changes
* Identify seasonal patterns in form exposure
# External Insights (/docs/feedback-management/reports-and-export/feedback-studio/external-insights)
## Introduction [#introduction]
External Insights transforms your feedback data into actionable insights with powerful analytics. Whether your feedback comes from app stores, play stores, product reviews, YouTube comments, Instagram comments, or any other source, you can import it and start analyzing immediately. The feature supports any CSV or JSON file, so you are never locked into a single platform or format.
Think of External Insights as your AI-powered feedback analyst. Instead of manually sifting through spreadsheets or writing custom scripts, you upload your data, ask questions in plain English, and receive clear answers with charts and summaries. The system uses DuckDB to run analytical queries directly on your device, which means your raw data stays local and private while you still get the full power of AI-driven analysis.
***
## Benefits [#benefits]
**Turn any feedback source into insights.** External Insights accepts CSV and JSON files from virtually anywhere. App store reviews, social media comments, survey exports, support tickets, NPS responses, or custom feedback dumps from your own tools—all of these can be loaded and analyzed in one place. You no longer need separate workflows for each platform.
**AI-powered analytics without the complexity.** You do not need to write SQL or learn a BI tool. Simply describe what you want to know in natural language. For example, you might ask for a dashboard on feedback categories for the last month, or a breakdown of ratings by feature area. The AI translates your questions into queries, runs them locally via DuckDB, and returns aggregated results. Charts and summaries appear in a live report panel as you ask questions, and the report builds up dynamically.
**Data privacy by design.** Your feedback data is loaded and processed on your device. Only aggregated results (summaries, counts, averages) are sent to the server for AI summarisation. Granular, row-level data stays local unless you explicitly ask the AI for specific details. This makes External Insights suitable for sensitive feedback and environments with strict data policies.
**Beautiful, shareable reports.** Once you are satisfied with the analysis, you can ask the AI to generate a report in HTML format. The report is self-contained and responsive, so it works on desktop, tablet, and mobile. You can save it as a file, share it with your team, or reuse the visuals for slides by taking screenshots. The HTML is editable, so you can tweak it further in any editor if needed.
**No pipelines or setup.** External Insights is ideal for ad-hoc analysis, board presentations, quarterly reviews, or quick explorations. There is no need to spin up a data pipeline, configure a warehouse, or wait for scheduled reports. Upload your file, start a conversation with the AI, and get insights in minutes.
***
## How to Use External Insights [#how-to-use-external-insights]
### Step 1: Open External Insights [#step-1-open-external-insights]
In the encatch admin, go to **Feedback Studio** in the left navigation. Expand the Feedback Studio section and select **External Insights**. You will see the welcome screen with the upload area and a brief overview of the three-step workflow: upload your data, analyze it with AI, and generate visualizations.
### Step 2: Upload Your Feedback Data [#step-2-upload-your-feedback-data]
Use the upload area to add your CSV or JSON file. You can drag and drop the file into the dashed box or click **Browse files** to select it from your computer. Files up to 50 MB are supported. Once uploaded, the file name and size will appear, and you can remove it with the trash icon if you need to switch to a different dataset.
If you want to explore the feature without your own data, use the **Sample data** button to load example feedback. This is useful for first-time users or demos.
### Step 3: Verify the Loaded Data [#step-3-verify-the-loaded-data]
After uploading, the system loads your data on your device. Take a moment to verify that the sample or preview looks correct. This ensures the columns and structure match what you expect before you start asking questions.
### Step 4: Start a Conversation with the AI [#step-4-start-a-conversation-with-the-ai]
In the message input area, type your question or request in plain English. For example, you might ask to create a dashboard for your presentation on the various categories of feedback from the uploaded data for the last month. Messages are processed in real time, so you will see responses and visualizations appear as the AI works.
You can ask for specific types of analysis, such as a bar-plus-line combo showing platform breakdown (feedback count as bars, average rating as line), or any other visualization that helps you understand your data. The AI will aggregate the data, run the appropriate queries, and present the results.
### Step 5: Build Your Report [#step-5-build-your-report]
As you ask questions, the AI adds charts and summaries to a live report panel. You can refine your analysis by asking follow-up questions or requesting additional data points. Once you are satisfied, ask the AI to generate the final report in HTML format.
### Step 6: Save and Share [#step-6-save-and-share]
The generated report is a standalone HTML file. Open it in any modern browser—it is responsive for desktop, tablet, and mobile. You can save it to your computer, email it to your team, or modify it further in any HTML editor. If you need visuals for slides or documents, take screenshots of the charts, or keep the interactive HTML as a live artifact for deeper exploration.
***
## Example Use Cases [#example-use-cases]
**Analyze feedback from social and review platforms.** You might have reviews from app stores, play stores, YouTube comments, Instagram comments, Glassdoor, or Twitter. Export that data to CSV or JSON and load it into External Insights to identify themes, sentiment trends, and areas for improvement.
**Go beyond standard encatch reports.** If the built-in encatch reports do not answer your questions, export your encatch data to CSV and analyze it with External Insights. You can slice the data by custom dimensions, time windows, or categories that are not available in the default dashboards.
**Ad-hoc analysis for presentations.** When you need quick insights for a board meeting, product review, or stakeholder update, External Insights lets you upload your latest feedback export and generate a tailored dashboard in minutes, without waiting for scheduled reports or setting up new pipelines.
# Private Insights (/docs/feedback-management/reports-and-export/feedback-studio/private-insights)
## Introduction [#introduction]
Private Insights lets you analyze and explore your feedback data using AI that runs entirely on your own device. Unlike cloud-based AI tools that send your data to external servers, Private Insights keeps everything local. Your feedback data is stored on your machine, and the Large Language Model (LLM) that powers the analysis runs in your browser. No API calls are made for data processing, which means your sensitive feedback never leaves your computer.
Think of Private Insights as a confidential analyst sitting on your desk. You provide the data, choose the AI model that runs locally, and ask questions in plain English. The AI analyzes your feedback, identifies patterns, and answers your questions—all without sending a single byte of data over the network. This makes Private Insights ideal for teams working with confidential feedback, internal product discussions, or any scenario where data privacy is non-negotiable.
***
## Benefits [#benefits]
**Complete data privacy.** The most important benefit of Private Insights is that your data never leaves your device. Everything—from the raw feedback you load to the AI analysis—happens locally in your browser. There are no API calls for data processing, no server logs, and no retention of your feedback on external systems. If you work with customer support tickets, internal surveys, or sensitive product feedback, Private Insights ensures that confidential information stays exactly where it belongs: on your machine.
**No vendor lock-in or usage limits.** Because the LLM runs on your device, you are not subject to per-request pricing, rate limits, or usage caps. You can analyze as much feedback as your machine can handle, ask as many questions as you like, and iterate on your analysis without worrying about costs or quotas. This is especially useful for teams that need to explore large feedback datasets or run repeated analyses during product planning cycles.
**Flexibility in model choice.** Private Insights supports multiple on-device LLMs, so you can pick the one that best fits your needs. If you want the simplest setup with no downloads, you can use Browser Native Chat (Chrome's built-in AI). If you need more capable analysis and have the disk space and RAM, you can choose from models like Falcon, SmolLM, TinyLlama, or DeepSeek R1 Distill. Each model has different trade-offs between speed, capability, and resource usage, so you can tailor the experience to your hardware and workload.
**Natural language analysis.** You do not need to write queries or learn a query language. Simply type your questions in plain English—for example, "Which is the common category of issue reported?" or "What are the main themes in the feedback for the Dashboard feature?" The AI reads your context data, understands the structure, and returns clear answers with explanations. You can ask follow-up questions to dig deeper, and the conversation builds on itself so you can explore your feedback iteratively.
**Works with structured feedback.** Private Insights is designed to work with structured feedback data. You can load feedback that includes fields like FeedbackID, UserID, UserType, Platform, AppVersion, FeatureArea, Rating, FeedbackText, BugReport, Screenshot, and Date. The AI uses this structure to understand your data and provide relevant insights. You can edit the data before analysis to add, remove, or refine entries, ensuring the AI has the right context for your questions.
***
## System Requirements [#system-requirements]
Before you start, make sure your machine meets the requirements for running local models. Private Insights needs a modern Chrome browser with sufficient resources to load and run an LLM on your device.
**Browser.** Use a recent version of Chrome (139 or newer). Some models, such as Browser Native Chat, rely on Chrome's built-in on-device AI capabilities, so an up-to-date browser is essential.
**Memory and storage.** Your machine should have at least 16 GB of RAM and enough free disk space for the model you choose. Smaller models like SmolLM2 360M require around 0.7 GB of disk space, while larger models like DeepSeek R1 Distill 7B need about 3.1 GB. Plan accordingly based on the model you select.
**GPU support.** For smoother performance, especially with larger models, a machine with GPU support is recommended. This helps the model run faster and reduces the load on your CPU.
For more details on Chrome's on-device models and compatibility, follow the "Learn more about Chrome on-device models" link shown on the Private Insights page.
***
## How to Use Private Insights [#how-to-use-private-insights]
### Step 1: Open Private Insights [#step-1-open-private-insights]
In the encatch admin, go to **Feedback Studio** in the left navigation. Expand the Feedback Studio section and select **Private Insights**. You will see the main page with the tagline "Analyze and explore your private feedback insights," along with an information banner explaining that data is stored on your device and no API calls are made for processing.
### Step 2: Choose an LLM [#step-2-choose-an-llm]
The first step is to select which Large Language Model will power your analysis. Click the **Select an LLM** dropdown to see the available options.
**Browser Native Chat (Chrome Browser 139+-144).** This option uses Chrome's built-in AI capabilities. It requires no download and supports up to 25,000 characters of context. It is the easiest option if you want to get started quickly and your Chrome version supports it.
**SmolLM2 360M Instruct.** A lightweight model requiring about 0.7 GB of disk space. Best for fast responses, lightweight tasks, and low-memory environments. Supports up to 15,000 characters.
**Falcon 1B.** Requires around 2.0 GB of disk space. Good for general chat, classification, and basic generation. Slightly slower than SmolLM but more capable. Supports up to 15,000 characters.
**TinyLlama 1.1B Chat.** Requires about 2.2 GB of disk space. Best for conversational agents, chatbots, and natural-sounding dialogue. Supports up to 15,000 characters.
**DeepSeek R1 Distill 7B.** Requires about 3.1 GB of disk space. Best for small-reasoning tasks and more complex analysis. Supports up to 15,000 characters.
Each model lists its disk space requirement, character capacity, and provider. Choose the one that matches your hardware and the complexity of analysis you need. Once selected, the model loads on your device and is ready for use.
### Step 3: Add or Edit Your Context Data [#step-3-add-or-edit-your-context-data]
The **Context Data** section shows the feedback data that the AI will analyze.
### Step 4: Ask Questions and Explore Insights [#step-4-ask-questions-and-explore-insights]
In the chat area, type your question in the input field. For example, you might ask "Which is the common category of issue reported on Zendesk?" or "What are the main pain points mentioned in the Dashboard feedback?" Press Enter or click the send button to submit your question.
The AI reads your context data, understands the structure, and responds with an analysis. It might identify that bug reports are the most common category, list which feedback entries support that finding, and explain its reasoning. You can ask follow-up questions to drill down—for example, "Which feature areas have the most bug reports?" or "Summarize the feedback for the Login feature."
A token counter (for example, "Tokens left: 7,600 (1,616/9,216)") shows how much of the model's context window you have used. If you want to start fresh, click **New Chat** to begin a new conversation. The AI can make mistakes, so always double-check important findings before acting on them.
### Step 5: Iterate and Refine [#step-5-iterate-and-refine]
Use the conversational interface to explore your feedback from different angles. Ask about trends, categories, severity, platform-specific issues, or any other dimension that matters to you. The more specific your questions, the more useful the answers. You can also go back to **Edit Data for analysis** to add more feedback or adjust the dataset, then continue the conversation with the updated context.
***
## Example Use Cases [#example-use-cases]
**Analyze support ticket themes.** If you export support tickets (for example, from Zendesk) into a structured format, you can load them into Private Insights and ask which categories of issues are most common, which features generate the most complaints, or what patterns appear across different user types. All of this happens locally, so sensitive ticket content never leaves your device.
**Explore internal feedback confidentially.** When your team collects internal feedback on a new feature or product direction, you can analyze it with Private Insights without sending that feedback to any external service. Ask about sentiment, recurring themes, or suggestions that appear most often, and use the answers to inform product decisions.
**Quick ad-hoc analysis during planning.** When preparing for a sprint review or product meeting, load your latest feedback export, choose an LLM, and ask targeted questions. Get a summary of what users are saying about a specific feature, identify the top issues, or compare feedback across platforms—all in a few minutes, with full privacy.
# Audience Overview (/docs/feedback-management/reports-and-export/feedback-dashboard/audience-overview)
## Audience Overview [#audience-overview]
The **Audience Overview** tab shows high-level metrics and charts for your feedback form. Use it to understand who is viewing and responding to your form over time.
### Key Metrics [#key-metrics]
Summary cards at the top display:
* **Responses** — Total number of feedback submissions received
* **Views** — Total number of times the feedback form was viewed
* **Response Rate** — Percentage of views that resulted in a submission (e.g., 33.33%)
These metrics update based on the selected date range and any applied conditions.
### Response Time Distribution [#response-time-distribution]
A chart shows how long users take to complete the form, measured in seconds. This helps you identify whether the form is easy to complete or if users are spending unusually long or short amounts of time on it.
### Views and Submissions by Time (Daily) [#views-and-submissions-by-time-daily]
This chart displays the number of views and submissions aggregated daily, helping you track engagement trends over time. Use it to spot peaks, drops, or seasonal patterns in form usage.
### Filtering [#filtering]
Use the date range selector (e.g., "Last 7 Days") and the "+ Add Condition" button to filter the data and focus on specific time periods or audience segments.
# Destinations (/docs/feedback-management/reports-and-export/feedback-dashboard/destinations)
## Destinations [#destinations]
The **Destinations** tab lets you configure where feedback data is sent when users submit responses. Use it to route feedback to integrations, webhooks, or other systems.
### What You'll See [#what-youll-see]
* **Active destinations** — Integrations and endpoints currently receiving feedback
* **Configuration options** — Settings for each destination (e.g., API keys, mappings)
* **Add new destinations** — Connect additional tools or services
### Use Cases [#use-cases]
* Send feedback to Slack, Discord, email, or CRM
* Trigger webhooks for custom workflows
* Integrate with analytics or data warehouses
* Ensure feedback reaches the right teams or systems
Configure destinations to ensure every response is routed to the right place for follow-up and analysis.
# Overview (/docs/feedback-management/reports-and-export/feedback-dashboard)
## Overview [#overview]
The **Feedback Dashboard** provides detailed analytics and management for each individual feedback form. Unlike the project-wide Overview dashboard, this dashboard focuses on a single feedback configuration, giving you insights into audience behavior, responses, and distribution settings.
## Data Points [#data-points]
The Feedback Dashboard includes the following sections, accessible via the top navigation tabs:
* **Audience Overview** — Key metrics (Responses, Views, Response Rate), response time distribution, and views/submissions by time
* **Responses Summary** — Aggregated summary of all responses to the feedback form
* **Individual Responses** — Browse and manage each submission individually
* **Destinations** — Configure where feedback data is sent (integrations, webhooks, etc.)
* **Shareable Links** — Create and manage links for sharing the feedback form
Use the date range selector (e.g., "Last 7 Days") and condition filters to narrow down the data. The dashboard also provides actions such as stopping feedback collection and exporting or printing reports.
## Report Views [#report-views]
* **[Audience Overview](/docs/feedback-management/reports-and-export/feedback-dashboard/audience-overview)** — Metrics, response time stats, and engagement over time
* **[Responses Summary](/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary)** — Summary of all responses
* **[Individual Responses](/docs/feedback-management/reports-and-export/feedback-dashboard/individual-responses)** — View and manage each response
* **[Destinations](/docs/feedback-management/reports-and-export/feedback-dashboard/destinations)** — Feedback routing and integrations
* **[Shareable Links](/docs/feedback-management/reports-and-export/feedback-dashboard/shareable-links)** — Manage feedback form links
# Individual Responses (/docs/feedback-management/reports-and-export/feedback-dashboard/individual-responses)
## Individual Responses [#individual-responses]
The **Individual Responses** tab lets you browse and manage each feedback submission one by one. Use it when you need to review specific answers, follow up with respondents, or export detailed response data.
### What You'll See [#what-youll-see]
* **Response list** — All submissions in a list or table format
* **Full response details** — Each answer to every question in the form
* **Metadata** — Timestamp, channel, language, country, and other attributes when available
* **Source tracking** — UTM tags and click IDs captured from the page URL when [Source Tracking](/docs/feedback-management/advanced-options/source-tracking) is enabled on the form
When **[Logic jumps](/docs/feedback-management/form-builder/logic-jumps)** are enabled for a form, open a response and switch to **Respondent path** to see only the questions that person actually visited—not the full form outline.
### Use Cases [#use-cases]
* Review and respond to specific feedback
* Identify outliers or notable submissions
* Export individual responses for analysis or CRM integration
* Filter and search responses by criteria
Use the date range and condition filters to focus on a subset of responses.
# Responses Summary (/docs/feedback-management/reports-and-export/feedback-dashboard/responses-summary)
## Responses Summary [#responses-summary]
The **Responses Summary** tab provides an aggregated view of all responses submitted to your feedback form. Use it to see trends, distributions, and high-level insights without drilling into individual submissions.
### What You'll See [#what-youll-see]
* **Aggregated data** — Totals, averages, and distributions across all responses
* **Question-level summaries** — How respondents answered each question
* **Trends over time** — How response patterns change across your selected date range
### Use Cases [#use-cases]
* Understand overall sentiment or satisfaction
* Identify common themes or patterns in feedback
* Compare response distributions across different time periods
* Export summary data for reporting or presentations
Use the date range and condition filters to narrow the summary to specific audiences or timeframes.
## Add report breakdowns [#add-report-breakdowns]
Use **Add Breakdowns** in the shared report filter bar to split the results by up to three dimensions. Choose a property from:
* **Feedback Fields** — Answers and fields captured by the form
* **Segments** — Saved audience segments
* **User traits** — Properties attached to identified users
* **Context variables** — Metadata passed when the form opens
* **Source Tracking** — Campaign fields such as `utm_source`, `utm_medium`, and `utm_campaign`
Add breakdowns in the order you want to inspect them. For example, start with a plan or account segment, then add device and campaign source to find where a change is concentrated.
You can drill into a segment as its own filtered report. Date range, conditions, and breakdown choices are shared across the supported report views, so the same scope carries as you move between them.
## Save the report view [#save-the-report-view]
When a combination of filters, breakdowns, and layout is useful more than once, save it as a [Dashboard Preset](/docs/feedback-management/reports-and-export/dashboard-presets).
# Shareable Links (/docs/feedback-management/reports-and-export/feedback-dashboard/shareable-links)
## Shareable Links [#shareable-links]
The **Shareable Links** tab lets you create and manage links for sharing your feedback form. Use it to distribute the form via email, social media, or embedded on your website.
### What You'll See [#what-youll-see]
* **Existing links** — All shareable URLs created for this feedback form
* **Link settings** — Custom slugs, expiration, or tracking parameters
* **Create new links** — Generate additional shareable URLs for different campaigns or channels
### Use Cases [#use-cases]
* Share the form via email or messaging
* Embed the form on specific pages or campaigns
* Create unique links for A/B testing or channel attribution
* Track which links drive the most responses
Manage your shareable links here to control how and where your feedback form is distributed.
# Targeting Overview (/docs/feedback-management/targeting-and-triggers/targeting)
Targeting under **Distribution → In-App** lets you decide exactly who sees your feedback form. Think of it as your audience control center—you get to choose whether your form reaches everyone or just the right people, whether they're browsing anonymously or logged in, and whether they're on mobile, desktop, or a specific country. Getting this right means better feedback quality and a smoother experience for your users.
## Why targeting matters [#why-targeting-matters]
Targeting helps you:
* **Reach the right people** — Show feedback forms to users who are most likely to give useful input (e.g., beta testers, specific segments, or new visitors).
* **Avoid feedback fatigue** — Exclude users who already saw or responded to similar forms so you don't overwhelm them.
* **Match context** — Target by language, country, or device so feedback is relevant to each user's environment.
* **Improve response quality** — Focus on the audience that matters for each campaign instead of showing forms to everyone.
## Distribution areas [#distribution-areas]
The **Distribution** area has three sections:
1. **[In-App Feedback](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback)** — Forms shown inside your app or website to visitors and logged-in users.
2. **[Link & Email](/docs/shareable-feedback/feedback-links)** — Shareable links you can send through external channels.
3. **[Advanced Options](/docs/feedback-management/advanced-options)** — Availability, response, and collection settings scoped to the applicable distribution method.
You can enable one, both, or neither, depending on how you want to collect feedback.
## Quick workflow summary [#quick-workflow-summary]
1. Open your feedback form and go to **Distribution**.
2. Decide how you want to distribute:
* **Link & Email** — Create links for external sharing.
* **In-App** — Enable In-App Feedback and configure Visitors and/or Logged-in Users.
3. For Logged-in Users, choose **All** or **Selected** (and pick segments if Selected).
4. Optionally refine with **Past Interaction**, **User Language**, **Country**, and **Device Type**.
5. Fix any validation messages (e.g., "At least one feedback must be selected") by completing the required selections.
6. Save your changes. Your form will now appear only to the users you've targeted.
# Triggers Overview (/docs/feedback-management/targeting-and-triggers/triggers)
Ever wondered *when* your feedback form should pop up—and when it shouldn't? The **Triggers** tab is your control center for exactly that. Whether you want forms to appear the moment someone lands on a page, after they complete a purchase, or only when you explicitly call for it in code, triggers give you the flexibility to collect feedback at the right moment—without annoying your users.
## Overview [#overview]
Open **Distribution → In-App → Triggers**. Here you'll find two main trigger types: **Manual Trigger** and **Automatic Trigger**. You can enable one, both, or neither—depending on how you want to collect feedback. Each trigger type has its own settings and use cases, so you can mix and match to fit your workflow.
The **Configuration overview** beside the trigger settings summarizes the active manual and automatic launch setup as you make changes.
## Trigger types [#trigger-types]
| Trigger Type | Description | Use when |
| ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **[Manual Trigger](/docs/feedback-management/targeting-and-triggers/triggers/manual-trigger)** | Show the form on demand via code—whenever you decide it makes sense. | You want full control (e.g. "Contact us" buttons, help menus, custom flows). |
| **[Automatic Trigger](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger)** | Show the form based on rules you define—no code required for the basic flow. | You want hands-off collection (e.g. after page visit, on event, after delay). |
## Why triggers matter [#why-triggers-matter]
Triggers put you in control of the feedback experience. By choosing the right combination of manual and automatic triggers, launch types, recurrence, and location rules, you can:
* **Collect feedback at the right moment** — When users are most engaged or have just completed an action.
* **Avoid survey fatigue** — Use recurrence and follow-up settings to respect user time.
* **Target specific flows** — Show forms only on checkout pages, help sections, or after key events.
* **Stay flexible** — Use manual triggers for custom flows and automatic triggers for hands-off collection.
Take a few minutes to configure your triggers—your future self (and your users) will thank you!
# Manual Trigger (/docs/feedback-management/targeting-and-triggers/triggers/manual-trigger)
The Manual Trigger lets you show your feedback form on demand—whenever you decide it makes sense. Perfect for "Contact us" buttons, help menus, or any moment where you want full control over when the form appears.
## Features and explanations [#features-and-explanations]
| Feature | Explanation |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Enable/Disable toggle** | Set Manual Trigger to **Enabled** when you want to launch the form from your application using the SDK. |
| **Feedback Configuration UUID** | A unique ID (e.g. `bf90fbce-9826-49b9-bf2c-2ec107a5bfd2`) that identifies your form. Use this with `_encatch.showForm()` to display the form programmatically. |
| **Form Slug** | A human-readable name (e.g. `customer-satisfaction-survey-2024`) that must be unique, alphanumeric lowercase with hyphens/underscores, 15–100 characters, and must start with a letter. Can be used instead of the UUID when calling `_encatch.showForm()`. |
| **showForm() method** | Call `_encatch.showForm('your-uuid-or-slug')` in your application to programmatically display the form. You can use either the Form Slug or the UUID. |
## How to use the Manual Trigger [#how-to-use-the-manual-trigger]
1. Set **Manual Trigger** to **Enabled**.
2. **Get your identifiers** — You'll see a **Feedback Configuration UUID** and a **Form Slug** field. The slug is a human-readable name that must be unique, alphanumeric lowercase with hyphens/underscores, 15–100 characters, and must start with a letter.
3. **Call the method in your app** — Use `_encatch.showForm('your-uuid-or-slug')` in your application to programmatically display the form. You can use either the Form Slug or the UUID.
# CDN / Script Tag (/docs/sdk-reference/web/installation-methods/cdn-script-tag)
The **Encatch Web SDK** (`@encatch/web-sdk`) can be loaded from jsDelivr as an IIFE bundle. Add one `
```
The IIFE build registers `_encatch` on `window`.
Always pin a specific version in the URL (for example `@1.5.2`) 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 [#initialize-the-client]
After the loader script tag, call `init()` with your publishable SDK key:
```html
```
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 [#optional-configuration]
Pass a config object as the second argument to `init()`:
```html
```
| 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 (development only) |
| `isFullScreen` | `false` | Full-viewport form without modal overlay |
| `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 [Initialize the SDK](/docs/sdk-reference/web#initialize-the-sdk) in the client reference.
***
## Identify users [#identify-users]
Encatch uses identified users for [in-app targeting](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback), [segments](/docs/segmentation/manual), and response attribution. Call `identifyUser` after `init()`:
```html
```
`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 & track users](/docs/sdk-reference/web#identify--track-users).
***
## Content Security Policy [#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:
```http
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](/docs/sdk-reference/web#content-security-policy) section in the client reference.
***
## Next steps [#next-steps]
Once installation and initialization are working, explore the full client API in the [Client Reference](/docs/sdk-reference/web) — automatic triggers, form events, pre-fill (`addToResponse`), source tracking, and session control.
# NPM Package (/docs/sdk-reference/web/installation-methods/npm-package)
The official [`@encatch/web-sdk`](https://www.npmjs.com/package/@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.
***
## Overview [#overview]
* **Package:** [`@encatch/web-sdk`](https://www.npmjs.com/package/@encatch/web-sdk)
* **Version:** 1.5.2
* **Platforms:** Web (browser)
* **Node.js:** `>= 18`
* **Repository:** [github.com/get-encatch/web-sdk](https://github.com/get-encatch/web-sdk)
- A **publishable SDK key** with your site listed under **Allowed Domains / Packages**
Never embed the publishable key's **Secret Key** in client code. Use it only on your server to generate HMAC signatures for [secure identify](/docs/sdk-reference/web#verify-identity).
***
## What you need from the Encatch dashboard [#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](/docs/settings/security/publishable-sdk-keys) and [Form Builder](/docs/feedback-management/form-builder/build-feedback-form) for details.
***
## Install the package [#install-the-package]
Navigate to your project root and install with your preferred package manager:
```bash
npm install @encatch/web-sdk
```
```bash
yarn add @encatch/web-sdk
```
```bash
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 [#initialize-the-client]
Import `_encatch` and call `init()` with your publishable SDK key as early as possible on the **client** (browser) side:
```javascript
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:
```javascript
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 [#optional-configuration]
Pass a config object as the second argument to `init()`:
```javascript
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;
},
});
```
| 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 (development only) |
| `isFullScreen` | `false` | Full-viewport form without modal overlay |
| `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 [Initialize the SDK](/docs/sdk-reference/web#initialize-the-sdk) in the client reference.
### Next.js [#nextjs]
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.
```javascript
'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. Alternatively, use `next/dynamic` with `{ ssr: false }` for components that import `@encatch/web-sdk` directly.
### Vue.js [#vuejs]
Import the package in a client-only lifecycle hook so `init()` never runs during SSR:
```javascript
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 [#astro--starlight]
For documentation sites, see the full [Astro Starlight](/docs/integrations/documentation-platforms/astro-starlight) guide — it installs `@encatch/web-sdk` and initializes the SDK in a React island with `PUBLIC_ENCATCH_SDK_PUBLISHABLE_KEY`.
***
## Identify users [#identify-users]
Encatch uses identified users for [in-app targeting](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback), [segments](/docs/segmentation/manual), and response attribution. Call `identifyUser` after `init()`:
```javascript
_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.
For `$set`, `$setOnce`, `$increment`, secure HMAC signatures (optional **Secret key** on the publishable SDK key), and full username rules, see [Identify & track users](/docs/sdk-reference/web#identify--track-users).
***
## Content Security Policy [#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:
```http
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](/docs/sdk-reference/web#content-security-policy) section in the client reference.
***
## Next steps [#next-steps]
Once installation and initialization are working, explore the full client API in the [Client Reference](/docs/sdk-reference/web) — automatic triggers, form events, pre-fill (`addToResponse`), source tracking, and session control.
# Country (/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/country)
**Country** lets you target users based on their geographic location. Show the form only to users in specific countries—useful for region-specific campaigns, compliance, or localized feedback.
## When to use [#when-to-use]
* **All** — When you want feedback from users worldwide. Use for global campaigns or when location doesn't matter.
* **Selected** — When you're running region-specific campaigns, need to comply with local regulations, or want feedback from users in particular markets.
## Options [#options]
| Option | Behavior |
| ------------ | ---------------------------------------------------------- |
| **All** | Show the form to users in any country. |
| **Selected** | Show the form only to users from the countries you select. |
## Configuration [#configuration]
1. Go to **Distribution → In-App → Targeting**.
2. Locate **Country** under the advanced targeting criteria.
3. Choose **All** or **Selected**.
4. If **Selected**, use the **Select countries...** dropdown to search and select countries. Selected countries appear as tags that you can remove with the X icon.
5. You can also add custom countries if needed.
6. If **Selected** is chosen, you must select at least one country to clear validation.
## Tips [#tips]
* **Region-specific launches** — Target users in countries where you've just launched a feature.
* **Compliance** — Restrict feedback collection to countries where you're legally allowed to collect data.
* **Combine with language** — Use Country and [User Language](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/user-language) together for highly localized campaigns.
## Related [#related]
* [User Language](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/user-language) — Target by browser or device language
* [Device Type](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/device-type) — Target by device
# Device Type (/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/device-type)
**Device Type** lets you target users based on the device they're using. Show the form on desktop only, mobile only, or specific combinations—useful when your form or campaign is optimized for certain devices.
## When to use [#when-to-use]
* **All** — When you want feedback from users on any device. Use for general campaigns or when your form works well everywhere.
* **Selected** — When you're testing a mobile-specific feature, running a desktop-only survey, or want to focus on a particular platform (e.g., native app users).
## Options [#options]
| Option | Behavior |
| ------------ | -------------------------------------------------- |
| **All** | Show the form on all device types. |
| **Selected** | Show the form only on the device types you choose. |
## Device types [#device-types]
When **Selected** is chosen, you can pick from:
### Web [#web]
| Type | Description |
| ----------- | --------------------------- |
| **Desktop** | Desktop and laptop browsers |
| **Tablet** | Tablet browsers |
| **Mobile** | Mobile browsers |
### Native [#native]
| Type | Description |
| ----------- | ---------------------- |
| **Android** | Android native apps |
| **iOS** | iOS native apps |
| **Others** | Other native platforms |
## Configuration [#configuration]
1. Go to **Distribution → In-App → Targeting**.
2. Locate **Device Type** under the advanced targeting criteria.
3. Choose **All** or **Selected**.
4. If **Selected**, select the device types where the form should appear.
## Tips [#tips]
* **Mobile-first features** — Target mobile or tablet when collecting feedback on mobile-specific UX.
* **Desktop surveys** — Use desktop only for longer surveys that work better on larger screens.
* **Native app feedback** — Target Android or iOS when you want feedback specifically from app users.
## Related [#related]
* [User Language](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/user-language) — Target by language
* [Country](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/country) — Target by geographic location
# In-App Feedback Overview (/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback)
**In-App Feedback** controls who sees the form when they're using your app or website. You can target visitors (anonymous users) and logged-in users separately, then refine with language, country, device type, and past interaction.
## What is In-App Feedback? [#what-is-in-app-feedback]
In-App Feedback is configured under **Distribution → In-App**. Unlike shareable links under **Link & Email**, In-App Feedback displays forms directly inside your application or website. Users encounter the form as they browse—whether they're anonymous visitors or logged-in users—and you control exactly who sees it.
The setup is organized into three steps: **Targeting**, **Triggers**, and **Integration**. A **Configuration overview** beside the setup updates as you make changes and summarizes both who will see the form and how it will launch.
## Core targeting options [#core-targeting-options]
| Feature | What it controls |
| ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **[Visitors](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/visitors)** | Whether anonymous (non-logged-in) users see the form |
| **[Logged-in Users](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/logged-in-users)** | Whether authenticated users see the form, and which segments to include or exclude |
## Advanced targeting criteria [#advanced-targeting-criteria]
These options apply to both Visitors and Logged-in Users and let you narrow down the audience further:
* **[Past Interaction](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/past-interaction)** — Exclude users who already saw or responded to specific feedback forms
* **[User Language](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/user-language)** — Target by browser or device language
* **[Country](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/country)** — Target by geographic location
* **[Device Type](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/device-type)** — Target by device (desktop, mobile, tablet, native apps)
## Quick workflow [#quick-workflow]
1. Open your feedback form and go to **Distribution → In-App → Targeting**.
2. Enable **In-App Feedback** and configure **Visitors** and/or **Logged-in Users**.
3. For Logged-in Users, choose **All** or **Selected** (and pick segments if Selected).
4. Optionally refine with Past Interaction, User Language, Country, and Device Type.
5. Fix any validation messages by completing required selections.
6. Save your changes.
## Tips for better targeting [#tips-for-better-targeting]
* **Start broad, then narrow** — Begin with **All** for Visitors or Logged-in Users, then add filters (language, country, device) if you need more precision.
* **Use Past Interaction to reduce fatigue** — Exclude users who already responded to similar forms so you don't ask the same people repeatedly.
* **Combine criteria** — You can use multiple filters together (e.g., English-speaking users in the US on mobile) for highly specific campaigns.
* **Check validation messages** — Red warning icons and messages indicate incomplete settings. Complete the required selections to clear them.
# Logged-in Users (/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/logged-in-users)
For users who are logged in, you can choose whether everyone sees the form or only users in specific segments. This lets you run targeted campaigns for beta testers, premium users, specific departments, or any group you've defined.
## When to use [#when-to-use]
* **Disabled** — When you only want feedback from visitors (anonymous users).
* **All** — When every logged-in user should see the form. Good for broad feedback campaigns.
* **Selected** — When you want to target specific segments (e.g., premium plan users, beta testers, users who completed a certain action).
## Options [#options]
| Option | Behavior |
| ------------ | --------------------------------------------------------------------------------------------------------------------------- |
| **Disabled** | Logged-in users will not see the form. |
| **All** | All logged-in users can see the form. |
| **Selected** | Only users in specific segments can see the form. You'll need to choose which segments to include (and optionally exclude). |
## Configuration (Selected mode) [#configuration-selected-mode]
When **Selected** is chosen:
1. **Include User Segments** — Select one or more segments. Only users in these segments will see the form.
2. **Exclude User Segments (Optional)** — Optionally exclude users in certain segments. Users in excluded segments will not see the form even if they're in an included segment.
Use the search bar in the segment dropdown to find segments quickly. If you choose **Selected** but don't pick at least one segment to include, you'll see a validation message until the configuration is complete.
## User Segmentation [#user-segmentation]
Segments are groups of users defined by attributes, behavior, or hand-picked lists. encatch supports **data-driven** segments (rules that update automatically) and **manual** segments (fixed username lists).
To create segments for targeting, see [Segmentation overview](/docs/segmentation/overview). For condition types (traits, tracked events, feedback interaction, and feedback response), see [Data-driven segments](/docs/segmentation/data-driven). To reduce overlap with users who already saw other forms, combine segment targeting with [Past Interaction](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/past-interaction).
## Related [#related]
* [Visitors](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/visitors): Target anonymous users
* [Segmentation overview](/docs/segmentation/overview): Create and manage segments
* [Data-driven segments](/docs/segmentation/data-driven): Build segments with traits, events, and feedback conditions
* [Manual segments](/docs/segmentation/manual): Hand-picked username lists
* [Past Interaction](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/past-interaction): Exclude users based on prior form activity
# Past Interaction (/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/past-interaction)
**Past Interaction** lets you control whether users who have already engaged with other feedback forms should see this one. This helps reduce feedback fatigue and ensures you're not repeatedly showing forms to the same people.
## When to use [#when-to-use]
* **All** — When you want to include everyone, regardless of past feedback activity. Use for new campaigns or when overlap doesn't matter.
* **Exclude** — When you want to avoid users who already saw or responded to specific forms. Use to prevent fatigue, run sequential campaigns, or target only fresh respondents.
## Options [#options]
| Option | Behavior |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **All** | Include everyone, regardless of past feedback activity. |
| **Exclude** | Exclude users based on their past interactions. You can choose to exclude: |
| | • **Users who saw these feedbacks** — Users who viewed specific feedback forms will not see this one. |
| | • **Users who responded to these feedbacks** — Users who submitted responses to specific feedback forms will not see this one. |
## Configuration [#configuration]
1. Go to **Distribution → In-App → Targeting**.
2. Locate **Past Interaction** under the advanced targeting criteria.
3. Choose **All** or **Exclude**.
4. If **Exclude**, select at least one feedback form for either "saw" or "responded" to complete the configuration. Otherwise, a validation message will appear.
## Tips [#tips]
* **Exclude responders** — Use "Users who responded to these feedbacks" when you want fresh respondents who haven't already given feedback on similar topics.
* **Exclude viewers** — Use "Users who saw these feedbacks" when you want to avoid users who were exposed to a form but didn't submit (e.g., to retry with a different form or message).
* **Combine both** — You can exclude both viewers and responders of different forms for fine-grained control.
## Related [#related]
* [Visitors](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/visitors): Target anonymous users
* [Logged-in Users](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/logged-in-users): Target authenticated users and segments
* [Segmentation overview](/docs/segmentation/overview): Build audiences with data-driven or manual segments
# User Language (/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/user-language)
**User Language** lets you target users based on their browser or device language. Show the form only to users whose language matches your form content, or run multilingual campaigns by targeting specific languages.
## When to use [#when-to-use]
* **All** — When your form is language-agnostic or you're using automatic translation. Use for simple feedback that doesn't depend on language.
* **Selected** — When you want to match form language to user language, run language-specific campaigns, or ensure users see content in their preferred language.
## Options [#options]
| Option | Behavior |
| ------------ | -------------------------------------------------------------------------------------------------- |
| **All** | Show the form to users regardless of language. |
| **Selected** | Show the form only to users whose browser/device language matches one of the languages you select. |
## Configuration [#configuration]
1. Go to **Distribution → In-App → Targeting**.
2. Locate **User Language** under the advanced targeting criteria.
3. Choose **All** or **Selected**.
4. If **Selected**, use the **Select languages...** dropdown to pick languages. Selected languages appear as tags that you can remove with the X icon.
5. If **Selected** is chosen, you must select at least one language to clear validation.
## Tips [#tips]
* **Match form language** — If your form is in English only, consider targeting English-speaking users to avoid confusion.
* **Localized campaigns** — Run separate forms for different languages and target each to its corresponding user language.
* **Browser vs. app** — Language is detected from the browser (web) or device (native) settings.
## Related [#related]
* [Country](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/country) — Target by geographic location
* [Device Type](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/device-type) — Target by device
# Visitors (/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/visitors)
**Visitors** are users who are not logged in. When enabled, the feedback form is shown to anonymous visitors browsing your app or website. When disabled, only logged-in users can see it (if you've enabled [Logged-in Users](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/logged-in-users)).
## When to use [#when-to-use]
* **Enabled** — Use when you want to collect feedback from anyone, including first-time visitors and users who haven't signed in. Ideal for general product feedback, onboarding surveys, or when you want maximum reach.
* **Disabled** — Use when you only want feedback from authenticated users, such as for account-specific issues, feature requests tied to user data, or when you need to identify respondents.
## Options [#options]
| Option | Behavior |
| ------------ | ----------------------------------------------- |
| **Disabled** | Anonymous visitors will not see the form. |
| **Enabled** | Anonymous visitors can see and submit the form. |
Use the information icon (ⓘ) next to each option for more details.
## Configuration [#configuration]
1. Go to **Distribution → In-App → Targeting**.
2. Locate the **Visitors** section.
3. Toggle **Disabled** or **Enabled** based on your targeting strategy.
4. Combine with [Logged-in Users](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/logged-in-users) if you want both audiences, or use one or the other.
## Related [#related]
* [Logged-in Users](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback/logged-in-users) — Target authenticated users and segments
* [Advanced targeting criteria](/docs/feedback-management/targeting-and-triggers/targeting/in-app-feedback) — Language, country, device, and past interaction
# Delayed Launch (/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/delayed-launch)
**Delayed Launch** waits a set amount of time after a user action before showing the form—giving users a moment to settle in before you ask for feedback.
## When to use [#when-to-use]
* **Session warm-up** — Show the form a few seconds after a user starts a new session.
* **Audience entry** — Wait after someone enters your target audience before prompting.
* **First-time visitors** — Delay from the user's very first visit so they can explore first.
## Configuration [#configuration]
**Launch Survey** — Enter a number and choose the unit (e.g. **5 seconds**, **2 minutes**, **1 day**).
**After the user...** — Pick when the delay starts:
* **Started a new session** — The timer begins when the user starts a new session.
* **Entered target audience** — The timer begins when the user matches your targeting rules.
* **Was seen for the very first time** — The timer begins on the user's first visit.
## Tips [#tips]
* **Avoid survey fatigue** — A short delay (3–5 seconds) often works better than showing the form immediately on page load. For instant display with no anchor, use [Immediate Launch](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/immediate-launch) instead.
* **Match the flow** — Use "Entered target audience" when you want the delay to start only after users qualify for your targeting rules.
* **Combine with recurrence** — Use [Recurrence Settings](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/recurrence-settings) to avoid showing the form too often to the same user.
## Related [#related]
* [Immediate Launch](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/immediate-launch) — Show the form right away when conditions are met
* [Recurrence Settings](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/recurrence-settings) — Control how often the form appears
* [On-Page Delay](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/on-page-delay) — Add a final delay after the launch condition is met
# Follow-Up Mode (/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/follow-up-mode)
**Follow-Up Mode** re-engages users who haven't reached the outcome you choose. Set a stop condition, a maximum number of attempts, the wait between attempts, and the total follow-up duration.
## When to use [#when-to-use]
* **Increase completion rates** — Give users another chance when they have not completed the form.
* **Choose the right endpoint** — Stop after a dismissal, a partial submission, or a completed submission.
* **Respect successful submissions** — Use **Completed** so the follow-up sequence ends after the form is submitted.
* **Control persistence** — Limit maximum attempts and add wait times to avoid being intrusive.
## Stop conditions [#stop-conditions]
| Condition | When follow-up stops |
| ---------------------- | ----------------------------------------------- |
| **Dismissed** | Stop after the user dismisses the form. |
| **Partial Submission** | Stop after the user submits a partial response. |
| **Completed** | Stop after the user completes the form. |
## Configuration [#configuration]
**Stop Condition** — Choose when to stop following up: **Dismissed**, **Partial Submission**, or **Completed**.
**Maximum Attempts** — The maximum number of times to show the form to each user. Enter a value greater than 0.
**Wait Between Attempts** — Enter a number and choose **Minutes**, **Hours**, or **Days**. This controls the pause before the next attempt.
**Stop After Duration** — Enter a number and choose **Minutes**, **Hours**, **Days**, or **Weeks**. Follow-ups end after this duration from the first attempt, even when Maximum Attempts has not been reached.
## Tips [#tips]
* **Use Completed for completion campaigns** — Keep the sequence active until the user submits, while the attempt and duration limits prevent over-messaging.
* **Use Partial Save** — Enable [Partial Save](/docs/feedback-management/advanced-options/partial-save) so users can resume where they left off when the form reappears.
* **Set reasonable limits** — Start with 2–3 attempts and enough time between them for users to return naturally.
* **Combine with Recurrence** — [Recurrence Settings](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/recurrence-settings) control the overall cadence; Follow-Up Mode handles the re-engagement logic.
## Related [#related]
* [Recurrence Settings](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/recurrence-settings) — Control how often the form appears
* [Partial Save](/docs/feedback-management/advanced-options/partial-save) — Save incomplete responses for later
# Immediate Launch (/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/immediate-launch)
**Immediate Launch** shows the feedback form as soon as the user is eligible—no waiting period. Once targeting rules match and the automatic trigger is enabled, the form is offered on the next ping (or when the SDK checks for available feedback).
## When to use [#when-to-use]
* **Instant feedback** — Collect input right when a user enters your target audience or starts a session.
* **Time-sensitive flows** — Show the form immediately after a support visit, onboarding step, or key product moment.
* **Simple auto-trigger setup** — When you do not need a delay anchor (session start, first seen, or target audience entry).
## Configuration [#configuration]
Select **Immediate** under **Choose when to launch** in the Automatic Trigger section. No additional launch settings are required—unlike [Delayed Launch](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/delayed-launch), there is no timer or "After the user..." anchor to configure.
You can still refine behavior with:
* **[On-Page Delay](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/on-page-delay)** — Add seconds after the launch condition is met.
* **[Recurrence Settings](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/recurrence-settings)** — Control how often the form is shown to the same user.
* **[Follow-Up Mode](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/follow-up-mode)** — Re-engage users who dismiss or partially complete the form.
* **[Location Restrictions](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/location-restrictions)** — Limit which pages can show the form.
## How it differs from Delayed Launch [#how-it-differs-from-delayed-launch]
| | **Immediate** | **Delayed** |
| ----------------- | --------------------------------------------------- | -------------------------------------------------------------- |
| **Timing** | Form is offered as soon as eligibility is confirmed | Form waits until a set time after a user action |
| **Configuration** | No delay fields | **Launch Survey** duration + **After the user...** anchor |
| **Best for** | Fast, in-context feedback | Giving users time to settle in before prompting |
If you want a short pause without switching launch types, use [On-Page Delay](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/on-page-delay) with Immediate launch.
## Tips [#tips]
* **Pair with targeting** — Immediate launch activates for eligible users quickly; narrow [Targeting](/docs/feedback-management/targeting-and-triggers/targeting) so only the right audience sees the form.
* **Avoid survey fatigue** — Use [Recurrence Settings](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/recurrence-settings) or a small [On-Page Delay](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/on-page-delay) if showing the form on every eligible ping feels too aggressive.
* **Need page- or event-based triggers?** — Use [Page Visit Launch](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/page-visit-launch) or [Tracked Event Launch](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/tracked-event-launch) when timing should depend on a specific URL or custom event.
## Related [#related]
* [Delayed Launch](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/delayed-launch) — Wait after a user action before showing the form
* [Automatic Trigger](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger) — All launch types and shared settings
# Automatic Trigger (/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger)
The **Automatic Trigger** shows your feedback form when your launch rules match—no `showForm()` call required. Enable it, pick a launch type, and the form appears when your conditions are met.
## What is the Automatic Trigger? [#what-is-the-automatic-trigger]
The Automatic Trigger is one of two trigger types under **Distribution → In-App → Triggers**. Unlike the [Manual Trigger](/docs/feedback-management/targeting-and-triggers/triggers/manual-trigger), which requires you to call `showForm()` in code, the Automatic Trigger displays your form when launch rules match—you configure timing and conditions in the dashboard, and the SDK handles display. You choose when and where the form appears, and the system handles the rest.
## Choose when to launch [#choose-when-to-launch]
| Launch Type | Icon | Description |
| --------------------------------------------------------------------------------------------------------------------- | ---- | ----------------------------------------------------------------------- |
| **[Immediate](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/immediate-launch)** | ▶ | Shows the form right away when the trigger condition is met. |
| **[Delayed](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/delayed-launch)** | ⏱ | Waits a set amount of time after a user action before showing the form. |
| **[Page Visit](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/page-visit-launch)** | 🌐 | Triggers when the user visits a page matching your URL rules. |
| **[Tracked Event](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/tracked-event-launch)** | 📈 | Triggers when a specific event (e.g. purchase, form submit) occurs. |
## Additional settings [#additional-settings]
These options refine *how often* and *where* the form appears:
* **[Recurrence Settings](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/recurrence-settings)** — Control how often the form appears to each user—so you don't over-survey them.
* **[Follow-Up Mode](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/follow-up-mode)** — Re-engage users who haven't completed the form.
* **[On-Page Delay](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/on-page-delay)** — Add a delay in seconds after the launch condition is met.
* **[Location Restrictions](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/location-restrictions)** — Control *where* on your site the form can appear.
## How to enable [#how-to-enable]
1. Go to **Distribution → In-App → Triggers** and expand **Automatic Trigger**.
2. Toggle the switch to **Enabled**.
3. Under **Choose when to launch**, select **Immediate**, **Delayed**, **Page Visit**, or **Tracked Event**.
4. Configure any additional settings (recurrence, follow-up, delay, location) as needed.
## Quick workflow [#quick-workflow]
1. Enable the Automatic Trigger.
2. Select a launch type (Immediate, Delayed, Page Visit, or Tracked Event).
3. Configure the launch type settings (e.g. delay time, URL rules, event name).
4. Optionally add recurrence, follow-up, on-page delay, or location restrictions.
5. Save your changes.
## Related [#related]
* [Manual Trigger](/docs/feedback-management/targeting-and-triggers/triggers/manual-trigger) — Show the form on demand via code
* [Targeting](/docs/feedback-management/targeting-and-triggers/targeting) — Control who sees your feedback forms
# Location Restrictions (/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/location-restrictions)
**Location Restrictions** control *where* on your site the form can appear. Use Include rules to specify pages where the form *should* show, and Exclude rules to hide it on specific pages—even if they match an include rule.
## When to use [#when-to-use]
* **Site-wide feedback** — Use "All Pages" to show the form everywhere, then exclude specific pages (e.g. checkout, login).
* **Targeted pages** — Use Include rules to show only on support pages, feature pages, or post-purchase flows.
* **Avoid sensitive areas** — Exclude login, payment, or admin pages where a feedback form would be inappropriate.
* **Refine Page Visit Launch** — Combine with [Page Visit Launch](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/page-visit-launch) for precise control.
## Configuration [#configuration]
**All Pages** — Toggle on to show the form on every page. When off, you must add Include rules to specify where it appears.
**Include Rules** — When "All Pages" is off, add rules to specify where the form *should* appear. Choose a condition (e.g. **Contains**, **Starts with**) and enter a URL or pattern. The form appears on pages matching *any* rule.
**No Exclusions** — Toggle on to allow the form on all included pages. When off, Exclude rules apply.
**Exclude Rules** — When "No Exclusions" is off, add rules so the form does *not* appear on certain pages—even if they match an Include rule. Exclude rules take precedence.
## Matching conditions [#matching-conditions]
The same URL matching options as [Page Visit Launch](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/page-visit-launch) are available: Equals, Starts with, Contains, Pattern match (regex), and relative path variants.
## Tips [#tips]
* **Exclude checkout and auth** — Avoid showing feedback forms on payment, login, or signup pages.
* **Use relative paths** — Keeps rules portable across staging and production.
* **Order matters for clarity** — Exclude rules override Include rules; list exclusions for pages you want to explicitly block.
* **Test edge cases** — Verify the form appears (or doesn't) on key URLs before going live.
## Related [#related]
* [Page Visit Launch](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/page-visit-launch) — Trigger on specific page visits
* [Targeting](/docs/feedback-management/targeting-and-triggers/targeting) — Control who sees the form
# On-Page Delay (/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/on-page-delay)
**On-Page Delay** waits a set number of seconds after the selected launch condition is met. Set it to **0** to show the form immediately.
## When to use [#when-to-use]
* **User orientation** — Give users a moment to understand the page before asking for feedback.
* **Smooth display** — Let the surrounding interface settle before the form appears.
* **Less interruption** — Add a short pause when immediate display would feel abrupt.
* **Immediate display** — Set to **0** when you want the form to show as soon as the trigger condition is met.
## Configuration [#configuration]
**On-page delay** — Enter the number of seconds to wait after the trigger condition is met. Set it to **0** to show immediately.
## How it differs from Delayed Launch [#how-it-differs-from-delayed-launch]
| Setting | What it controls |
| ------------------ | ------------------------------------------------------------------------------------------------------- |
| **Delayed Launch** | Starts its timer from a selected user milestone, such as session start or entering the target audience. |
| **On-Page Delay** | Adds seconds after the configured launch condition has been met. |
Both can be used together. The delayed launch condition is evaluated first, followed by the on-page delay.
## Tips [#tips]
* **Start with 2–3 seconds** — This is often enough to soften the interruption without making the form feel late.
* **Use 0 for event triggers** — When triggering on a Tracked Event (e.g. purchase), the user has already acted; a page delay may not be needed.
* **Test on slow connections** — Ensure the delay doesn't feel excessive when the page loads slowly.
## Related [#related]
* [Immediate Launch](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/immediate-launch) — Show the form right away when conditions are met
* [Delayed Launch](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/delayed-launch) — Delay from user action
* [Page Visit Launch](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/page-visit-launch) — Trigger on page visits
# Page Visit Launch (/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/page-visit-launch)
**Page Visit Launch** triggers the form when users land on pages matching your URL rules. Use it for post-checkout surveys, feature-specific feedback, support pages, or any flow where you want feedback tied to specific pages.
## When to use [#when-to-use]
* **Post-checkout surveys** — Show the form on the thank-you or confirmation page.
* **Feature-specific feedback** — Trigger on pages for a particular feature or product.
* **Support pages** — Collect feedback from users who visited help or documentation.
* **Landing pages** — Gather feedback from visitors who reached a specific campaign page.
## Configuration [#configuration]
**Add Rule** — Add page visit rules. The form triggers when the user visits a page matching *any* of these rules.
**Matching conditions** — Choose how URLs are matched:
| Condition | Description |
| ----------------------------- | ------------------------------------- |
| **Equals** | Exact URL match |
| **Starts with** | URL begins with the specified string |
| **Contains** | URL contains the specified string |
| **Pattern match (regex)** | URL matches a regular expression |
| **Relative path equals** | Path (without domain) matches exactly |
| **Relative path starts with** | Path begins with the specified string |
| **Relative path contains** | Path contains the specified string |
| **Relative pattern match** | Path matches a regular expression |
## Tips [#tips]
* **Use relative path** — When your site has multiple domains (e.g. staging vs production), relative path conditions keep rules portable.
* **Combine rules** — Add multiple rules to cover variations (e.g. `/checkout/thank-you` and `/order/confirmation`).
* **Test your regex** — If using pattern match, verify your regex against sample URLs before saving.
* **Pair with targeting** — Use [Targeting](/docs/feedback-management/targeting-and-triggers/targeting) to further narrow who sees the form on those pages.
## Related [#related]
* [Location Restrictions](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/location-restrictions) — Control where the form can appear
* [Tracked Event Launch](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/tracked-event-launch) — Trigger on specific user actions
# Recurrence Settings (/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/recurrence-settings)
**Recurrence Settings** control how often the form can appear to each user. Set a required **Show every** interval and, if needed, an optional **Stop after** duration.
## When to use [#when-to-use]
* **Reduce survey fatigue** — Show the form at most once per week (or your chosen interval).
* **Time-bound campaigns** — Use Stop After to stop showing the form after a set period (e.g. 30 days).
* **Ongoing feedback** — Leave Stop After empty to keep collecting feedback indefinitely at the set interval.
* **Post-launch feedback** — Show the form every few days for a limited time after a release.
## Configuration [#configuration]
**Show every** — Enter a number greater than 0 and choose **Minutes**, **Hours**, **Days**, **Weeks**, **Months**, or **Years**. The form will not appear to that user again until the interval has passed.
**Stop after (optional)** — Enter a number and choose a unit to limit how long recurrence continues. Leave both fields empty to keep showing the form indefinitely at the selected interval.
## Tips [#tips]
* **Balance frequency and coverage** — Shorter intervals reach users more often but can feel intrusive. Longer intervals collect feedback more gradually.
* **Combine with Follow-Up Mode** — Use [Follow-Up Mode](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/follow-up-mode) to re-engage users who dismissed or partially completed the form, while Recurrence controls the overall cadence.
* **Match your product cycle** — If users engage weekly, a 7-day interval often works well. For daily users, consider 3–5 days.
## Related [#related]
* [Follow-Up Mode](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/follow-up-mode) — Re-engage users who haven't completed the form
* [Throttling](/docs/feedback-management/advanced-options/throttling) — Limit views and responses globally or per user
# Tracked Event Launch (/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/tracked-event-launch)
**Tracked Event Launch** shows the form when users perform specific actions—like completing a purchase, submitting a form, or reaching a milestone. You define the event name in your app, and the form appears when that event occurs (optionally after a minimum count within a time period).
## When to use [#when-to-use]
* **Post-purchase feedback** — Trigger when `purchase_completed` or similar events fire.
* **Form submission follow-up** — Show the form after a user submits a contact or signup form.
* **Milestone feedback** — Collect feedback when users reach a key milestone (e.g. first project created, 10th task completed).
* **Feature adoption** — Trigger when users complete an onboarding step or use a new feature.
## Prerequisites [#prerequisites]
**Allow track for visitors** — Enable this in your project settings so that events from anonymous visitors can trigger the form. If you only need logged-in user events, you can leave this disabled.
## Configuration [#configuration]
**Event Name** — The event identifier you send from your app (e.g. `purchase_completed`, `form_submitted`). Must match exactly the event name used in your tracking code.
**Minimum Count** — How many times the event must occur before the form shows. Default is 1 (form shows on first occurrence).
**Time Period** — The window in which the minimum count must be met. For example, "user was first seen" or a custom time range.
## Tips [#tips]
* **Name events consistently** — Use clear, lowercase names with underscores (e.g. `checkout_completed`, `trial_started`).
* **Avoid over-triggering** — Use Minimum Count > 1 for events that can fire frequently (e.g. page views, clicks).
* **Document your events** — Keep a list of event names and when they fire so your team can configure triggers correctly.
* **Test before launch** — Send test events and verify the form appears as expected.
## Related [#related]
* [Page Visit Launch](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/page-visit-launch) — Trigger on page visits
* [Recurrence Settings](/docs/feedback-management/targeting-and-triggers/triggers/automatic-trigger/recurrence-settings) — Limit how often the form appears