Trigger Engine

Triggers let you show surveys automatically in response to events that happen inside your application. This is one of ResponseDock's core differentiators — no manual sharing needed.

How It Works

1. Your app calls ResponseDock.track("event_name", payload), or the SDK emits an automatic event such as $pageview
2. The SDK sends the event to the ResponseDock API, together with the identified user or the visitor's anonymous id
3. The API evaluates the active trigger rules for that event name and environment, in priority order
4. Conditions, schedule, sampling, holdout and frequency rules decide which surveys are eligible
5. The API records a display for the first eligible survey and returns the eligible surveys
6. The SDK opens the first survey in a modal, unless another survey is already open

Tracking Events

import { ResponseDock } from 'https://survey.responsedock.com/sdk/0.2/index.js';

ResponseDock.init({
  projectKey: 'pk_live_xxxx',
});

ResponseDock.identify({
  externalUserId: currentUser.id,       // optional; anonymous visitors get a persisted anonymousId
});

// Fire a named event with context payload
ResponseDock.track('match_completed', {
  matchId: 'match_789',
  teamId:  'team_123',
  result:  'win',
  sport:   'football',
});

Every event also carries pageUrl, pagePath, pageTitle and referrer, so conditions can target pages without extra code. Values passed as the third context argument are matched as context.<key>, and identify traits as trait.<key>.

Automatic Events

The browser SDK can emit events for you. They are off by default; enable the ones you need with the autoTrack option of init() and create trigger rules for their event names:

ResponseDock.init({
  projectKey: 'pk_live_xxxx',
  autoTrack: { pageViews: true, exitIntent: true, scrollDepth: [50, 90], delaySeconds: [30] },
});

For example, a trigger on $scroll_depth with the conditions depth equals 90 and pagePath contains /blog/ asks readers who finish an article. See the browser SDK reference for details.

Creating a Trigger

1. Open Audience targeting in the dashboard sidebar
2. Click Create target
3. Pick the survey and set the event name (must match what your SDK sends)
4. Add optional conditions (e.g., result equals win)
5. Set the sample, holdout, frequency and limits
6. Choose the environment, then save

Priority and an active date window can be set through the Triggers API.

Trigger Fields

Condition Operators

equals | not_equals | contains | not_contains
greater_than | less_than | exists | not_exists
in_list | not_in_list

Frequency Rules

For ONCE_PER_CONTEXT, contextKey names an event property; matchId also finds a value sent as context.matchId. Events that don't carry the property share a single context, so the survey shows only once across all of them.

How Frequency Is Counted

Every rule is evaluated per person: the identified externalUserId when there is one, otherwise the anonymous id the browser SDK keeps for each visitor.

• Response-based rules (ONCE_PER_USER, ONCE_EVER and maxResponsesPerUser) count completed responses only. Someone who closed the survey halfway can be asked again.
• Display-based rules (cooldownSeconds, ONCE_PER_CONTEXT, ONCE_PER_X_DAYS and maxDisplaysPerUser) count displays recorded by the server. A display is recorded when /sdk/events returns a survey, so the caps hold even if the page closes before the survey loads.
• Anonymous visitors are capped by displays: their responses can't be linked to the anonymous id, so for them the response-based rules count displays instead. An anonymous visitor who has been shown a ONCE_PER_USER survey is not asked again.
• Events with neither an externalUserId nor an anonymous id cannot be capped.

Sampling and Holdouts

Each person gets a stable cohort per trigger, so the same person is always inside or outside the sample. People in the holdout never see the survey; the sample then applies to everyone else. A visitor's anonymous id is cleared by ResponseDock.reset(), after which they get a new cohort.

Multiple Surveys Matching

If multiple triggers match the same event, ResponseDock evaluates them by priority, highest first, and the SDK opens the first eligible survey. Only that survey gets a display recorded. A survey a trigger opens never replaces one that is already open.

Debugging

The debugger on the Audience targeting page evaluates an event name, user id and properties against every trigger and explains why each one would or would not show (inactive, schedule, conditions, holdout, sample or frequency). It doesn't record a display.