How to ask for feedback during onboarding

Which onboarding steps are worth asking about

Ask during onboarding only where a new user has just done something or is stuck. Those two moments carry the most information. A person who has just connected their first data source can tell you whether the connection flow made sense. A person who opened the same settings page three times without saving can tell you what confused them. A person who has not done anything yet mostly has an opinion about your homepage, and that is not what onboarding feedback is for.

Start by listing the steps of your onboarding in order. Mark each one with three labels: the user has just finished it, the user can get stuck on it, and the user drops off there. Your analytics tool can show drop-off if you use one. If you do not, your support inbox usually shows which steps people ask about most.

Pick two or three steps from that list. Adding a prompt to every screen turns onboarding into a form, and people skip forms.

Put the entry point next to the step

The best place for an onboarding prompt is inside the step, next to the control the user is working with. A small link labeled "Something unclear here?" beside a confusing field gets a specific answer. The same question on a separate screen, after the user has left the flow, gets a vague one.

Use the widget without its floating button so the prompt appears only where you put it. Set data-trigger to none on the script tag, then add an element with data-escuta-open next to the step. The value preselects the type, so one link can open the form as a bug and another as an idea.

<script src="https://escutaproduto.com/widget.js" data-key="pk_your_product_key" data-trigger="none" defer></script>

<button type="button" data-escuta-open="bug">Something is not working here</button>
<button type="button" data-escuta-open="idea">Something is missing here</button>

Keep the button text short and in the user's language. The widget form is available in English and Portuguese, and it follows the browser language unless you set data-locale.

Stay out of the way of activation

Activation is the point where a new user gets their first real result. Anything that interrupts the path to that result costs more than the feedback is worth. Three rules keep onboarding prompts honest:

1. Never open a form automatically during a step. Wait for the user to click.
2. Never block the next button. The prompt is a side door, not a gate.
3. Show the same onboarding prompt once per step. Repeating it on every visit makes people feel watched.

If you want a broader question, send it later by email from your own address, after the user has reached their first result. Escuta Produto does not send automatic emails to customers, so that message is yours to write and send.

Tag each answer with the step

A message such as "this is confusing" is hard to act on without knowing where it happened. The widget saves the page URL automatically, but onboarding steps often share one URL. The step name has to travel with the feedback. Call EscutaProduto.setMetadata before the form opens.

document.querySelector("#connect-data-source").addEventListener("click", () => {
  EscutaProduto.setMetadata({ onboardingStep: "connect-data-source" });
  EscutaProduto.open({ kind: "bug" });
});

Use a stable step name, not the visible label. Labels change when someone rewrites the copy, and you want the history of answers to survive that change. Metadata can hold up to 4 KB, so a step name and a user role fit easily. Escuta Produto has no tags, so metadata, internal notes and the CSV export are how you group onboarding answers. The feedback metadata guide explains which context is worth capturing.

Read onboarding feedback as a sequence

Onboarding answers are most useful in order. Filter the inbox to one product, then read the items for one week in the order they arrived. You will often see a pattern. The same step produces confusion on Monday, a workaround shared on Tuesday and a fix request by Thursday. That sequence tells you whether a change helped, which a single message never can. Write the date of each copy or design change in an internal note on the step's items, so the next time you read them you can see which messages came before the fix and which came after.

A worked example

For example, imagine that 12 new users mention the same step, the one where they connect a data source, in their first week. Their messages use different words: "where is the key", "does this need admin access", "I could not find the button". Those are three ways of describing one missing explanation. The fix is copy near the field, not a new feature, and it should ship first.

When a step produces repeated confusion, decide whether the fix is copy, order or design. Copy fixes are cheap and should ship quickly. Order and design fixes need a planned item and a short internal note in the inbox, so the next person reading the item knows why the decision was made. The triage routine covers how to move items through those statuses.

Setting up onboarding prompts in Escuta Produto

Start with one step. Add the script tag with data-trigger set to none, add one button with data-escuta-open, and set the step metadata on click. Give the product a notification webhook so each new item reaches Slack or Discord with its type and an excerpt. Then review the step's answers once a week.

Read the widget docs before you ship, especially the options for locale and position. If your app is built with Next.js, the Next.js guide shows where the script belongs in the root layout. The notifications docs describe what each Slack or Discord message contains, so you can test the alert before real users depend on it.