# How surveys and NPS work

> The two feedback tools under Data Platform, how respondents reach a survey by personal or public link, how an NPS survey is picked for a visitor and how often it repeats, where the answers go, and how to export them.

Releva has two ways to ask customers what they think. Both live under **Data Platform**, both store their answers as events on the customer’s profile, and both can be exported. They differ in how the question reaches the customer.

|                      | Surveys                                                                                         | NPS                                                                                                   |
| -------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| What it is           | A form with any number of questions, built in a drag-and-drop designer                          | One 0-10 question with an optional follow-up per score group                                          |
| Where it is answered | On a page hosted by Releva, opened from a link                                                  | In an overlay the Releva SDK shows on your site or in your app                                        |
| Who answers          | Customers you send a personal link to, or anyone holding the public link                        | Visitors who match the survey’s targeting and triggers                                                |
| Results              | **Statistics** per survey (one chart per question) and the **Opens** / **Submissions** counters | **Analytics** per survey: NPS Score, promoters / passives / detractors, trend, distribution, comments |
| Guides               | [Create a survey](https://releva.ai/documentation/guides/surveys/create-a-survey/)                               | [Create an NPS survey](https://releva.ai/documentation/guides/surveys/create-an-nps-survey/)                           |

## How respondents reach a survey

A survey has a **token**, a long random id. Every survey link carries it. There are two kinds of link.

### Personal links in messages

The merge tag `{{surveyLink '<token>'}}` turns into a link that is personal to the recipient: it carries the recipient’s profile id in encrypted form, so Releva knows who answered without asking for an e-mail. The merge tag list of every message editor has one ready-made entry per survey, labelled **Survey: \<name>**, with the token already filled in. Pick it in e-mails, push notifications, SMS, Viber, WhatsApp, webhooks and banners. The App Inbox text of a push notification and stories do not offer survey tags.

A survey whose **Public link (QR code)** setting is **No** can only be opened through such a personal link. Anyone who opens it without one sees an error and nothing is recorded.

### The public link and QR codes

With **Public link (QR code)** set to **Yes**, the survey also opens from a plain link without a profile in it: `https://<realm>.releva.ai/surveys?token=<token>`. The admin shows this link with a **Copy** button once the survey is saved. Print it as a QR code for your store, put it on a receipt or post it on social media.

Public respondents are anonymous. Releva gives each one a temporary identity so the open and the answer belong together. If you want to know who answered, add an e-mail or phone-number question (**Single-Line Input** with the **Email** or **Phone Number** sub-type) and switch on **Merge Email Into Profile** or **Merge Phone Number Into Profile**. Then:

* If no profile has that e-mail or phone number, it is saved on the respondent’s profile, replacing any value already there.
* If another profile already has it, the answer is attributed to that existing profile and nothing on it changes.
* An empty or unusable answer is skipped; the submission is still recorded.

With a personal link, the same merge settings update the recipient’s own profile.

### How often one person can answer

**Allowed Submissions** has two values. With **Once per link**, Releva remembers that a profile completed the survey and the survey page shows it as already completed on every later open through a personal link of that profile, in any browser. The state is kept per survey and profile, not per link: a second personal link for the same customer (for example for a second order) opens as completed too. **Multiple times** keeps no such state. The check happens on the survey page: the API itself accepts every submission it receives. On a public link there is no profile to remember, so a public respondent can answer again; the browser cookie the survey page sets after a completed answer is reset on the next open, so **Once per link** has no effect on public links at the moment.

## How an NPS survey reaches a visitor

The NPS survey is not sent anywhere. Every time the Releva SDK loads a page (or a mobile app reports a screen), Releva checks the store’s NPS surveys in the order they were created and returns the first one that passes all of these checks:

1. **Status** is **Active**.
2. Today is within the **Start date** and **End date** (**Targeting** tab). No dates means always.
3. **Platforms**: if any are ticked, the visitor’s platform (web, iOS, Android) must be among them. Untick all to target everyone.
4. **Min app** / **Max app**: the app version reported by a mobile app is within the range.
5. **Min days since first contact**: the visitor’s first visit is at least that many days ago.
6. The visitor is in one of the survey’s segments, if any were set through the API. The form has no segment field.
7. One of the **Triggers** fires: **Screen / Page View** (optionally limited with **Limit to screens (leave empty for all)** to the Personalization pages you see in the page selector of Product Blocks and Banner Blocks), **Session Count** (**Min sessions**, counted by the SDK across visits), or **Custom Event** (your site calls `Releva.trackEvent('<Event name>')`). No triggers means always.
8. Frequency: with **Until Answered** or **Once Ever**, a visitor who answered this survey before never sees it again. With every policy, including **Recurring**, a visitor who answered waits out the **Cooldown days** (default 90) before the survey can show again. The cooldown starts when the visitor answers, not when the survey is shown, so a visitor who only closed the overlay can see it again in their next session.

The SDK then waits the **Trigger delay (seconds)** (default 2) and shows the overlay, at the bottom of the page (**Bottom Sheet**) or in the middle (**Modal**). One NPS survey is shown per browser session; the session restarts after 30 minutes away from the page. Events listed in **Cancel on events** cancel a pending survey for that session. Unlike product blocks, banners and stories, the NPS survey is also shown to visitors in an A/B-test control group.

Preview a survey that is still a **Draft**, or one you already answered, by opening your shop with `?rlv_mode=debug` in the address. Debug mode ignores status, dates and frequency but keeps the targeting and trigger rules.

### What the visitor sees

The overlay shows the **Question**, a 0-10 scale with the **Scale low label** and **Scale high label**, the **Skip button** (if its label is not empty) and a close icon. After the visitor picks a score, the follow-up question for their group appears, if you set one: **Promoters (9–10)**, **Passives (7–8)** or **Detractors (0–6)**. **Submit** sends the score and the comment together; with **Follow-up comment is required** on, the button stays disabled until something is typed. Without a follow-up question, the score is sent as soon as it is clicked. The group’s thank-you message shows for two seconds and the overlay closes.

## Where the answers go

Answers are events. They show up in **Data Platform › Events** on the customer’s profile, feed the survey and NPS pages, and are what exports read.

|                | Survey                                                                                                                                                             | NPS                                                                                                                                                                                                                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| On open        | `surveyOpen` each time the survey page loads. The list card counts them as **Opens**.                                                                              | `npsImpression` when the overlay is drawn (not counted on any admin page)                                                                                                                                              |
| On answer      | `surveySubmission` with every answer, flattened so numbers are numbers and dates are dates. **Submissions** on the card, one chart per question on **Statistics**. | `npsSubmission` with the score, the category and the comment. Everything on **Analytics** and the **NPS Score** on the card. Also `npsScoreSelected`, `npsSubmitted`, `npsSkipped` and `npsDismissed` from the widget. |
| On the profile | The merged e-mail or phone number, when the merge settings are on                                                                                                  | `nps_score` (number), `nps_category` (`promoter`, `passive` or `detractor`), `nps_survey_id` and `nps_last_answered` as custom fields                                                                                  |

The NPS profile fields work in segments: a segment rule on the profile field `nps_category` equal to `detractor` gives you everyone to follow up with. See [How segments work](https://releva.ai/documentation/learn/segments/how-segments-work/).

The **NPS Score** is the share of promoters minus the share of detractors, rounded, for the answers in the selected period: 5 promoters, 2 passives and 3 detractors out of 10 give (50% − 30%) = +20. Green is 50 or more, yellow 0 to 49, red below 0.

### Two timing details

* The **Opens** and **Submissions** counters on a survey card and the NPS **Analytics** update within seconds. The survey **Statistics** page, however, counts answers up to the start of the end day of its date range, so answers from today appear there tomorrow.
* Saving a survey or an NPS survey takes effect on the next page load; there is no publish step.

## Exporting answers

Both features use the shared export form described in [How exports work](https://releva.ai/documentation/learn/exports/how-exports-work/):

* **Surveys**: select **Statistics** on a survey card, then **Export**. The form opens with **Scope** set to **Surveys** and that survey selected. **Analytics › Exports › New Export** with **Scope › Surveys** does the same for all surveys or one you pick. The CSV has one row per survey with the opens and submissions as unique profiles for the period.
* **NPS**: **Export** at the top of the NPS list opens the form with **Scope** set to **Nps Surveys** and **Selection › All**. The CSV lists every answer with the profile, the date, the score, the category and the comment.

Exports arrive by e-mail at the **Recipients**, prefilled with your own address. The survey list page itself has no **Export** button any more; use the Statistics page or the Exports page.

## Next steps

* [Create a survey](https://releva.ai/documentation/guides/surveys/create-a-survey/): Build a survey in the designer and share it with a public link or a QR code.
* [Create an NPS survey](https://releva.ai/documentation/guides/surveys/create-an-nps-survey/): Set the question, colours and triggers, activate it and read the score in Analytics.
* [Surveys and NPS API](https://releva.ai/documentation/reference/surveys/overview/): Render surveys or the NPS widget in your own front end or app.
* [Export results for a date range](https://releva.ai/documentation/guides/exports/export-results-for-a-date-range/): Receive your survey or NPS results as a CSV for a period you choose.