diff --git a/docs/platforms/javascript/common/user-feedback/configuration/index.mdx b/docs/platforms/javascript/common/user-feedback/configuration/index.mdx index c85d4a8762960..3d444ceb71a5e 100644 --- a/docs/platforms/javascript/common/user-feedback/configuration/index.mdx +++ b/docs/platforms/javascript/common/user-feedback/configuration/index.mdx @@ -1,7 +1,7 @@ --- title: Configuration sidebar_order: 6100 -description: "Learn about the general User Feedback configuration fields." +description: "Learn about general User Feedback configuration fields." --- @@ -22,7 +22,7 @@ The following options can be configured for the integration in `feedbackIntegrat | -------------- | ------------------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `autoInject` | `boolean` | `true` | Injects the Feedback widget into the application when the integration is added. Set `autoInject: false` if you want to call `feedback.attachTo()` or `feedback.createWidget()` directly, or only want to show the widget on certain views. | | `showBranding` | `boolean` | `true` | Displays the Sentry logo inside of the form. | -| `colorScheme` | "system" \| "light" \| "dark" | `"system"` | The color theme to use. `"system"` will follow your OS color scheme. | +| `colorScheme` | "system" \| "light" \| "dark" | `"system"` | Shows the color theme choices. `"system"` will use your OS color scheme. | | `id` | `string` | `sentry-feedback` | The `id` attribute of the `
` that contains the feedback widget. See [CSS Customization](#css-customization) for more. | ### Auto-Inject vs. Manual Injection @@ -48,16 +48,16 @@ Read more about how to [use your own UI](#bring-your-own-button) below. | Key | Type | Default | Description | | ------------------ | ------------------------ | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -| `showName` | `boolean` | `true` | Displays the name field on the Feedback form. | -| `showEmail` | `boolean` | `true` | Displays the email field on the Feedback form. | +| `showName` | `boolean` | `true` | Displays the name field on the feedback form. | +| `showEmail` | `boolean` | `true` | Displays the email field on the feedback form. | | `enableScreenshot` | `boolean` | `true` | Allows the user to send a screenshot attachment with their feedback. For self-hosted, release 24.4.2 is also required. | -| `isNameRequired` | `boolean` | `false` | Requires the name field on the Feedback form to be filled in. | -| `isEmailRequired` | `boolean` | `false` | Requires the email field on the Feedback form to be filled in. | +| `isNameRequired` | `boolean` | `false` | Requires the name field on the feedback form to be filled in. | +| `isEmailRequired` | `boolean` | `false` | Requires the email field on the feedback form to be filled in. | | `useSentryUser` | `Record` | `{ email: 'email', name: 'username'}` | Sets the `email` and `name` fields to the corresponding Sentry SDK user fields that were called with `Sentry.setUser`. | #### User Context -If you have set a user context by calling [`Sentry.setUser`](/platforms/javascript/enriching-events/identify-user/) then those values will be used as defaults for the `name` and `email` fields. If those fields are hidden from the user, then the default values will still be sent along with the feedback message. +If you've set a user context by calling `Sentry.setUser()`, those values will be used as defaults for the `name` and `email` fields. If those fields are hidden from the user, the default values will still be sent along with the feedback message. Below is an example configuration with non-default user fields. @@ -162,7 +162,7 @@ Colors can be customized by by defining CSS variables that override the default | `--success-color` | `successColor` | `#268d75` | `#2da98c` | Color used for success-related components (such as text color when feedback is submitted successfully). | | `--error-color` | `errorColor` | `#df3338` | `#f55459` | Color used for error related components (such as text color when there's an error submitting feedback). | | `--box-shadow` | `boxShadow` | `0px 4px 24px 0px rgba(43, 34, 51, 0.12)` | `0px 4px 24px 0px rgba(43, 34, 51, 0.12)` | Box shadow style used for the widget (injected button and form). | -| `--outline` | `outline` | `1px auto var(--accent-background)` | `1px auto var(--accent-background)` | Outline for form inputs when focused. | +| `--outline` | `outline` | `1px auto var(--accent-background)` | `1px auto var(--accent-background)` | Outline for form inputs when focused. | #### Theme priority @@ -207,7 +207,7 @@ feedbackIntegration({ ### Event Callbacks -Sometimes it’s important to know when a user started interacting with the feedback form, so you can add custom logging, or start/stop background timers on the page until the user is done. +Because it’s sometimes useful to know when a user started interacting with the feedback form, we've made it possible for you to add custom logging, or start and stop background timers on the page that tell you when the user is done. Pass these callbacks when you initialize the Feedback integration: @@ -222,7 +222,7 @@ feedbackIntegration({ ### Bring Your Own Button -You can skip the default injected button and use your own button to trigger displaying the form. Call `feedback.attachTo()` to have the SDK attach a click listener to your own button. You can additionally supply the same customization options that the constructor accepts (like for text labels and colors). +You can use your own button instead of the default injected button to trigger the form being displayed, by calling `feedback.attachTo()` to have the SDK attach a click listener to your button. You can also supply the same customization options that the constructor accepts (for example, for text labels and colors). ```javascript const feedback = feedbackIntegration({ @@ -265,8 +265,8 @@ function MyFeedbackButton() { You can also use your own UI components to gather feedback and pass the feedback data object to the `sendFeedback()` function. The `sendFeedback` function accepts two parameters: -- a JavaScript object with a required `message` property and additionally, optional `name` and `email` properties or a `FormData` instance with the same properties -- an optional "options" object +- A JavaScript object with a required `message` property and also optional `name` and `email` properties, or a `FormData` instance with the same properties. +- An optional "options" object. ```javascript Sentry.sendFeedback( @@ -281,7 +281,7 @@ Sentry.sendFeedback( ); ``` -Here is a simple example: +Here's a simple example: ```html
@@ -309,27 +309,27 @@ document You can customize the Crash-Report modal to your organization's needs, for example, for localization purposes. All options can be passed through the `Sentry.showReportDialog` call. -| Param | Default | -| ---------------- | ------------------------------------------------------------------------------------------------- | -| `eventId` | Manually set the id of the event. | -| `dsn` | Manually set dsn to report to. | -| `user` | Manually set user data _[an object with keys listed below]_. | -| `user.email` | User's email address. | -| `user.name` | User's name. | -| `lang` | _[automatic]_ – **override for Sentry’s language code** | -| `title` | It looks like we’re having issues. | -| `subtitle` | Our team has been notified. | -| `subtitle2` | If you’d like to help, tell us what happened below. – **not visible on small screen resolutions** | -| `labelName` | Name | -| `labelEmail` | Email | -| `labelComments` | What happened? | -| `labelClose` | Close | -| `labelSubmit` | Submit | -| `errorGeneric` | An unknown error occurred while submitting your report. Please try again. | -| `errorFormEntry` | Some fields were invalid. Please correct the errors and try again. | -| `successMessage` | Your feedback has been sent. Thank you! | -| `onLoad` | n/a - **an optional callback that will be invoked when the widget opens** | -| `onClose` | n/a - **an optional callback that will be invoked when the widget closes** | +| Param | Default | +| ---------------- | ---------------------------------------------------------------------------------------------------- | +| `eventId` | Manually set the id of the event. | +| `dsn` | Manually set dsn to report to. | +| `user` | Manually set user data _[an object with keys listed below]_. | +| `user.email` | User's email address. | +| `user.name` | User's name. | +| `lang` | _[automatic]_ – (**Override for Sentry’s language code.**) | +| `title` | It looks like we’re having issues. | +| `subtitle` | Our team has been notified. | +| `subtitle2` | If you’d like to help, tell us what happened below. – (**Not visible on small screen resolutions.**) | +| `labelName` | Name | +| `labelEmail` | Email | +| `labelComments` | What happened? | +| `labelClose` | Close | +| `labelSubmit` | Submit | +| `errorGeneric` | An unknown error occurred while submitting your report. Please try again. | +| `errorFormEntry` | Some fields were invalid. Please correct the errors and try again. | +| `successMessage` | Your feedback has been sent. Thank you! | +| `onLoad` | n/a - (**An optional callback that will be invoked when the widget opens.**) | +| `onClose` | n/a - (**An optional callback that will be invoked when the widget closes.**) | The optional callback `onLoad` will be called when users see the widget. You can use this to run custom logic, for example to log an analytics event: diff --git a/docs/platforms/javascript/common/user-feedback/v7/img/user-feedback-widget-customization.png b/docs/platforms/javascript/common/user-feedback/v7/img/user-feedback-widget-customization.png new file mode 100644 index 0000000000000..187dec6da57a6 Binary files /dev/null and b/docs/platforms/javascript/common/user-feedback/v7/img/user-feedback-widget-customization.png differ diff --git a/docs/platforms/javascript/common/user-feedback/v7/index.mdx b/docs/platforms/javascript/common/user-feedback/v7/index.mdx new file mode 100644 index 0000000000000..47584a6d14625 --- /dev/null +++ b/docs/platforms/javascript/common/user-feedback/v7/index.mdx @@ -0,0 +1,279 @@ +--- +title: Beta SDK +sidebar_order: 6900 +description: "Learn about general User Feedback configuration fields for version 7 of the JavaScript SDK." +--- + + + +In version 7 of our JavaScript SDK, User Feedback was released as a Beta integration. We recommend updating your SDK to version 8. + + + + + +## User Feedback Widget + +The User Feedback Widget offers many customization options, and if the available options are insufficient, you can [use your own UI](#bring-your-own-widget). The following image shows which elements are customizable. The configuration keys on the left of the image correspond to [text customization](#text-customization), while the ones on the right side are for [theme customizations](#theme-customization). + +![An image showing the available customization options for the User Feedback Widget](./img/user-feedback-widget-customization.png) + +### General + +The following options can be configured for the integration in `feedbackIntegration({})`: + +| Key | Type | Default | Description | +| -------------- | ------------------------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `autoInject` | `boolean` | `true` | Injects the Feedback widget into the application when the integration is added. Set `autoInject: false` if you want to call `feedback.attachTo()` or `feedback.openDialog()` directly, or only want to show the widget on certain views. | +| `showBranding` | `boolean` | `true` | Displays the Sentry logo inside of the form | +| `colorScheme` | "system" \| "light" \| "dark" | `"system"` | Shows the color theme choices. `"system"` will use your OS color scheme. | + +### User and Form + +| Key | Type | Default | Description | +| ------------------ | ------------------------ | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| `showName` | `boolean` | `true` | Displays the name field on the feedback form. | +| `showEmail` | `boolean` | `true` | Displays the email field on the feedback form. | +| `isNameRequired` | `boolean` | `false` | Requires the name field on the feedback form to be filled in. | +| `isEmailRequired` | `boolean` | `false` | Requires the email field on the feedback form to be filled in. | +| `useSentryUser` | `Record` | `{ email: 'email', name: 'username'}` | Sets the `email` and `name` fields to the corresponding Sentry SDK user fields that were called with `Sentry.setUser`. | + +By default, the Feedback integration will attempt to fill in the name and email fields if you've set a user context via `Sentry.setUser()`. The email and name fields are expected to be `email` and `username`. Below is an example configuration with non-default user fields: + +```javascript +Sentry.setUser({ + email: "foo@example.com", + fullName: "Jane Doe", +}); + +feedbackIntegration({ + useSentryUser: { + email: "email", + name: "fullName", + }, +}); +``` + +### Text Customization + +Most text that you see in the default Feedback widget can be customized. + +| Key | Default | Description | +| -------------------- | -------------------------------------- | ------------------------------------------------------------------ | +| `buttonLabel` | `Report a Bug` | The label of the injected button. | +| `submitButtonLabel` | `Send Bug Report` | The label of the submit button used in the feedback form. | +| `cancelButtonLabel` | `Cancel` | The label of the cancel button used in the feedback form. | +| `formTitle` | `Report a Bug` | The title at the top of the feedback form. | +| `nameLabel` | `Name` | The label of the name input field. | +| `namePlaceholder` | `Your Name` | The placeholder for the name input field. | +| `emailLabel` | `Email` | The label of the email input field. | +| `emailPlaceholder` | `your.email@example.org` | The placeholder for the email input field. | +| `messageLabel` | `Description` | The label for the feedback description input field. | +| `messagePlaceholder` | `What's the bug? What did you expect?` | The placeholder for the feedback description input field. | +| `successMessageText` | `Thank you for your report!` | The message to be displayed after a succesful feedback submission. | +| `isRequiredText` | `(required)` | The text displayed next to a required field. | + +Example of customization: + +```javascript +feedbackIntegration({ + buttonLabel: "Feedback", + submitButtonLabel: "Send Feedback", + formTitle: "Send Feedback", +}); +``` + +### Theme Customization + +Colors can be customized via the Feedback class constructor or by defining CSS variables on the injected button. If you use the default button it will have a property `id="sentry-feedback`, meaning you can use the `#sentry-feedback` selector to define CSS variables to override. + +| Key | CSS Variable | Light | Dark | Description | +| ------------------------- | ------------------------------ | ----------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------ | +| `background` | `--background` | `#ffffff` | `#29232f` | Background color of the widget (injected button and form). | +| `backgroundHover` | `--background-hover` | `#f6f6f7` | `#352f3b` | Background color of the injected button when in a hover state. | +| `foreground` | `--foreground` | `#2b2233` | `#ebe6ef` | Foreground color, e.g. text color. | +| `error` | `--error` | `#df3338` | `#f55459` | Color used for error related components (e.g. text color when there was an error submitting feedback). | +| `success` | `--success` | `#268d75` | `#2da98c` | Color used for success-related components (e.g. text color when feedback is submitted successfully). | +| `border` | `--border` | `1.5px solid rgba(41, 35, 47, 0.13)` | `1.5px solid rgba(235, 230, 239, 0.15)` | The border style used for the widget (injected button and form). | +| `borderRadius` | `--border-radius` | `12px` | `12px` | Border radius style used for the widget (injected button and success message). | +| `boxShadow` | `--box-shadow` | `0px 4px 24px 0px rgba(43, 34, 51, 0.12)` | `0px 4px 24px 0px rgba(43, 34, 51, 0.12)` | The box shadow style used for the widget (injected button and form). | +| `submitBackground` | `--submit-background` | `rgba(88, 74, 192, 1)` | `rgba(88, 74, 192, 1)` | Background color for the submit button. | +| `submitBackgroundHover` | `--submit-background-hover` | `rgba(108, 95, 199, 1)` | `rgba(108, 95, 199, 1)` | Background color when hovering over the submit button. | +| `submitBorder` | `--submit-border` | `rgba(108, 95, 199, 1)` | `rgba(108, 95, 199, 1)` | Border style for the submit button. | +| `submitOutlineFocus` | `--submit-outline-focus` | `rgba(108, 95, 199, 1)` | `rgba(108, 95, 199, 1)` | Outline color for the submit button, in the focused state. | +| `submitForeground` | `--submit-foreground` | `#ffffff` | `#ffffff` | Foreground color for the submit button. | +| `submitForegroundHover` | `--submit-foreground-hover` | `#ffffff` | `#ffffff` | Foreground color for the submit button when hovering. | +| `cancelBackground` | `--cancel-background` | `transparent` | `transparent` | Background color for the cancel button. | +| `cancelBackgroundHover` | `--cancel-background-hover` | `var(--background-hover)` | `var(--background-hover)` | Background color when hovering over the cancel button. | +| `cancelBorder` | `--cancel-border` | `var(--border)` | `var(--border)` | Border style for the cancel button. | +| `cancelOutlineFocus` | `--cancel-outline-focus` | `var(--input-outline-focus)` | `var(--input-outline-focus)` | Outline color for the cancel button, in the focused state. | +| `cancelForeground` | `--cancel-foreground` | `var(--foreground)` | `var(--foreground)` | Foreground color for the cancel button. | +| `cancelForegroundHover` | `--cancel-foreground-hover` | `var(--foreground)` | `var(--foreground)` | Foreground color for the cancel button when hovering. | +| `inputBackground` | `--input-background` | `inherit` | `inherit` | Background color for form inputs. | +| `inputForeground` | `--input-foreground` | `inherit` | `inherit` | Foreground color for form inputs. | +| `inputBorder` | `--input-border` | `var(--border)` | `var(--border)` | Border styles for form inputs. | +| `inputOutlineFocus` | `--input-outline-focus` | `rgba(108, 95, 199, 1)` | `rgba(108, 95, 199, 1)` | Outline color for form inputs when focused. | +| `formBorderRadius` | `--form-border-radius` | `20px` | `20px` | Border radius style for the form. | +| `formContentBorderRadius` | `--form-content-border-radius` | `6px` | `6px` | Border radius style for form content (for example: inputs, buttons). | + +Here is an example of customizing only the background color for the light theme using the Feedback constructor configuration: + +```javascript +feedbackIntegration({ + themeLight: { + background: "#cccccc", + }, +}); +``` + +Or the same example as above, but using the CSS variables method instead: + +```css +#sentry-feedback { + --background: #cccccc; +} +``` + +### Additional UI Customization + +These are additional CSS variables that can be overridden, similar to the theme customization above. They're not supported in the constructor. + +| Variable | Default | Description | +| --------------- | --------------------------------------- | ---------------------------------------------------------------------------------- | +| `--bottom` | `1rem` | By default, the widget has a position of fixed, and is in the bottom right corner. | +| `--right` | `1rem` | By default, the widget has a position of fixed, and is in the bottom right corner. | +| `--top` | `auto` | By default, the widget has a position of fixed, and is in the bottom right corner. | +| `--left` | `auto` | By default, the widget has a position of fixed, and is in the bottom right corner. | +| `--z-index` | `100000` | The z-index of the widget. | +| `--font-family` | `"'Helvetica Neue', Arial, sans-serif"` | Default font-family to use. | +| `--font-size` | `14px` | Font size. | + +### Event Callbacks + +Because it’s sometimes useful to know when a user started interacting with the feedback form, we've made it possible for you to add custom logging, or start and stop background timers on the page that tell you when the user is done. + +Pass these callbacks when you initialize the Feedback integration: + +```javascript +feedbackIntegration({ + onFormOpen: () => {}, + onFormClose: () => {}, + onSubmitSuccess: () => {}, + onSubmitError: () => {}, +}); +``` + +### Bring Your Own Button + +You can use your own button instead of the default injected button to trigger the form being displayed, by calling `feedback.attachTo()` to have the SDK attach a click listener to your button. You can also supply the same customization options that the constructor accepts (for example, for text labels and colors). + +```javascript +const feedback = feedbackIntegration({ + // Disable injecting the default widget + autoInject: false, +}); + +feedback.attachTo(document.querySelector("#your-button"), { + formTitle: "Report a Bug!", +}); +``` + +Alternatively, you can call `feedback.openDialog()`: + +```typescript +import { BrowserClient, Feedback, getClient } from "@sentry/react"; + +function MyFeedbackButton() { + const client = getClient(); + const feedback = client?.getIntegration(Feedback); + + // Don't render custom feedback button if Feedback integration isn't installed + if (!feedback) { + return null; + } + + return ( + + ); +} +``` + +### Bring Your Own Widget + +You can also use your own UI components to gather feedback and pass the feedback data object to the `sendFeedback()` function. The `sendFeedback` function accepts two parameters: + +- A JavaScript object with a required `message` property and also optional `name` and `email` properties, or a `FormData` instance with the same properties. +- An optional "options" object. + +```javascript +Sentry.sendFeedback( + { + name: "Jane Doe", // optional + email: "email@example.org", // optional + message: "This is an example feedback", // required + }, + { + includeReplay: true, // optional + } +); +``` + +Here's a simple example: + +```html + + + +