Getting started with Survicate

This guide takes a developer from a new Survicate account to a survey that collects identified responses from a website or app and delivers them to your own systems. Steps 1 and 2 apply to everyone; in step 3 pick the channel your customers use. Each step links to the reference page with the full details.

1. Before you start

• Create an account at panel.survicate.com/signup with a business email address, or accept the invitation a teammate sent you. A new account starts with a 10-day trial of the Growth plan's features and continues on the free plan afterwards; the pricing page lists what each plan includes.
• Split the work. Developers install the SDK once and pass attributes and events. From then on, whoever owns feedback creates, targets and launches surveys in the panel, with no further release needed. Agree early on the attribute and event names both sides will use; they are case-sensitive.
• Know where to get help. Support answers on the live chat in the panel and at support@survicate.com. The Help Center covers everything that happens in the panel and this site covers the code; both can be read by your AI assistant, see Docs for AI agents.

2. Find your keys

3. Install Survicate

Website or web app

Add the tracking code before the closing </body> tag of every page where a survey may appear, or install one of the npm packages. One installation serves every survey in the workspace, and the same snippet can be installed on any number of domains; which pages a survey shows on is decided by its targeting.

The snippet with your key already filled in is under Settings → Surveys → Web in the panel. The tracking code and the wrapper always load the current SDK version; the web package is a dependency you update yourself. To verify the installation, open your site and run _svc in the browser console: it prints the workspace key when the code is installed. Google Tag Manager, WordPress, Segment and Braze installations are covered on the Installation page.

Mobile app

Install the SDK for iOS, Android, React Native, Flutter or Unity, put the workspace key in the app configuration (Info.plist on iOS, AndroidManifest.xml on Android, or setWorkspaceKey in code) and initialize the SDK when the app starts. The key and the per-platform instructions are also under Settings → Surveys → Mobile in the panel. Steps 4 and 5 add user attributes, screens and events.

Email

Nothing to install. To identify the respondents of email and link surveys, add parameters to the survey link. When you pick a supported email tool in the survey's Configure step, Survicate generates the link with that tool's merge tags; with any other tool, or in your own emails, append the parameters yourself. Every parameter becomes a respondent attribute.

4. Identify respondents

Responses are anonymous until your code says who the respondent is. Pass a user_id plus the attributes you want to target or filter by, at a point where you know the user, for example after login. Attributes are cached on the device, so once is enough, and changing one may make a survey eligible immediately.

Website or web app

Set the traits in the opts.traits object before the tracking code loads, or call setVisitorTraits at any time.

The Installation page covers user identification and user attributes for each installation method; the method itself is documented under Set visitor attributes.

Mobile app

Call setUserTrait, or setUserTraits for several at once, once the SDK is initialized.

The same call exists in every SDK: iOS, Android, React Native, Flutter and Unity.

Email

Every parameter on a survey link becomes a respondent attribute, as shown in step 3: email, first_name, last_name and any custom name such as plan. When you send the survey through a supported email tool, Survicate generates the link with that tool's merge tags. For Intercom Messenger and Braze in-app message surveys, respondent identification is set up in the integration; see the Help Center articles on Intercom Messenger surveys and Braze in-app message surveys.

Attribute rules

• user_id can be any string that is unique per user. It marks the respondent as logged in, and it is required for the All logged-in users, Users and Manual audiences.
• first_name, last_name and email make a response identified in the panel; without them it is marked Anonymous.
• Values can be strings, numbers, booleans or dates (ISO 8601). Attribute names are case-sensitive, and names and values are limited to 255 characters. Strings must not contain {}, *, [], %, ~, -- or $.
• A workspace can hold up to 2,000 distinct attribute names, and an audience filter up to 50 attributes. An attribute becomes available as a filter in the Analyze tab once a response carrying it has arrived.
• Keep sensitive personal data (health, political opinions and similar) out of attributes used for targeting; stick to plan, role, company size and the like.

Sign user IDs for server-side targeting. With a Users or Manual audience, anyone who can run JavaScript on your page could pretend to be another user. To prevent it, create a secret key in the Secret Key section of Settings → Organization → Access Keys, compute an HMAC-SHA256 of the user_id with it on your server, pass the result as user_key next to user_id (in the web traits, or as a user trait in a mobile app), and turn on Enforce secret keys for logged-in user targeting. Once enforced, a user_id without a valid user_key gets no server-side targeted surveys. Details are in the Help Center article Securing surveys with secret and user keys.

