A metadata naming convention for feedback across products

Why does metadata need a convention at all?

Metadata is the context you attach to a feedback item: which user sent it, what plan they are on, which version of the app they run. Escuta Produto stores that context with each item and includes it in the CSV export, so it helps when you read one item and when you analyze a batch. The trouble starts when two products name the same thing differently. One sends userId, another sends user_id, a third sends uid. Each product's export then needs its own cleanup before you can compare them.

A convention is a short agreement about key names, value types and the set of keys every product sends. It costs an hour to write and saves a spreadsheet step every week.

Which keys should every product send?

Start with a small set of keys that answer the questions you ask most often. Four is a good number for most teams, and more keys can come later once the first four are stable:

Key	Type	Example value	Why it helps
userId	string	"u_1042"	Links feedback to the account, without sending the email again
plan	string	"team"	Shows whether a bug affects paying or free users
appVersion	string	"2.4.0"	Lets you see if one release causes more reports
locale	string	"pt-BR"	Explains language or regional problems

Keep the list the same for every product. A key that exists in one product only is a question nobody can answer in a combined export. If one product has a plan system and another does not, send plan as a fixed value such as "none" rather than leaving it out.

How should you name keys and choose their types?

Use lowerCamelCase for every key, and use the same spelling in every product. Avoid abbreviations that only one team understands, and avoid spaces and punctuation, because they make the key harder to read in a spreadsheet header. Keep values simple: strings for names and labels, and strings for version numbers too, so "2.4.0" never gets read as a decimal.

Choose a type for each key and stick to it. A plan written as "team" in one product and "Team plan" in another is two different values in a spreadsheet, and a filter will miss one of them. If a value comes from a list, such as the plan names in your billing system, use the same list in every product.

Where should the convention live?

Write the convention down in one place your team already reads, such as the repository README, a shared handbook or a pinned note in your chat. Include the key name, the type, an example value and one sentence on why the key exists. Add a line about what never to send, such as passwords, tokens or full payment details.

Put a reference to the document in the code that sends metadata, so a developer adding a new product sees it before writing a key. A convention that lives only in one person's head will drift within a month.

Review the list once a quarter, and add a key only when two or more products need the same answer. A key that only one product uses belongs in that product's own notes. Keeping the shared list short is what makes it easy to follow, and a short list is much more likely to be used in the next product's setup.

How do you send the metadata from your apps?

Identify the user once, when they sign in, and set the app version when the app loads. The identify call stores the key values as metadata, so a basic setup looks like this:

EscutaProduto.identify({
  email: user.email,
  name: user.name,
  userId: user.id,
  plan: user.plan,
  appVersion: "2.4.0",
});

For a value that changes during a session, use setMetadata. The setMetadata call accepts up to 4 KB of JSON, so keep the values short and avoid large objects:

EscutaProduto.setMetadata({ appVersion: "2.4.1" });

Mobile apps and server-side flows send the same keys through the REST API, in the metadata field of the JSON body:

curl -X POST https://escutaproduto.com/api/v1/feedback \
  -H "Content-Type: application/json" \
  -d '{"key":"pk_your_product_key","message":"Export is slow","kind":"bug","metadata":{"userId":"u_1042","plan":"team","appVersion":"2.4.0"}}'

What does metadata look like in the export?

The CSV export has one metadata column. Its value is the JSON text of everything you sent with that item, so a row might hold a single cell with userId, plan and appVersion inside it. A spreadsheet will not split that cell into separate columns on its own.

This is where the convention pays off. When every product uses the same keys, one parsing step works for all of them. You can extract appVersion from each product's export with the same formula or the same short script, then count bugs per version across the whole portfolio. Without a convention, each product needs its own parser, and the combined view is slow to build and easy to get wrong.

The inbox does not filter by metadata, and text search covers the name, email and message fields only, so the export is where metadata earns its keep. Use it for the questions the counts cannot answer, such as whether one app version produces more bugs than the rest.

Keeping metadata consistent in Escuta Produto

Set the keys in each product's code as you add the widget, and check one item from each product in the inbox to confirm the metadata arrived. Then export that product's CSV and find the metadata column to see the keys as you intended. Repeat this for each product as you add it. The widget guide covers identify, setMetadata and the other options, and the API reference shows the metadata field for mobile and server clients.

For a view of how consistent data supports the weekly routine, read a weekly feedback digest across products. For the shared experience your customers see across apps, keeping the feedback experience consistent across apps covers the matching side of the same idea.