@danieljvdm/dev-kit 1.0.2 → 2.0.0

package/skills/sentry/references/sdks/browser/user-feedback.md

@@ -0,0 +1,354 @@
+# User Feedback — Sentry Browser SDK
+
+> Minimum SDK: `@sentry/browser` ≥7.85.0 for `feedbackIntegration()`\
+> Screenshot capture: requires ≥8.0.0\
+> Self-hosted Sentry: requires version ≥24.4.2
+
+---
+
+## Two Approaches
+
+| Approach                             | When to Use                                                                      |
+| ------------------------------------ | -------------------------------------------------------------------------------- |
+| **`feedbackIntegration()` widget**   | Collect feedback anywhere — no error required; embeds a button in the UI         |
+| **`showReportDialog()` crash modal** | Triggered after an error is captured; prompts the user to describe what happened |
+
+Both approaches can be used together.
+The widget is general-purpose; the crash modal is specifically for error-linked
+feedback.
+
+---
+
+## Approach 1: Feedback Widget (`feedbackIntegration`)
+
+### Basic Setup
+
+```javascript
+import * as Sentry from "@sentry/browser";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [
+    Sentry.feedbackIntegration({
+      colorScheme: "system", // "light" | "dark" | "system"
+    }),
+  ],
+});
+```
+
+A “Report a Bug” button appears in the bottom-right corner by default.
+Clicking it opens a modal form.
+
+### Lazy Loading via Loader Script
+
+```javascript
+window.sentryOnLoad = function () {
+  Sentry.init({ dsn: "___PUBLIC_DSN___" });
+
+  Sentry.lazyLoadIntegration("feedbackIntegration")
+    .then((feedbackIntegration) => {
+      Sentry.addIntegration(
+        feedbackIntegration({
+          colorScheme: "system",
+        }),
+      );
+    })
+    .catch(() => {
+      // Network error — User Feedback widget not loaded
+    });
+};
+```
+
+### CDN Bundle Options
+
+```html
+<!-- Feedback only (lightest bundle) -->
+<script
+  src="https://browser.sentry-cdn.com/10.42.0/bundle.feedback.min.js"
+  crossorigin="anonymous"
+></script>
+
+<!-- With tracing and replay -->
+<script
+  src="https://browser.sentry-cdn.com/10.42.0/bundle.tracing.replay.feedback.min.js"
+  crossorigin="anonymous"
+></script>
+```
+
+### Configuration Options
+
+#### Appearance
+
+| Option              | Type                                | Default             | Description                                      |
+| ------------------- | ----------------------------------- | ------------------- | ------------------------------------------------ |
+| `colorScheme`       | `'light'` \| `'dark'` \| `'system'` | `'system'`          | Widget color theme.                              |
+| `buttonLabel`       | `string`                            | `"Report a Bug"`    | Text on the trigger button.                      |
+| `submitButtonLabel` | `string`                            | `"Send Bug Report"` | Text on the form’s submit button.                |
+| `cancelButtonLabel` | `string`                            | `"Cancel"`          | Text on the cancel button.                       |
+| `formTitle`         | `string`                            | `"Report a Bug"`    | Title displayed in the feedback form.            |
+| `showBranding`      | `boolean`                           | `true`              | Show “Powered by Sentry” branding in the widget. |
+
+#### Form Fields
+
+| Option               | Type      | Default                    | Description                    |
+| -------------------- | --------- | -------------------------- | ------------------------------ |
+| `showName`           | `boolean` | `true`                     | Show the name input field.     |
+| `showEmail`          | `boolean` | `true`                     | Show the email input field.    |
+| `isNameRequired`     | `boolean` | `false`                    | Make name field required.      |
+| `isEmailRequired`    | `boolean` | `false`                    | Make email field required.     |
+| `namePlaceholder`    | `string`  | `"Your Name"`              | Placeholder for name field.    |
+| `emailPlaceholder`   | `string`  | `"your.email@example.org"` | Placeholder for email field.   |
+| `messagePlaceholder` | `string`  | `"What's the bug? ..."`    | Placeholder for message field. |
+
+#### Positioning
+
+| Option     | Type                                                                 | Default          | Description                           |
+| ---------- | -------------------------------------------------------------------- | ---------------- | ------------------------------------- |
+| `position` | `'bottom-right'` \| `'bottom-left'` \| `'top-right'` \| `'top-left'` | `'bottom-right'` | Where to position the trigger button. |
+
+#### Behaviour
+
+| Option             | Type                     | Default | Description                                                                                      |
+| ------------------ | ------------------------ | ------- | ------------------------------------------------------------------------------------------------ |
+| `autoInject`       | `boolean`                | `true`  | Automatically inject the trigger button into the DOM. Set `false` to control placement manually. |
+| `enableScreenshot` | `boolean`                | `true`  | Allow users to attach a screenshot. Requires SDK ≥8.0.0.                                         |
+| `tags`             | `Record<string, string>` | `{}`    | Additional tags to attach to every submitted feedback event.                                     |
+
+### Pre-fill User Information
+
+```javascript
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [
+    Sentry.feedbackIntegration({
+      // Pre-fill form with logged-in user's details
+    }),
+  ],
+});
+
+// After authentication
+Sentry.setUser({
+  email: "user@example.com",
+  name: "Jane Smith",
+});
+```
+
+When `Sentry.setUser()` is called, the feedback form auto-populates name and email
+fields.
+
+### Manual Widget Control (Custom Button)
+
+Disable auto-inject and open the widget programmatically from your own button:
+
+```javascript
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [
+    Sentry.feedbackIntegration({
+      autoInject: false, // Don't render Sentry's trigger button
+    }),
+  ],
+});
+
+// Open the widget from your own UI element
+document.getElementById("my-feedback-btn").addEventListener("click", () => {
+  const feedback = Sentry.getFeedback();
+  if (feedback) {
+    feedback.openDialog();
+  }
+});
+```
+
+---
+
+## Approach 2: Programmatic Feedback (`captureFeedback`)
+
+Use a completely custom form UI and submit feedback via the API:
+
+```javascript
+// Minimal — only message is required
+Sentry.captureFeedback({
+  name: "Jane Smith",
+  email: "jane@example.com",
+  message: "The checkout button doesn't work on mobile.",
+});
+```
+
+### With Tags and Attachments
+
+```javascript
+// Attach a screenshot as a file
+const screenshotDataUrl = "data:image/jpeg;base64,...";
+const res = await fetch(screenshotDataUrl);
+const buffer = await res.arrayBuffer();
+
+Sentry.captureFeedback(
+  {
+    name: "Jane Smith",
+    email: "jane@example.com",
+    message: "The checkout button doesn't work on mobile.",
+  },
+  {
+    captureContext: {
+      tags: { page: "checkout", device: "mobile" },
+    },
+    attachments: [
+      {
+        filename: "screenshot.png",
+        data: new Uint8Array(buffer),
+      },
+    ],
+  },
+);
+```
+
+### Linking Feedback to a Specific Error
+
+```javascript
+try {
+  await submitOrder();
+} catch (err) {
+  const eventId = Sentry.captureException(err);
+
+  Sentry.captureFeedback({
+    message: "Something went wrong during checkout.",
+    associatedEventId: eventId, // Links this feedback to the captured error
+  });
+}
+```
+
+### `captureFeedback` Parameters
+
+| Parameter           | Required | Description                                                                                                      |
+| ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
+| `message`           | ✅       | The feedback text from the user                                                                                  |
+| `name`              | ❌       | User’s name                                                                                                      |
+| `email`             | ❌       | User’s email                                                                                                     |
+| `associatedEventId` | ❌       | Links feedback to a specific Sentry event (use `Sentry.lastEventId()` or the return value of `captureException`) |
+
+---
+
+## Approach 3: Crash-Report Modal (`showReportDialog`)
+
+Show a modal prompting users to describe what happened when an error occurs.
+Ideal for “something went wrong” pages or after unhandled errors.
+
+### Basic Setup
+
+```javascript
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  beforeSend(event) {
+    if (event.exception && event.event_id) {
+      Sentry.showReportDialog({ eventId: event.event_id });
+    }
+    return event;
+  },
+});
+```
+
+### On a 500 Error Page
+
+```html
+<script>
+  Sentry.init({ dsn: "___PUBLIC_DSN___" });
+</script>
+
+<script>
+  // eventId is provided by your server-side Sentry SDK after capturing the error
+  Sentry.showReportDialog({ eventId: "{{ sentry_event_id }}" });
+</script>
+```
+
+### After Manual `captureException`
+
+```javascript
+try {
+  await riskyOperation();
+} catch (err) {
+  const eventId = Sentry.captureException(err);
+  Sentry.showReportDialog({ eventId });
+}
+```
+
+### `showReportDialog` Options
+
+| Option        | Required | Description                                        |
+| ------------- | -------- | -------------------------------------------------- |
+| `eventId`     | ✅       | The Sentry event ID to associate the feedback with |
+| `user.name`   | ❌       | Pre-fill user’s name                               |
+| `user.email`  | ❌       | Pre-fill user’s email                              |
+| `lang`        | ❌       | Dialog language code (e.g., `"de"`, `"fr"`)        |
+| `title`       | ❌       | Override dialog title                              |
+| `subtitle`    | ❌       | Override dialog subtitle                           |
+| `subtitle2`   | ❌       | Override second subtitle line                      |
+| `labelSubmit` | ❌       | Override submit button label                       |
+
+The modal collects: **user name, email, and a description** — paired with the original
+captured error event.
+
+---
+
+## Screenshot Capture
+
+- Available on SDK **v8.0.0+**
+- Enabled by default via `enableScreenshot: true` on `feedbackIntegration()`
+- Auto-hidden on mobile devices
+- Screenshots count against your **attachment quota** (1GB standard)
+
+```javascript
+Sentry.feedbackIntegration({
+  enableScreenshot: true, // default — can set false to disable
+});
+```
+
+---
+
+## Session Replay Integration
+
+When Session Replay is configured alongside User Feedback, submitted feedback links to
+the user’s replay:
+
+```javascript
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  replaysOnErrorSampleRate: 1.0, // Buffer replays for error sessions
+  integrations: [Sentry.replayIntegration(), Sentry.feedbackIntegration({ colorScheme: "system" })],
+});
+```
+
+The system buffers up to **30 seconds** when the feedback widget opens.
+This enables viewing the replay alongside the submitted feedback in Sentry.
+
+---
+
+## Best Practices
+
+- **Use `feedbackIntegration()` for proactive collection** — don’t wait for errors; a
+  persistent feedback button catches issues that never throw exceptions
+- **Pre-fill user info** — call `Sentry.setUser()` after login so users don’t have to
+  type their email each time
+- **Combine crash modal with `beforeSend`** — automatic prompting after errors maximizes
+  feedback capture
+- **Link programmatic feedback to events** — use `associatedEventId` so feedback appears
+  alongside error context in Sentry
+- **Set `autoInject: false`** for branded UI — implement your own trigger button to
+  match your design system
+- **Keep `showReportDialog` for 500 pages** — server-rendered error pages are the
+  primary use case; pass the server-side event ID to the client
+
+---
+
+## Troubleshooting
+
+| Issue                                                     | Solution                                                                                       |
+| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| Widget doesn’t appear                                     | Check that `feedbackIntegration()` is in the `integrations` array and SDK ≥7.85.0              |
+| Widget appears but form won’t submit                      | Verify DSN is correct; check browser network tab for blocked requests                          |
+| Screenshots not showing                                   | Requires SDK ≥8.0.0; check `enableScreenshot` is not set to `false`                            |
+| `showReportDialog` shows but feedback not linked to error | Ensure `eventId` is passed; use `captureException()` return value or `Sentry.lastEventId()`    |
+| Crash modal not appearing after error                     | `showReportDialog` must be called with a valid `eventId`; check `beforeSend` hook is executing |
+| Feedback not appearing in Sentry                          | Check attachment quota; ensure self-hosted Sentry is version ≥24.4.2                           |
+| Form fields are empty (no pre-fill)                       | Call `Sentry.setUser({ name, email })` before the widget is opened                             |
+| Replay not linked to feedback                             | Set `replaysOnErrorSampleRate > 0`; replay must be active when feedback is submitted           |
+| Widget conflicts with page z-index                        | Widget uses Shadow DOM — if still conflicting, use `autoInject: false` and position manually   |