5. Report events

Report the actions you want surveys to react to and, in mobile apps, the screens users move through. Event names, property names and values are case-sensitive and must match the panel exactly; property values are strings, and names are up to 255 characters.

Website or web app

Other methods you will reach for: showSurvey(surveyId) to show a specific survey regardless of its targeting (with { forceDisplay: true } even to a visitor who already answered it), closeSurvey(), retarget() to re-run targeting after an asynchronous change in a single-page app (page loads, survey completions and route changes already do), and addEventListener for the survey_displayed, question_answered, survey_completed and survey_closed events, so your app can react to answers. Wait for the SurvicateReady window event before calling methods on _sva. For a fully custom UI, hide a survey with hiddenSurveys and record answers with getSurveyPointsMetadata and submitAnswer. All of them are on the Methods and Event Listeners pages. Methods other than setVisitorTraits, and the event listeners, require a plan with JavaScript targeting.

Mobile app

Report each screen when it appears and when it disappears, so surveys can be targeted to screens, and report events the same way as on the web. Listeners for survey_displayed, question_answered, survey_completed and survey_closed are available as well.

The same calls, with the same names (PascalCase in Unity), on every platform:

• iOS: screens, events, attributes, listeners
• Android: screens, events, attributes, listeners
• React Native: screens, events, attributes, listeners
• Flutter: screens, events, attributes, listeners
• Unity: screens, events, attributes, listeners

Triggers and audiences

An event can be used in two ways. As a trigger (Target → Triggers) the survey fires the moment the event happens, and occurrence counts are kept on the device. As an audience filter on a Users audience, Survicate stores the event history per user_id on its servers, so the filter follows the user across devices; the eligibility check is cached for about five minutes, so the survey may appear with a delay.

6. Launch a survey

In the panel, whoever owns the survey does the rest, without a deployment:

1. Create new survey: start from scratch, a template, a description for the AI, or imported questions, then choose the survey type. It cannot be changed afterwards.
2. Create: add questions, branch logic, translations and the design theme. Website surveys can switch between a pop-up and the Feedback Button in the Format tab.
3. Target: choose pages (URL rules or regular expressions) or screens, a trigger (on load, after a delay, on exit intent, on an event), the audience (All visitors, All logged-in users, or a Visitors, Users or Manual audience), the frequency (once per respondent by default, or recurring), sampling and, for mobile surveys, the device language, operating system or orientation.
4. Connect: turn on integrations and Webhooks for this survey.
5. Launch: start now or on a date, optionally with an end date or a response cap.

Testing a website survey: use the panel's preview, or test live in a private browsing window, because a website survey is shown to a visitor once by default and the visitor is remembered in Local Storage. Changes to a survey take up to 15 minutes to reach visitors (a couple of minutes for mobile surveys), and server-side audiences add the five-minute cache. showSurvey(surveyId, { forceDisplay: true }) skips both the targeting and the once-per-visitor rule for a quick check.

7. Get the data out

• Webhooks: in the survey's Connect tab, add your endpoint URL and choose delivery per answer (questionAnswered) or per completed response (surveyCompleted). Use Send sample request to test. A questionAnswered delivery carries one question and its answer; a surveyCompleted delivery carries all of them in a questionsAnswered array. Both include the survey, responseUuid, timestamp, page URL and the respondent's attributes. Verify the signature with your verification token or signing secret, and allow the source IPs 3.248.104.12 and 54.171.69.70. Payloads are documented under Events and Answer types.
• Data Export API: authenticate with the API key and page through results by following next_url until has_more is false. Responses can be filtered by date range and enriched with the attributes you name in attributes[]. Limits: 5 concurrent requests and 1,000 requests per minute per workspace. Setup explains pagination and attributes; Survey, Response, Respondent and Personal Data list the endpoints.

• Integrations: for Slack, Microsoft Teams, Google Sheets, HubSpot, Salesforce, Intercom, Amplitude, Mixpanel, BigQuery and other tools, connect the integration in the panel instead of writing code; the Help Center's Connect integrations collection has the setup for each.
• Exports: CSV and XLSX from a survey's Analyze tab, and PDF or PNG charts.
• Survicate MCP: connect Claude, ChatGPT, Cursor or Slack to https://mcp.survicate.com/ to ask questions about the responses, pull scores and draft surveys with your own permissions. See Connect.

Webhooks and the Data Export API are included in the Pro and Enterprise plans; the pricing page lists what each plan includes.

Next steps