User feedback
End users can tell you what went wrong or what they want, in their own words. Feedback is stored next to your crashes, linked to the crash it is about, tagged with sentiment and topics, and readable by agents through the REST API and the MCP server.
- Widget: a floating "Feedback" button for web and Android apps and a feedback form for iOS, macOS and tvOS, with an optional screenshot and email field.
- Crash prompt: after an uncaught error, ask "what were you doing?". The answer is linked to that crash's issue.
- API:
captureFeedback()in the SDKs, orPOST /ingest/v1/feedbackfrom anywhere. - Sentiment and topics: when an LLM is configured (
VAKA_LLM_*, see self-hosting), each item gets a sentiment, 1 to 3 topics and a one-line summary. Without an LLM, feedback works the same, untagged. - Triage: status
new,triaged,resolvedorignored, an assignee, and a link to an issue. Anew_feedbackalert trigger and a feedback block in digests.
Web widget
With the script tag, load the widget after vaka.js:
<script defer src="https://vaka.example.com/sdk/vaka.js" data-key="vk_..."></script>
<script defer src="https://vaka.example.com/sdk/vaka-feedback.js" data-crash-prompt="true"></script>
Attributes: data-button="false" (no floating button; open it yourself),
data-position="bottom-left", data-crash-prompt="true", data-screenshot="false",
data-ask-email="false", data-accent="#16a34a", data-auto="false" (don't install; call
window.VakaFeedback.installFeedback(...) yourself).
With npm:
import { init } from '@hellsoft/vaka-browser';
import { installFeedback, showFeedback } from '@hellsoft/vaka-browser/feedback';
init({ key: 'vk_...', endpoint: 'https://vaka.example.com' });
installFeedback({ crashPrompt: true, email: currentUser?.email });
// Your own "Report a problem" link:
document.querySelector('#report')!.addEventListener('click', () => showFeedback());
See the JavaScript SDK for every option. The widget lives in a shadow root, so page styles don't leak in or out.
Screenshots
The widget renders the visible part of the page to a JPEG in the browser (no extension or
permission prompt). The user sees it and can untick it before sending. Password fields and
anything marked data-vaka-mask are blacked out; canvases, videos and iframes appear as empty
boxes. Turn screenshots off with screenshot: false.
Android widget
Vaka.init(this, VakaConfig(...))
Vaka.installFeedback(VakaFeedbackOptions(crashPrompt = true))
Vaka.showFeedback(activity) // open it from your own menu item
The crash prompt appears on the first screen of the next launch after a JVM or native crash.
Screenshots skip FLAG_SECURE windows and black out password fields and views passed to
Vaka.maskInScreenshots(view). See the Android SDK for every option.
iOS, macOS and tvOS
Vaka.installFeedback(Vaka.FeedbackOptions(crashPrompt: true))
Vaka.showFeedback() // UIKit or anywhere
VakaFeedbackButton() // SwiftUI
Button("Report a problem") { show = true }.vakaFeedback(isPresented: $show)
The form opens with a screenshot of the current screen (secure text fields and .vakaMask() views blacked
out) that the user can remove, and lets them add up to 3 images. With crashPrompt, the next launch after a
crash asks what the user was doing, and so does recovering from a hang. Feedback written offline is sent later.
See the iOS SDK.
Sending feedback from code
import { captureFeedback, lastEventId } from '@hellsoft/vaka-browser';
const r = await captureFeedback({ message: 'The export button does nothing', email, eventId: lastEventId() });
// r = { id, short_id: 'WEB-F12' }
From a backend
The server SDKs have no widget. They forward feedback your users wrote in your own forms (support, contact, in-app chat), right away, with the release, environment and the request scope's user, tags and flags:
| SDK | Call |
|---|---|
| Node.js | await Vaka.captureFeedback({ message, email, issue, ip }) |
| Python | vaka.capture_feedback(message, email=..., issue=..., ip=...) |
| Go | vaka.CaptureFeedback(ctx, vaka.Feedback{Message: ..., IP: ...}) |
| Rust | vaka_sdk::capture_feedback(vaka_sdk::Feedback { .. }) |
| JVM | Vaka.captureFeedback(Feedback.of(message).email(...).ip(...)) |
| .NET | await VakaSdk.CaptureFeedbackAsync(new VakaFeedback(message) { ... }) |
- Link feedback to a crash with
eventId(the id the capture call returned) or to an issue withissue(API-12). - Pass the end user's IP address. The SDK sends it as
X-Forwarded-For, so the per-address rate limit applies to each user instead of to your server. Vaka only believes that header from trusted proxies: backends on a private network (the same Docker network, VPC or cluster) are trusted by default; add a backend that calls Vaka from a public address toVAKA_TRUSTED_PROXIES. Otherwise all feedback from that server shares one limit (raiseVAKA_FEEDBACK_PER_IP_HOURif needed). Browsers can't use the header to dodge the limit. - Up to 3 images go as a multipart upload.
- The call returns
{ id, short_id }, and fails with the HTTP status when the server refuses the feedback (429for a rate limit), so your form can tell the user.
Anything else can send it over the ingest protocol.
Limits
- Message: required, at most 5000 characters.
- Up to 3 images (PNG, JPEG or WebP), 5 MB and 4096 px per side each. EXIF data is stripped from JPEGs.
- Rate limits per project: 10 per hour per IP address and 5 per hour per session
(
VAKA_FEEDBACK_PER_IP_HOUR,VAKA_FEEDBACK_PER_SESSION_HOUR). Extra sends get429. - Retries with the same client
idare stored once.
Reading feedback
| Where | How |
|---|---|
| MCP | list_feedback, get_feedback (with screenshots as images), feedback_summary, update_feedback |
| REST | GET /api/v1/projects/{p}/feedback, GET /api/v1/projects/{p}/feedback/summary, GET / PATCH /api/v1/feedback/{id} |
| Admin UI | /ui/projects/{slug}/feedback: list with filters, detail page with screenshots and status |
Feedback also shows up where it is useful: get_issue and get_fix_context include the
feedback linked to an issue, session and user timelines include it in order, compare_releases
compares feedback volume and sentiment, and flag_health splits it by variant.
feedback_summary groups by sentiment, topic, release, flag, day, status,
platform or source, with counts, the sentiment split, the negative rate and a few quotes per
group. Grouping feedback into themes beyond topics is left to the agent reading it.
Example prompts:
- "What are users complaining about since the 2.4 release?"
- "Summarize negative feedback about checkout this week and link each item to an issue."
- "Does the new_checkout variant get worse feedback than control?"
Privacy
- The message goes through the same scrubber as crash reports, except that email addresses are kept (the user typed them on purpose). Card numbers and secrets are filtered.
- The contact email is optional and only visible to write tokens and admins. It is never sent in alerts, digests or to the LLM.
- Only the message, platform and URL path go to the LLM, never the email, user id or screenshots.
- Vaka never emails end users.
- Feedback follows the project's retention period, and
delete_user_datadeletes it, matching the user id or the contact email. See privacy.