Surveys

Collect feedback directly on your storefront with customizable multi-question forms — NPS, ratings, multiple choice, free text. Surveys are designed in the dashboard; the tag fetches the active ones and shows the right survey when its trigger fires.

How surveys appear

On boot the tag fetches active surveys for your tenant from /analytics/surveys/active. A survey then shows when all of its targeting rules match:

• URL — the current page matches target_url_pattern (substring, or a ~regex if it starts with ~).
• Trigger — either on page view (no target_event), or right after a specific event is tracked (target_event).
• Frequency — hasn't already been shown per its frequency rule.
• Rollout — the visitor is in the rollout percentage (sticky per visitor).

Once matched, an optional delay_ms waits before showing.

Frequency

Value	Meaning
once_visitor	Show at most once per visitor (persisted in localStorage).
once_session	Show at most once per browser session.
always	Show every time the trigger fires.

Show a survey manually

Trigger any active survey by its key, regardless of targeting:

window.periscale.showSurvey("post_purchase_nps"); // returns true if found & shown

Close whatever survey is currently open:

window.periscale.dismissSurvey();

React to loaded surveys

Active surveys load asynchronously. Subscribe to know when they're ready — useful to drive a custom trigger button:

const off = window.periscale.onSurveys((surveys) => {
  console.log(`${surveys.length} surveys available`);
});
off(); // unsubscribe

Trigger on an event

Set a survey's target_event to checkout_complete, then when you track that event, the survey is evaluated automatically:

window.periscale.track("checkout_complete", { order_id: "1042" });
// → if a survey targets this event and the visitor qualifies, it appears

Question types

A survey is a sequence of questions. Each supports required, an optional description, and (for text) a placeholder / max_length.

Type	Captures	Notes
nps	0–10	Optional min_label / max_label.
rating	1–max	icon: star (default) / heart / thumb.
single_choice	one option	options: string[].
multiple_choice	array of options	Optional min_select / max_select.
short_text	string
long_text	string	max_length, multi-line.
email	string	Validated against an email pattern when required.
number	number	Optional min / max.

Theming & screens

Each survey carries its own theme — primary_color, background_color, text_color, button_label, font_family, and show_branding. Optional welcome and thank-you screens bracket the questions. Position is one of popup_br (bottom-right, default), popup_bl, modal, or inline.

Where responses go

On submit, answers are POSTed to /analytics/surveys/respond with the survey id, distinct id, fingerprint, and page URL. Submission is best-effort and silently ignores network errors.