Skip to content

Commit 6b496f4

Browse files
antonisantonis
authored
Add React Native Feedback Widget documentation (#12503)
1 parent 80021b8 commit 6b496f4

File tree

3 files changed

+262
-1
lines changed

3 files changed

+262
-1
lines changed

‎docs/platforms/react-native/user-feedback/configuration/img/mobile-user-feedback-widget-customization.png

275 KB
Loading

‎docs/platforms/react-native/user-feedback/configuration/index.mdx

+199
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
---
2+
title: Configuration
3+
sidebar_order: 6100
4+
description: "Learn about the User Feedback Widget configuration options."
5+
---
6+
7+
The User Feedback Widget offers many customization options, and if the available options are insufficient, you can [use your own UI](/platforms/react-native/user-feedback/#user-feedback-api).
8+
9+
![An image showing the main customization options for the User Feedback Widget](./img/mobile-user-feedback-widget-customization.png)
10+
To collect user feedback from inside your application use the `showFeedbackWidget` method.
11+
12+
```javascript
13+
import * as Sentry from "@sentry/react-native";
14+
15+
Sentry.wrap(RootComponent);
16+
17+
Sentry.showFeedbackWidget();
18+
```
19+
20+
Note that [the root application component must be wrapped with `Sentry.wrap`](/platforms/react-native/#wrap-your-app) for this to work.
21+
22+
## General
23+
24+
The following options can be configured for the integration in `feedbackIntegration({})` or passed in the `FeedbackWidget` component props:
25+
26+
27+
| Key | Type | Default | Description |
28+
| ---------------------- | ------------------------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
29+
| `showBranding` | `boolean` | `true` | Displays the Sentry logo. |
30+
| `showName` | `boolean` | `true` | Displays the name field on the feedback widget. |
31+
| `showEmail` | `boolean` | `true` | Displays the email field on the feedback widget. |
32+
| `enableScreenshot` | `boolean` | `false` | Allows the user to send a screenshot attachment with their feedback. |
33+
| `isNameRequired` | `boolean` | `false` | Requires the name field on the feedback widget to be filled in. |
34+
| `isEmailRequired` | `boolean` | `false` | Requires the email field on the feedback widget to be filled in. |
35+
| `shouldValidateEmail` | `boolean` | `true` | If set the email is validated with the following regular expression `"/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/"` |
36+
| `useSentryUser` | `Record<string, string>` | `{ email: 'email', name: 'username'}` | Sets the default values for the `email` and `name` fields. |
37+
38+
39+
## Text Customization
40+
41+
All the text that you see in the Feedback widget can be customized.
42+
43+
The following options can be configured for the integration in `feedbackIntegration({})` or passed in the `FeedbackWidget` component props:
44+
45+
| Key | Default | Description |
46+
| ----------------------------- | ------------------------------------------------------- | --------------------------------------------------------------- |
47+
| `formTitle` | `"Report a Bug"` | The title at the top of the feedback widget. |
48+
| `submitButtonLabel` | `"Send Bug Report"` | The label of the submit button used in the feedback widget. |
49+
| `cancelButtonLabel` | `"Cancel"` | The label of cancel buttons used in the feedback widget. |
50+
| `addScreenshotButtonLabel` | `"Add a screenshot"` | The label of the button to add a screenshot to the widget. |
51+
| `removeScreenshotButtonLabel` | `"Remove screenshot"` | The label of the button to remove the screenshot. |
52+
| `nameLabel` | `"Name"` | The label of the name input field. |
53+
| `namePlaceholder` | `"Your Name"` | The placeholder for the name input field. |
54+
| `emailLabel` | `"Email"` | The label of the email input field. |
55+
| `emailPlaceholder` | `"[email protected]"` | The placeholder for the email input field. |
56+
| `isRequiredLabel` | `"(required)"` | The label shown next to an input field that is required. |
57+
| `messageLabel` | `"Description"` | The label for the feedback description input field. |
58+
| `messagePlaceholder` | `"What's the bug? What did you expect?"` | The placeholder for the feedback description input field. |
59+
| `successMessageText` | `"Thank you for your report!"` | The message displayed after a successful feedback submission. |
60+
| `errorTitle` | `"Error"` | The title of the error message dialog. |
61+
| `formError` | `"Please fill out all required fields."` | Form validation error message. |
62+
| `emailError` | `"Please enter a valid email address."` | Email validation error mesage. |
63+
| `genericError` | `"Unable to send feedback due to an unexpected error."` | The generic error message. |
64+
65+
Example of customization:
66+
67+
```javascript
68+
feedbackIntegration({
69+
nameLabel: "Full Name",
70+
submitButtonLabel: "Send",
71+
formTitle: "Give Feedback",
72+
});
73+
```
74+
75+
## Style Customization
76+
77+
You can customize placement of the feedback components on the widget, as well as the fonts and colors.
78+
79+
The example below shows how to customize the submit button background color and border radius with the `feedbackIntegration`.
80+
81+
```javascript
82+
import * as Sentry from "@sentry/react-native";
83+
84+
Sentry.feedbackIntegration({
85+
styles:{
86+
submitButton: {
87+
backgroundColor: '#6a1b9a',
88+
borderRadius: 5,
89+
},
90+
},
91+
});
92+
93+
Sentry.showFeedbackWidget();
94+
```
95+
96+
The same can be achived by passing the `styles` prop to the `FeedbackWidget` component:
97+
98+
```javascript
99+
import { FeedbackWidget } from "@sentry/react-native";
100+
101+
<FeedbackWidget
102+
styles={{
103+
submitButton: {
104+
backgroundColor: '#6a1b9a',
105+
borderRadius: 5,
106+
},
107+
}}
108+
/>
109+
```
110+
111+
The following styles are available for customisation.
112+
113+
| Style | Type | Description |
114+
| --------------------- | ------------ | ----------------------------------------------- |
115+
| `container` | `ViewStyle` | The widget container style. |
116+
| `title` | `TextStyle` | The title text style. |
117+
| `label` | `TextStyle` | The label text style (name, email). |
118+
| `input` | `TextStyle` | The input field text style (name, email). |
119+
| `textArea` | `TextStyle` | The message text style. |
120+
| `submitButton` | `ViewStyle` | The submit button style. |
121+
| `submitText` | `TextStyle` | The submit button text style. |
122+
| `cancelButton` | `ViewStyle` | The cancel button style. |
123+
| `cancelText` | `TextStyle` | The cancel button text style. |
124+
| `screenshotButton` | `ViewStyle` | The screenshot button style. |
125+
| `screenshotText` | `TextStyle` | The screenshot button text style. |
126+
| `screenshotContainer` | `TextStyle` | The screenshot thumbnail container style. |
127+
| `screenshotThumbnail` | `ImageStyle` | The screenshot thumbnail image style. |
128+
| `titleContainer` | `ViewStyle` | The title container style. |
129+
130+
## Event Callbacks
131+
132+
The following callbacks can be configured for the integration in `feedbackIntegration({})` or passed in the `FeedbackWidget` component props:
133+
134+
| Callback | Parameters | Default behavior | Description |
135+
| ----------------- | ---------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------- |
136+
| `onFormOpen` | | | Callback when widget is opened. |
137+
| `onFormClose` | | The widget is unmounted.| Callback when widget is closed and not submitted. |
138+
| `onSubmitSuccess` | `data: FeedbackFormData` | | Callback when feedback is successfully submitted. |
139+
| `onSubmitError` | `error: Error` | | Callback when feedback is unsuccessfully submitted. |
140+
| `onFormSubmitted` | | The widget is unmounted.| Callback when the feedback widget is submitted successfully, and the SuccessMessage is complete, or dismissed.|
141+
| `onAddScreenshot` | `addScreenshot: (uri: string) => void` | | Callback when a screenshot is added. |
142+
143+
## Screenshots
144+
145+
The screenshot functionality is disabled by default. To enable it, pass an `imagePicker` integration library or set the `enableScreenshot` option to `true` and implement the `onAddScreenshot` callback.
146+
147+
### Integrating with an Image Picker Library
148+
149+
Currently the supported libraries are:
150+
- [expo-image-picker](https://docs.expo.dev/versions/latest/sdk/imagepicker/) (tested with version `16.0`)
151+
- [react-native-image-picker](https://github.com/react-native-image-picker/react-native-image-picker) (tested with version `7.2` and `8.0`)
152+
153+
You just need to import the library and pass it to the `feedbackIntegration` method.
154+
155+
```javascript
156+
import * as ImagePicker from 'expo-image-picker';
157+
```
158+
159+
Or `react-native-image-picker`:
160+
161+
```javascript
162+
import * as ImagePicker from 'react-native-image-picker';
163+
```
164+
165+
And then pass it to `feedbackIntegration`:
166+
167+
```javascript
168+
Sentry.init({
169+
integrations: [
170+
Sentry.feedbackIntegration({
171+
imagePicker: ImagePicker,
172+
}),
173+
],
174+
});
175+
```
176+
177+
### Implementing the `onAddScreenshot` Callback
178+
179+
If the above libraries do not cover your use case you can manually integrate screenshots by implementing the `onAddScreenshot` callback. The callback receives the `uri` of the image like in the example below.
180+
181+
```javascript
182+
import * as Sentry from '@sentry/react-native';
183+
import { getImage } from 'custom-image-picker';
184+
185+
const handleChooseImage = (addScreenshot: (uri: string) => void): void => {
186+
const { uri, error, canceled } = getImage();
187+
if (canceled) {
188+
console.log('User canceled image choice.');
189+
} else if (error) {
190+
console.log('Error during image loading', error);
191+
} else {
192+
addScreenshot(uri);
193+
}
194+
};
195+
196+
Sentry.feedbackIntegration({
197+
onAddScreenshot={handleChooseImage}
198+
});
199+
```

‎docs/platforms/react-native/user-feedback/index.mdx

+63-1
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,71 @@
11
---
22
title: Set Up User Feedback
3-
description: "Learn more about collecting user feedback when an event occurs. Sentry pairs the feedback with the original event, giving you additional insight into issues."
3+
description: "Learn how to enable User Feedback in your app."
44
sidebar_order: 6000
55
---
66

7+
The User Feedback feature allows you to collect user feedback from anywhere inside your application at any time, without needing an error event to occur first.
8+
9+
Note that if you're using a self-hosted Sentry instance, you'll need to be on version 24.4.2 or higher in order to use the full functionality of the User Feedback feature. Lower versions may have limited functionality.
10+
11+
## User Feedback Widget
12+
13+
The user feedback widget allows users to submit feedback from anywhere inside your application.
14+
15+
To collect user feedback from inside your application use the `showFeedbackWidget` method.
16+
17+
```javascript
18+
import * as Sentry from "@sentry/react-native";
19+
20+
Sentry.wrap(RootComponent);
21+
22+
Sentry.showFeedbackWidget();
23+
```
24+
25+
Note that [the root application component must be wrapped with `Sentry.wrap`](/platforms/react-native/#wrap-your-app) for the `showFeedbackWidget` method to work. The method depends on the React Native `Modal` implementation. It is supported fully in the legacy architecture. For the new architecture (Fabric renderer) it requires React Native `0.71` and up.
26+
27+
To configure the widget you can use the `Sentry.feedbackIntegration({})` or add it to your Sentry initialization.
28+
29+
```javascript
30+
import * as Sentry from "@sentry/react-native";
31+
32+
Sentry.init({
33+
dsn: "___PUBLIC_DSN___",
34+
35+
integrations: [
36+
Sentry.feedbackIntegration({
37+
// Additional SDK configuration goes in here, for example:
38+
styles:{
39+
submitButton: {
40+
backgroundColor: '#6a1b9a',
41+
},
42+
},
43+
namePlaceholder: 'Fullname',
44+
}),
45+
],
46+
});
47+
```
48+
49+
There are many options you can pass to the integration constructor. See the [configuration documentation](/platforms/react-native/user-feedback/configuration/) for more details.
50+
51+
### Feedback Widget Component
52+
53+
You can also integrate the `FeedbackWidget` component manually in your app.
54+
55+
```javascript
56+
import { FeedbackWidget } from "@sentry/react-native";
57+
58+
<FeedbackWidget/>
59+
```
60+
61+
For the full set of options you can pass to the `FeedbackWidget` component see the [configuration documentation](/platforms/react-native/user-feedback/configuration/).
62+
63+
<Alert>
64+
65+
Note that when the device is offline, the feedback will be stored locally and sent when the device is back online.
66+
67+
</Alert>
68+
769
## User Feedback API
870

971
The user feedback API allows you to collect user feedback while utilizing your own UI. You can use the same programming language you have in your app to send user feedback. In this case, the SDK creates the HTTP request so you don't have to deal with posting data via HTTP.

0 commit comments

Comments
 (0)