Core concepts
On this page
UserReason asks for feedback inside your app. Your app supplies context and reports actions; a published survey decides what to ask, who to ask and when.
Workspaces and sites
A workspace groups your team's sites and access permissions. A site is one integration with its own public site ID, surveys, events and visitors. Initialize the SDK with the site ID. Keep development and production in separate sites so testing does not affect real visitors or responses.
A site's allowed origins can restrict which browser origins use it. Origins include the scheme, hostname and port, such as https://app.example.com. A public site ID provides no management access.
Visitors and identity
The SDK starts with an anonymous visitor. Use identify() after sign-in to associate activity with your application's account ID, and reset() on sign-out. Traits describe the visitor, such as their plan; event properties describe one occurrence, such as an export's format.
Browser-supplied IDs and traits can be changed by the visitor. Backend assertions provide verified identity and traits when targeting requires trusted facts.
Surveys and publishing
A survey combines questions and presentation with audience, triggers, sampling and frequency rules. Its management ID is the campaign ID; SDK notifications and responses use surveyId for the underlying question set.
The app calls these surveys. Existing technical names stay the same: use the userreason prompt CLI commands, the prompt_* MCP tools, and API fields such as prompt_id. In a question definition, prompt is the question text. Documentation addresses under /prompts/ also stay the same.
Creating or updating a draft does not change what visitors see. Publish makes the draft live. Pause stops delivery, resume enables it again, and archive retires it. Existing responses retain the question version that was shown.
See Your first survey for the complete flow, or Survey definition for the JSON format.
When a survey appears
| Decision | Question it answers | Example |
|---|---|---|
| Trigger | Is this a suitable moment? | After onboarding.completed |
| Audience | Does this visitor qualify? | The visitor has the pro plan |
| Sampling | Is this visitor in the selected cohort? | Ask 10% of eligible visitors |
| Frequency | Has this visitor already been asked enough? | At most one completed response |
| Display availability | Can the SDK show it now? | No other UserReason survey is open |
These checks work together. An event can be recorded even when no survey appears. A published survey can also be ineligible for the current visitor. Targeting and frequency explains each check.
Three different SDK actions
- event() reports a fact from your app and checks matching event triggers.
- show() requests one particular survey using a page-load opportunity. Its rules still apply.
- on() listens for SDK notifications such as
shown,submittedanderror.
Sending an application event and listening for an SDK notification are separate operations. A successful ready() means configuration and a visitor session loaded; it does not mean a survey should appear.