What is feedback metadata and why does it matter?

What counts as feedback metadata?

Feedback metadata is every piece of information that describes a message but is not the message itself. The text a customer writes is the content. The page they were on, the browser they used, the time they wrote and the account they belong to are metadata.

Metadata answers the questions a reader would otherwise have to ask. Where was the customer? What were they using? Are they a paying customer or a free user? A reader who knows these things can often decide without writing back.

Which fields does the widget capture on its own?

The Escuta Produto widget collects some metadata automatically, so you do not need to write code for it:

• Page URL. The address of the page where the customer opened the form. This is often the most useful field, because it points straight at the screen.
• Browser. The user agent string, which names the browser and operating system. Use it to reproduce layout problems that only appear in one browser.
• Country. Added by the server when the message arrives, so you do not need to ask the customer for it.

These fields arrive with every message from the widget. They do not depend on whether the customer is logged in.

Which details do you send yourself?

Some metadata only your application knows. Pass it in through the JS API:

• Identity. identify({ email, name, id }) sets who the customer is. Email and name fill the form fields, and any other key, such as an account id, is stored as metadata on each message.
• Plan. A plan name in the identify call, such as plan: "team", lets you tell later whether a message came from a paying customer. The plan name is your own label, so use the same names your billing system uses.
• Feature or state. setMetadata({...}) attaches more JSON, up to 4 KB, such as the feature flag a customer was testing or the step of a wizard they were on.

The widget does not capture a device class separately. If you need one, such as mobile or desktop, send it yourself with setMetadata, rather than trying to read it from the user agent string each time.

Why does context make feedback actionable?

Context turns a claim into a case. "The export is broken" can mean a dozen things. "The export is broken" with a page URL, a browser and a plan name tells you which screen, which environment and which kind of customer to start from.

Context also helps you size the problem. If five messages come from one plan and one country, the pattern is a clue. If they come from every plan and every browser, the problem is probably in the product rather than in one setup.

Context does not replace reading the message. It gives the reading a starting point.

What should you leave out of metadata?

Metadata is easy to over-collect, and that creates a privacy and maintenance problem. Keep to a short list of fields that you will actually use.

• Do not send secrets or sensitive personal data. Passwords, card numbers and health details have no place in feedback metadata.
• Keep the key names stable. Use plan, not planName in one place and subscription in another. Stable names make it possible to read the same field across messages.
• Keep values small. The 4 KB limit on setMetadata is generous for a few fields and tight for a full copy of the user's record.

Decide which fields you need before you write the code. A list of five useful keys is worth more than twenty that nobody reads.

How do you read metadata in the inbox?

Metadata is stored on each message, so it stays with the feedback item. Use the inbox filters and text search to group similar items, and use the internal notes to record what the context revealed. The page URL and browser saved on a bug are the first things to check when you try to reproduce it.

For analysis across many messages, export the product's feedback as UTF-8 CSV and sort or filter in a spreadsheet. Check the export columns before you build a report on a metadata field, so you know which fields it contains.

How do you add metadata with Escuta Produto?

Queue an identify call with the user's details as soon as the script tag is on the page. The queue works before or after the widget script finishes loading, so your code does not have to wait for it:

window.EscutaProduto = window.EscutaProduto || { q: [] };
(window.EscutaProduto.q ||= []).push(["identify", [{ id: user.id, plan: user.plan }]]);

Call EscutaProduto.setMetadata({...}) from your app once the widget has loaded, each time the context changes, such as when a customer opens a new feature. Keep the calls small, because the limit is 4 KB of JSON.

The full list of JS API calls is in the widget documentation. For how context fits into the first step of the loop, read what in-app feedback is. For the decision that follows, see what feedback triage is.