|
| 1 | +# End of Feedback Beta |
| 2 | + |
| 3 | +With the release of 8.0.0, Sentry Feedback is now out of Beta. This means that the usual stabilty guarantees apply. |
| 4 | + |
| 5 | +Feedback 8.0.0 requires server version 24.4.2 and above. |
| 6 | + |
| 7 | +Because of experimentation and rapid iteration, during the Beta period some bugs and problems came up which have since |
| 8 | +been fixed/improved, as well as API's which have been streamlined and changed. |
| 9 | + |
| 10 | +Below you can find a list of relevant feedback changes and issues that have been made from 7.x to 8.0.0. |
| 11 | + |
| 12 | +## Upgrading Feedback from 7.x to 8.0.0 |
| 13 | + |
| 14 | +We have streamlined the interface for interacting with the Feedback widget. Below is a list of public functions that |
| 15 | +existed in 7.x and a description of how they have changed in v8. |
| 16 | + |
| 17 | +| Method Name | Replacement | Notes | |
| 18 | +| ------------------------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 19 | +| `Sentry.getClient<BrowserClient>()?.getIntegration(Feedback)` | `const feedback = Sentry.getFeedback()` | Get a type-safe reference to the configured feedbackIntegration instance. | |
| 20 | +| `feedback.getWidget()` | `const widget = feedback.createWidget(); widget.appendToDom()` | The SDK no longer maintains a stack of form instances. If you call `createWidget()` a new widget will be inserted into the DOM and an `ActorComponent` returned allows you control over the lifecycle of the widget. | |
| 21 | +| `feedback.openDialog()` | `widget.open()` | Make the form inside the widget visible. | |
| 22 | +| `feedback.closeDialog()` | `widget.close()` | Make the form inside the widget hidden in the page. Success/Error messages will still be rendered and will hide themselves if the form was recently submitted. | |
| 23 | +| `feedback.removeWidget()` | `widget.removeFromDom()` | Remove the form and widget instance from the page. After calling this `widget.el.parentNode` will be set to null. | |
| 24 | +| `feedback.attachTo()` | `const unsubscribe = feedback.attachTo(myButtonElem)` | The `attachTo()` method will create an onClick event listener to your html element that calls `appendToDom()` and `open()`. It returns a callback to remove the event listener. | |
| 25 | +| - | `const form = await feedback.createForm()` | A new method `createForm()`, used internally by `createWidget()` and `attachTo()`, returns a `Promise<FeedbackDialog>` so you can control showing and hiding of the feedback form directly. | |
| 26 | + |
| 27 | +### API Examples |
| 28 | + |
| 29 | +#### Auto injecting Feedback |
| 30 | + |
| 31 | +The easiest way to get setup is to auto-inject the feedback widget. This will create a floating button which opens the |
| 32 | +feedback form. |
| 33 | + |
| 34 | +In your SDK setup: |
| 35 | + |
| 36 | +```javascript |
| 37 | +Sentry.init({ |
| 38 | + integrations: [ |
| 39 | + feedbackIntegration({ |
| 40 | + autoInject: true, |
| 41 | + }), |
| 42 | + ], |
| 43 | +}); |
| 44 | +``` |
| 45 | + |
| 46 | +`autoInject: true` is the default value. |
| 47 | + |
| 48 | +#### Attaching feedback to your own button |
| 49 | + |
| 50 | +If you don't want to have a floating button to trigger the feedback form, you can attach the form to your own DOM |
| 51 | +element instead. |
| 52 | + |
| 53 | +First, get a reference to the feedback integration instance: |
| 54 | + |
| 55 | +```javascript |
| 56 | +// Option 1: Keep a reference when you setup the sdk: |
| 57 | +const feedbackInstance = feedbackIntegration(); |
| 58 | +Sentry.init({ |
| 59 | + integrations: [feedbackInstance], |
| 60 | +}); |
| 61 | + |
| 62 | +// Option 2: Get a reference from the SDK client |
| 63 | +const feedbackInstance = getFeedback(); |
| 64 | +``` |
| 65 | + |
| 66 | +Next, call `attachTo()` |
| 67 | + |
| 68 | +```javascript |
| 69 | +const myButton = document.getElementById('my-button'); |
| 70 | +const unsubscribe = feedbackInstance.attachTo(myButton); |
| 71 | +``` |
| 72 | + |
| 73 | +This will insert the form into the DOM and show/hide it when the button is clicked. |
| 74 | + |
| 75 | +Later, if `my-button` is removed from the page be sure to call `unsubscribe()` or `feedbackInstance.remove()` to cleanup |
| 76 | +the event listeners. |
| 77 | + |
| 78 | +#### Manually managing show/hide state and adding/remove the form from the DOM. |
| 79 | + |
| 80 | +You can manually add/remove the widget from the page, and control when it's shown/hidden by calling the lifecycle |
| 81 | +methods directly. |
| 82 | + |
| 83 | +For example, `attachTo()` is a convenience wrapper over the lifecycle methods. You could re-implement it like this: |
| 84 | + |
| 85 | +```javascript |
| 86 | +function attachTo(button: HTMLElement) { |
| 87 | + const handleClick = () => { |
| 88 | + const widget = feedbackInstance.createWidget({ |
| 89 | + onFormClose: () => { |
| 90 | + widget.close(); |
| 91 | + }, |
| 92 | + onFormSubmited: () => { |
| 93 | + widget.removeFromDom(); |
| 94 | + } |
| 95 | + }); |
| 96 | + widget.appendToDom(); |
| 97 | + widget.open(); |
| 98 | + }; |
| 99 | + |
| 100 | + button.addEventListener('click', handleClick); |
| 101 | + return () => { |
| 102 | + button.removeEventListener('click', handleClick) |
| 103 | + } |
| 104 | +} |
| 105 | +``` |
| 106 | + |
| 107 | +Alternatively you can call `createForm()` and control the form directly: |
| 108 | + |
| 109 | +```javascript |
| 110 | +const formPromise = feedbackInstance.createForm(); |
| 111 | + |
| 112 | +// Automatically insert and open the dialog after 5 seconds |
| 113 | +// then close and remove it after another 10 seconds |
| 114 | +setTimeout(() => { |
| 115 | + const form = await formPromise; |
| 116 | + form.appendToDom(); |
| 117 | + form.open(); |
| 118 | + |
| 119 | + setTimeout(() => { |
| 120 | + form.close(); |
| 121 | + form.removeFromDom(); |
| 122 | + }, 10_000); |
| 123 | +}, 5_000); |
| 124 | +``` |
| 125 | + |
| 126 | +## Config changes in v8 |
| 127 | + |
| 128 | +Added new configuration values |
| 129 | + |
| 130 | +| Field Name | Type | Description | |
| 131 | +| ------------------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 132 | +| `enableScreenshot` | `boolean` | Default: true. Enable this option to allow a user to choose to include a screenshot of the webpage with their feedback submission. The user option is not supported on mobile browsers and will have no effect there. | |
| 133 | +| `onFormSubmitted` | `() => void` | Callback whenever the feedback form is submitted, but before success/failure is returned. | |
| 134 | + |
| 135 | +Some new configuration values have been added & changed so you can tweak instructions, or translate labels for your |
| 136 | +users. |
| 137 | + |
| 138 | +| Old Name | New Name | Default Value | |
| 139 | +| ---------------- | ----------------------- | ------------------------------ | |
| 140 | +| `buttonLabel` | `triggerLabel` | `"Report a bug"` | |
| 141 | +| `isRequiredText` | `isRequiredLabel` | `"(required)"` | |
| 142 | +| - | `addScreenshotLabel` | `"Add a screenshot"` | |
| 143 | +| - | `removeScreenshotLabel` | `"Remove Screenshot"` | |
| 144 | +| - | `confirmButtonLabel` | `"Confirm"` | |
| 145 | +| - | `successMessageText` | `"Thank you for your report!"` | |
| 146 | + |
| 147 | +Some theme/color configuration values have been added & changed to make it easier to style the widget. Refer to the |
| 148 | +[Feedback Configuration docs](https://docs.sentry.io/platforms/javascript/user-feedback/configuration/#user-feedback-widget) |
| 149 | +to see the supported fields and their default values. |
0 commit comments