vaka
CI statusLatest releaseGitHub

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.

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) { ... })

Anything else can send it over the ingest protocol.

Limits

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:

Privacy