@danieljvdm/dev-kit 1.0.2 → 2.0.0

package/skills/sentry/references/sdks/react-native/user-feedback.md

@@ -0,0 +1,815 @@
+# User Feedback — Sentry React Native SDK
+
+> **Minimum SDK:** `@sentry/react-native` ≥6.5.0 for `captureFeedback()` API\
+> **Feedback widget** (`showFeedbackWidget`, `feedbackIntegration`): ≥6.9.0\
+> **Self-hosted Sentry:** ≥24.4.2 required for full user feedback functionality\
+> **New Architecture (Fabric):** Feedback widget requires React Native ≥0.71+
+
+---
+
+## Overview
+
+Sentry provides three complementary approaches to collecting user feedback in React
+Native:
+
+| Approach                       | When to Use                                                 |
+| ------------------------------ | ----------------------------------------------------------- |
+| **Feedback Widget**            | Built-in modal; minimal code; works out of the box          |
+| **`FeedbackWidget` component** | Embed feedback form inline within your own screen           |
+| **`captureFeedback()` API**    | Full control; build your own UI and submit programmatically |
+
+All approaches support:
+
+- Linking feedback to specific error events via `associatedEventId`
+- Offline caching (stored on-device, sent when connectivity restores)
+- Session Replay integration (buffers last 60 seconds of activity with submitted
+  feedback)
+
+---
+
+## Prerequisites
+
+Wrap your root component with `Sentry.wrap` — this is **required** for the feedback
+widget and error boundary integration:
+
+```typescript
+import * as Sentry from "@sentry/react-native";
+
+export default Sentry.wrap(App);
+```
+
+Without `Sentry.wrap`, `Sentry.showFeedbackWidget()` and `Sentry.showFeedbackButton()`
+will not function correctly.
+
+---
+
+## Approach 1: Built-In Feedback Widget
+
+The simplest integration.
+Call `Sentry.showFeedbackWidget()` from anywhere — a button, menu item, or support
+screen. For automatic shake-to-report, see
+[Shake to Report](#shake-to-report-built-in-native-detection) below.
+
+### Trigger the Widget
+
+```typescript
+import * as Sentry from "@sentry/react-native";
+import { Button } from "react-native";
+
+function SupportButton() {
+  return (
+    <Button
+      title="Report a Problem"
+      onPress={() => Sentry.showFeedbackWidget()}
+    />
+  );
+}
+```
+
+### Persistent Feedback Button
+
+Show or hide the built-in floating feedback button:
+
+```typescript
+// Show the floating feedback button (persists on screen)
+Sentry.showFeedbackButton();
+
+// Hide it when no longer needed
+Sentry.hideFeedbackButton();
+```
+
+### Shake to Report (Built-In Native Detection)
+
+The SDK provides built-in device shake detection that automatically shows the feedback
+widget when the user shakes their device.
+This delegates to native shake detectors in the iOS and Android SDKs — no permissions
+required.
+
+**Option A: Enable via `feedbackIntegration` config**
+
+```typescript
+Sentry.init({
+  dsn: "YOUR_DSN",
+  integrations: [Sentry.feedbackIntegration({ enableShakeToReport: true })],
+});
+```
+
+**Option B: Imperative API (enable/disable at runtime)**
+
+```typescript
+import * as Sentry from "@sentry/react-native";
+
+// Start listening for device shakes — shows feedback widget on shake
+Sentry.enableFeedbackOnShake();
+
+// Stop listening when no longer needed
+Sentry.disableFeedbackOnShake();
+```
+
+> **Platform details:**
+>
+> - **iOS:** Uses UIKit motion event detection (`SentryShakeDetector`)
+> - **Android:** Uses accelerometer sensor (`SentryShakeDetector`)
+> - **Web:** Not supported — shake detection is native-only
+
+### Configure the Widget via `feedbackIntegration`
+
+Customize appearance and fields in `Sentry.init`:
+
+```typescript
+import * as Sentry from "@sentry/react-native";
+
+Sentry.init({
+  dsn: "YOUR_DSN",
+  integrations: [
+    Sentry.feedbackIntegration({
+      // Field placeholder text
+      namePlaceholder: "Full Name",
+      emailPlaceholder: "your@email.com",
+      messagePlaceholder: "What went wrong? What did you expect?",
+
+      // Field labels
+      nameLabel: "Name",
+      emailLabel: "Email",
+      messageLabel: "Description",
+      submitButtonLabel: "Send Report",
+      cancelButtonLabel: "Cancel",
+      formTitle: "Report a Bug",
+
+      // Require fields (all optional by default)
+      isNameRequired: false,
+      isEmailRequired: false,
+
+      // Styling
+      styles: {
+        submitButton: {
+          backgroundColor: "#6a1b9a",
+        },
+      },
+
+      // Pre-fill from current user context (reads Sentry user scope)
+      useSentryUser: {
+        name: "username", // maps user.username → name field
+        email: "email", // maps user.email → email field
+      },
+    }),
+  ],
+});
+```
+
+### Architecture Requirements
+
+| Architecture              | Support                        |
+| ------------------------- | ------------------------------ |
+| Legacy (Bridge)           | ✅ Fully supported             |
+| New Architecture (Fabric) | ✅ Requires React Native ≥0.71 |
+
+---
+
+## Approach 2: `FeedbackWidget` Component
+
+Embed the feedback form directly into your own screen layout instead of showing it as a
+modal:
+
+```typescript
+import { FeedbackWidget } from "@sentry/react-native";
+import { View, Text, StyleSheet } from "react-native";
+
+function SupportScreen() {
+  return (
+    <View style={styles.container}>
+      <Text style={styles.heading}>Having trouble?</Text>
+      <Text style={styles.subtext}>
+        Describe what happened and we'll look into it.
+      </Text>
+      <FeedbackWidget />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { flex: 1, padding: 16 },
+  heading: { fontSize: 20, fontWeight: "bold", marginBottom: 8 },
+  subtext: { color: "#666", marginBottom: 16 },
+});
+```
+
+The `FeedbackWidget` component respects the same configuration set in
+`feedbackIntegration` within `Sentry.init`.
+
+---
+
+## Approach 3: Programmatic API (`captureFeedback`)
+
+Build a completely custom feedback UI and submit via the SDK. Gives full control over
+form layout, validation, and submission flow.
+
+### Basic Feedback (Standalone)
+
+```typescript
+import * as Sentry from "@sentry/react-native";
+
+Sentry.captureFeedback({
+  name: "Jane Smith",
+  email: "jane@example.com",
+  message: "The checkout button doesn't respond after the first tap.",
+});
+```
+
+### Link Feedback to a Specific Error Event
+
+```typescript
+import * as Sentry from "@sentry/react-native";
+
+// Capture an error and get its ID
+const eventId = Sentry.captureException(new Error("Payment failed"));
+
+// Associate the user's report with that exact error
+Sentry.captureFeedback({
+  name: "John Doe",
+  email: "john@example.com",
+  message: "App crashed when I tapped Pay Now.",
+  associatedEventId: eventId,
+});
+```
+
+### Link Feedback to the Most Recent Event
+
+`Sentry.lastEventId()` retrieves the ID of the last event captured in the current
+session — useful for post-crash feedback flows:
+
+```typescript
+import * as Sentry from "@sentry/react-native";
+
+const lastId = Sentry.lastEventId();
+
+if (lastId) {
+  Sentry.captureFeedback({
+    name: user.name,
+    email: user.email,
+    message: feedbackText,
+    associatedEventId: lastId,
+  });
+}
+```
+
+### Feedback with Tags and Attachments
+
+```typescript
+import * as Sentry from "@sentry/react-native";
+
+Sentry.captureFeedback(
+  {
+    name: user.displayName,
+    email: user.email,
+    message: feedbackText,
+  },
+  {
+    captureContext: {
+      tags: {
+        screen: currentScreen,
+        appVersion: appVersion,
+        platform: Platform.OS,
+      },
+    },
+    attachments: [
+      {
+        filename: "device_info.txt",
+        data: JSON.stringify(deviceInfo, null, 2),
+        contentType: "text/plain",
+      },
+    ],
+  },
+);
+```
+
+---
+
+## Crash Report Modal (Post-Crash Feedback)
+
+Show a feedback form on the next app launch after a crash.
+This is the recommended pattern for collecting context around hard crashes that the user
+survived.
+
+### Pattern: Check for Last Event on Launch
+
+```typescript
+import * as Sentry from "@sentry/react-native";
+import React from "react";
+import { Modal, View, Text, TextInput, Button } from "react-native";
+
+function App() {
+  const [showFeedback, setShowFeedback] = React.useState(false);
+  const [feedbackText, setFeedbackText] = React.useState("");
+  const lastEventId = React.useRef<string | undefined>(undefined);
+
+  React.useEffect(() => {
+    // Check if there was a crash in the previous session
+    const eventId = Sentry.lastEventId();
+    if (eventId) {
+      lastEventId.current = eventId;
+      setShowFeedback(true);
+    }
+  }, []);
+
+  function submitCrashFeedback() {
+    if (!feedbackText.trim()) return;
+
+    Sentry.captureFeedback({
+      message: feedbackText,
+      associatedEventId: lastEventId.current,
+    });
+
+    setShowFeedback(false);
+    setFeedbackText("");
+  }
+
+  return (
+    <>
+      <Modal visible={showFeedback} transparent animationType="slide">
+        <View style={{ flex: 1, justifyContent: "center", padding: 24 }}>
+          <Text style={{ fontSize: 18, fontWeight: "bold", marginBottom: 8 }}>
+            It looks like the app crashed
+          </Text>
+          <Text style={{ color: "#555", marginBottom: 16 }}>
+            What were you doing when it happened?
+          </Text>
+          <TextInput
+            multiline
+            value={feedbackText}
+            onChangeText={setFeedbackText}
+            placeholder="Describe what happened..."
+            style={{
+              borderWidth: 1,
+              borderColor: "#ccc",
+              borderRadius: 8,
+              padding: 12,
+              minHeight: 100,
+              marginBottom: 16,
+            }}
+          />
+          <Button title="Send Report" onPress={submitCrashFeedback} />
+          <Button title="Skip" onPress={() => setShowFeedback(false)} />
+        </View>
+      </Modal>
+      {/* rest of app */}
+    </>
+  );
+}
+```
+
+> **Tip:** `Sentry.lastEventId()` returns the ID of the most recent event captured
+> during the _current_ app session.
+> For post-crash context, call it at app start before any other Sentry calls that might
+> create a new event.
+
+---
+
+## Linking Feedback to Errors via `ErrorBoundary`
+
+The `Sentry.ErrorBoundary` component can automatically show a feedback dialog after
+capturing a React render error, using the `showDialog` prop:
+
+```typescript
+import * as Sentry from "@sentry/react-native";
+import { Text } from "react-native";
+
+function App() {
+  return (
+    <Sentry.ErrorBoundary
+      fallback={<Text>Something went wrong. Your report has been sent.</Text>}
+      showDialog  // Opens Sentry feedback widget after capturing the error
+    >
+      <MainContent />
+    </Sentry.ErrorBoundary>
+  );
+}
+```
+
+### Custom Post-Error Feedback Form
+
+For full control, use `onError` to capture the `eventId` and trigger your own feedback
+form:
+
+```typescript
+import * as Sentry from "@sentry/react-native";
+import React from "react";
+import { View, Text, TextInput, Button } from "react-native";
+
+function ErrorFallback({ eventId, onReset }: { eventId: string; onReset: () => void }) {
+  const [message, setMessage] = React.useState("");
+
+  function submit() {
+    Sentry.captureFeedback({
+      message,
+      associatedEventId: eventId,
+    });
+    onReset();
+  }
+
+  return (
+    <View style={{ padding: 24 }}>
+      <Text style={{ fontSize: 18, fontWeight: "bold" }}>Oops, something broke</Text>
+      <TextInput
+        multiline
+        value={message}
+        onChangeText={setMessage}
+        placeholder="What were you trying to do?"
+        style={{ borderWidth: 1, borderColor: "#ccc", padding: 12, marginVertical: 16 }}
+      />
+      <Button title="Send Feedback" onPress={submit} />
+    </View>
+  );
+}
+
+function App() {
+  const [errorEventId, setErrorEventId] = React.useState<string | null>(null);
+
+  return (
+    <Sentry.ErrorBoundary
+      onError={(_error, _componentStack, eventId) => {
+        setErrorEventId(eventId);
+      }}
+      fallback={
+        errorEventId
+          ? <ErrorFallback eventId={errorEventId} onReset={() => setErrorEventId(null)} />
+          : <Text>Something went wrong.</Text>
+      }
+    >
+      <MainContent />
+    </Sentry.ErrorBoundary>
+  );
+}
+```
+
+---
+
+## Screenshots in Feedback
+
+Allow users to attach screenshots to feedback reports.
+Use `attachments` in `captureFeedback` to include screenshots captured from the device:
+
+```typescript
+import * as Sentry from "@sentry/react-native";
+import { captureScreen } from "react-native-view-shot"; // npm install react-native-view-shot
+import RNFS from "react-native-fs"; // npm install react-native-fs
+
+async function submitFeedbackWithScreenshot(feedbackMessage: string) {
+  // Capture current screen as PNG
+  const screenshotUri = await captureScreen({ format: "png", quality: 0.8 });
+  const screenshotBase64 = await RNFS.readFile(screenshotUri, "base64");
+
+  Sentry.captureFeedback(
+    {
+      message: feedbackMessage,
+      associatedEventId: Sentry.lastEventId(),
+    },
+    {
+      attachments: [
+        {
+          filename: "screenshot.png",
+          data: screenshotBase64,
+          contentType: "image/png",
+        },
+      ],
+    },
+  );
+}
+```
+
+> **Alternative:** Enable `attachScreenshot: true` in `Sentry.init` to automatically
+> attach a screenshot to every error event — the screenshot then appears alongside any
+> feedback linked to that event via `associatedEventId`.
+
+```typescript
+Sentry.init({
+  dsn: "YOUR_DSN",
+  attachScreenshot: true, // Auto-attach screenshot to every error event
+});
+```
+
+---
+
+## Session Replay Integration with Feedback
+
+When `mobileReplayIntegration()` is enabled and a user submits feedback via the widget,
+Sentry automatically buffers and attaches **up to 60 seconds of prior session replay**
+to the feedback submission.
+This gives you visual context for what the user experienced before they filed the report
+— no extra code required.
+
+```typescript
+Sentry.init({
+  dsn: "YOUR_DSN",
+  replaysOnErrorSampleRate: 1.0,
+  replaysSessionSampleRate: 0.1,
+  integrations: [
+    Sentry.mobileReplayIntegration(),
+    Sentry.feedbackIntegration(), // replay attaches automatically on feedback submit
+  ],
+});
+```
+
+---
+
+## Offline Feedback
+
+Feedback captured while the device is offline is **automatically cached on-device** by
+the native SDK layer and replayed to Sentry when connectivity is restored.
+This applies to all three approaches (`showFeedbackWidget`, `FeedbackWidget`,
+`captureFeedback`). No additional configuration is needed.
+
+---
+
+## Complete Custom Feedback Form Example
+
+A fully custom feedback flow — your own UI, validation, submission:
+
+```typescript
+import React from "react";
+import {
+  View,
+  Text,
+  TextInput,
+  TouchableOpacity,
+  StyleSheet,
+  Alert,
+} from "react-native";
+import * as Sentry from "@sentry/react-native";
+
+interface FeedbackFormProps {
+  onDismiss: () => void;
+  associatedEventId?: string;
+}
+
+export function CustomFeedbackForm({ onDismiss, associatedEventId }: FeedbackFormProps) {
+  const [name, setName] = React.useState("");
+  const [email, setEmail] = React.useState("");
+  const [message, setMessage] = React.useState("");
+  const [submitting, setSubmitting] = React.useState(false);
+
+  async function handleSubmit() {
+    if (!message.trim()) {
+      Alert.alert("Required", "Please describe what happened.");
+      return;
+    }
+
+    setSubmitting(true);
+
+    try {
+      Sentry.captureFeedback(
+        {
+          name: name.trim() || undefined,
+          email: email.trim() || undefined,
+          message: message.trim(),
+          associatedEventId,
+        },
+        {
+          captureContext: {
+            tags: { feedbackSource: "custom-form" },
+          },
+        }
+      );
+
+      Alert.alert("Thank you", "Your feedback has been submitted.");
+      onDismiss();
+    } catch (err) {
+      Alert.alert("Error", "Failed to submit feedback. Please try again.");
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>Send Feedback</Text>
+
+      <TextInput
+        style={styles.input}
+        placeholder="Name (optional)"
+        value={name}
+        onChangeText={setName}
+        autoCapitalize="words"
+      />
+
+      <TextInput
+        style={styles.input}
+        placeholder="Email (optional)"
+        value={email}
+        onChangeText={setEmail}
+        keyboardType="email-address"
+        autoCapitalize="none"
+      />
+
+      <TextInput
+        style={[styles.input, styles.messageInput]}
+        placeholder="Describe what happened *"
+        value={message}
+        onChangeText={setMessage}
+        multiline
+        numberOfLines={5}
+        textAlignVertical="top"
+      />
+
+      <TouchableOpacity
+        style={[styles.button, submitting && styles.buttonDisabled]}
+        onPress={handleSubmit}
+        disabled={submitting}
+      >
+        <Text style={styles.buttonText}>
+          {submitting ? "Sending…" : "Submit"}
+        </Text>
+      </TouchableOpacity>
+
+      <TouchableOpacity style={styles.cancelButton} onPress={onDismiss}>
+        <Text style={styles.cancelText}>Cancel</Text>
+      </TouchableOpacity>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { padding: 24, backgroundColor: "#fff", borderRadius: 12 },
+  title: { fontSize: 20, fontWeight: "bold", marginBottom: 16 },
+  input: {
+    borderWidth: 1,
+    borderColor: "#ddd",
+    borderRadius: 8,
+    padding: 12,
+    marginBottom: 12,
+    fontSize: 16,
+  },
+  messageInput: { minHeight: 120 },
+  button: {
+    backgroundColor: "#6200ee",
+    borderRadius: 8,
+    padding: 14,
+    alignItems: "center",
+    marginBottom: 8,
+  },
+  buttonDisabled: { opacity: 0.6 },
+  buttonText: { color: "#fff", fontSize: 16, fontWeight: "600" },
+  cancelButton: { alignItems: "center", padding: 10 },
+  cancelText: { color: "#666", fontSize: 16 },
+});
+```
+
+---
+
+## `captureFeedback` API Reference
+
+```typescript
+Sentry.captureFeedback(
+  feedback: UserFeedback,
+  hint?: EventHint
+): string | undefined
+```
+
+### `feedback` object
+
+| Field               | Type     | Required | Description                                                  |
+| ------------------- | -------- | -------- | ------------------------------------------------------------ |
+| `message`           | `string` | ✅       | User’s feedback text                                         |
+| `name`              | `string` | ❌       | User’s display name                                          |
+| `email`             | `string` | ❌       | User’s email address                                         |
+| `associatedEventId` | `string` | ❌       | Links feedback to a specific Sentry event (error or message) |
+
+### `hint` object (optional)
+
+| Field            | Type             | Description                                               |
+| ---------------- | ---------------- | --------------------------------------------------------- |
+| `captureContext` | `CaptureContext` | Scope data to attach (tags, extra, user, level, contexts) |
+| `attachments`    | `Attachment[]`   | Files to attach (screenshots, logs, etc.)                 |
+
+Returns the feedback event ID (or `undefined` if SDK is disabled).
+
+---
+
+## `feedbackIntegration` Configuration Reference
+
+| Option                | Type      | Default                                  | Description                                                                    |
+| --------------------- | --------- | ---------------------------------------- | ------------------------------------------------------------------------------ |
+| `formTitle`           | `string`  | `"Report a Bug"`                         | Widget modal title                                                             |
+| `submitButtonLabel`   | `string`  | `"Send Bug Report"`                      | Submit button text                                                             |
+| `cancelButtonLabel`   | `string`  | `"Cancel"`                               | Cancel button text                                                             |
+| `nameLabel`           | `string`  | `"Name"`                                 | Name field label                                                               |
+| `namePlaceholder`     | `string`  | `"Your Name"`                            | Name field placeholder                                                         |
+| `emailLabel`          | `string`  | `"Email"`                                | Email field label                                                              |
+| `emailPlaceholder`    | `string`  | `"your.email@example.org"`               | Email field placeholder                                                        |
+| `messageLabel`        | `string`  | `"Description"`                          | Message field label                                                            |
+| `messagePlaceholder`  | `string`  | `"What's the bug? What did you expect?"` | Message field placeholder                                                      |
+| `isNameRequired`      | `boolean` | `false`                                  | Make name field required                                                       |
+| `isEmailRequired`     | `boolean` | `false`                                  | Make email field required                                                      |
+| `useSentryUser`       | `object`  | —                                        | Maps Sentry user scope fields to pre-fill name/email                           |
+| `enableShakeToReport` | `boolean` | `false`                                  | Show feedback widget when the user shakes the device (native iOS/Android only) |
+| `styles`              | `object`  | —                                        | Style overrides for widget UI elements                                         |
+
+---
+
+## API Summary
+
+| Method                                    | Description                                                |
+| ----------------------------------------- | ---------------------------------------------------------- |
+| `Sentry.showFeedbackWidget()`             | Open the built-in feedback modal                           |
+| `Sentry.showFeedbackButton()`             | Show the persistent floating feedback button               |
+| `Sentry.hideFeedbackButton()`             | Hide the persistent floating feedback button               |
+| `Sentry.enableFeedbackOnShake()`          | Start native shake detection to show feedback widget       |
+| `Sentry.disableFeedbackOnShake()`         | Stop native shake detection                                |
+| `Sentry.captureFeedback(feedback, hint?)` | Submit feedback programmatically                           |
+| `Sentry.lastEventId()`                    | Get the ID of the most recent captured event (for linking) |
+| `Sentry.feedbackIntegration(options)`     | Configure the built-in widget                              |
+
+---
+
+## Version Requirements
+
+| Feature                                           | Min SDK            | Notes                                       |
+| ------------------------------------------------- | ------------------ | ------------------------------------------- |
+| `captureFeedback()`                               | ≥6.5.0             | Replaces deprecated `captureUserFeedback()` |
+| `showFeedbackWidget()`                            | ≥6.9.0             | Requires `Sentry.wrap(App)`                 |
+| `feedbackIntegration()`                           | ≥6.9.0             | Configure widget appearance                 |
+| `FeedbackWidget` component                        | ≥6.9.0             | Inline embedded widget                      |
+| `showFeedbackButton()` / `hideFeedbackButton()`   | ≥6.15.0            | Floating feedback button                    |
+| `enableShakeToReport` / `enableFeedbackOnShake()` | ≥8.5.0             | Native shake detection (iOS & Android)      |
+| Offline caching                                   | Built-in           | Automatic, no config needed                 |
+| Session Replay attachment                         | ≥6.9.0             | When `mobileReplayIntegration` enabled      |
+| New Architecture (Fabric) support                 | React Native ≥0.71 | Widget works on new arch                    |
+
+---
+
+## Expo Considerations
+
+- The feedback widget works in **Expo managed and bare** workflows
+- `showFeedbackWidget()` requires a **native build** — it does **not** function in Expo
+  Go
+- `captureFeedback()` (programmatic API) works in both Expo Go and native builds
+- Use `isRunningInExpoGo()` to guard widget calls in dev:
+
+```typescript
+import { isRunningInExpoGo } from "expo";
+import * as Sentry from "@sentry/react-native";
+
+function ReportButton() {
+  if (isRunningInExpoGo()) {
+    // Fallback: use captureFeedback directly instead of the widget
+    return (
+      <Button
+        title="Report (dev mode)"
+        onPress={() =>
+          Sentry.captureFeedback({ message: "Test feedback from Expo Go" })
+        }
+      />
+    );
+  }
+
+  return (
+    <Button
+      title="Report a Problem"
+      onPress={() => Sentry.showFeedbackWidget()}
+    />
+  );
+}
+```
+
+---
+
+## Migration: `captureUserFeedback` → `captureFeedback`
+
+`captureUserFeedback()` was removed in v7. Replace all usages:
+
+```typescript
+// ❌ BEFORE (v6 and earlier) — removed in v7
+Sentry.captureUserFeedback({
+  event_id: eventId,
+  name: "John",
+  email: "john@example.com",
+  comments: "Something went wrong.",
+});
+
+// ✅ AFTER (v7+)
+Sentry.captureFeedback({
+  associatedEventId: eventId,
+  name: "John",
+  email: "john@example.com",
+  message: "Something went wrong.", // renamed from "comments"
+});
+```
+
+---
+
+## Troubleshooting
+
+| Issue                                      | Solution                                                                                                               |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `showFeedbackWidget()` has no effect       | Confirm `Sentry.wrap(App)` wraps your root component                                                                   |
+| Widget doesn’t open on New Architecture    | Requires React Native ≥0.71; check architecture compatibility                                                          |
+| Feedback not appearing in Sentry dashboard | Verify DSN is correct; check network connectivity; enable `debug: true` for SDK logs                                   |
+| `captureFeedback` not sending in Expo Go   | Expected — use `captureFeedback()` (works) but not `showFeedbackWidget()` (native only)                                |
+| `lastEventId()` returns `undefined`        | No events have been captured in the current session yet; ensure an error or message was captured first                 |
+| Offline feedback not delivered             | Offline caching is automatic; check `maxCacheItems` (default: 30); old cache is evicted if full                        |
+| `captureUserFeedback` is not a function    | Upgrade to `@sentry/react-native` ≥7.0.0 and replace with `captureFeedback()`                                          |
+| Replay not attaching to feedback           | Confirm `mobileReplayIntegration()` is in `integrations` and the app is running as a native build                      |
+| `associatedEventId` not linking correctly  | Pass the exact event ID string returned by `captureException`, `captureMessage`, or `lastEventId()`                    |
+| Widget styles not applying                 | Pass `styles` config inside `feedbackIntegration({ styles: { ... } })` in `Sentry.init`                                |
+| Shake to report not working                | Confirm `Sentry.wrap(App)` wraps your root component; shake detection is native-only (not available on Web or Expo Go) |
+| Shake detected but widget doesn’t appear   | Ensure `feedbackIntegration()` is in the `integrations` array; check `debug: true` for logs                            |