Events & Triggers

Events are named actions that happen in your application. When tracked via the SDK, they are evaluated against your active trigger rules on the ResponseDock backend.

Event Schema

{
  event: string;           // "match_completed"
  properties?: Record<string, string | number | boolean | null>;
  context?: Record<string, string | number | boolean | null>;
  externalUserId?: string; // optional, set by identify()
  anonymousId?: string;    // persisted per browser by the SDK
  traits?: Record<string, unknown>;
  environment?: 'PRODUCTION' | 'STAGING' | 'DEVELOPMENT';
}

Trigger conditions match properties by name, context values as context.<key> and traits as trait.<key>.

Tracking Events

// Browser SDK
ResponseDock.track('match_completed', {
  matchId: 'match_789',
  sport:   'football',
  result:  'win',
});

// React SDK
const { track } = useSurvey();
track('purchase_completed', { orderId: 'ord_123', total: 59.99 });

Common Event Patterns

Use case	Event name	Key payload fields
Post-event feedback	`event_completed`	`eventId`, `eventType`
Post-purchase NPS	`purchase_completed`	`orderId`, `total`
Onboarding milestone	`onboarding_step_completed`	`step`, `totalSteps`
Support ticket closed	`ticket_resolved`	`ticketId`, `category`
Feature used	`feature_used`	`featureName`
Session ended	`session_ended`	`duration`

Automatic Events

With the browser SDK's autoTrack option, the SDK emits $pageview, $scroll_depth (depth), $time_on_page (seconds) and $exit_intent for you. Use these names in trigger rules like any other event. See Browser SDK.

SDK Event Lifecycle

App calls ResponseDock.track() or the React track() hook
SDK sends POST /api/v1/sdk/events with the event
Server evaluates all active triggers for this workspace + event name
Matching triggers return eligible surveys (respecting sampling, holdouts and frequency rules)
Server records a display of the highest-priority eligible survey for this user or visitor
SDK opens that survey in a modal, unless another survey is already open
On completion, response webhooks are dispatched

Cooldown & Deduplication

Cooldowns and frequency caps are enforced on the server. A display is recorded in the same request that returns the survey, so the caps hold even when the page is refreshed or closed before the survey loads. Response-based rules count completed responses only; display-based rules count recorded displays. Anonymous visitors are identified by the SDK's persisted anonymousId and capped by displays. See the trigger engine guide.

Debug Mode

ResponseDock.init({
  projectKey: 'pk_live_xxxx',
  debug: true,    // logs all track() calls and trigger evaluations
});