Sentry Integration for Feedback

This SDK is considered experimental and in an alpha state. It may experience breaking changes, and may be discontinued at any time. Please reach out on GitHub if you have any feedback/concerns.

Pre-requisites

@sentry-internal/feedback currently can only be used by browsers with Shadow DOM support.

Installation

During the alpha phase, the feedback integration will need to be imported from @sentry-internal/feedback. This will be changed for the general release.

npm add @sentry-internal/feedback

Setup

To set up the integration, add the following to your Sentry initialization. This will inject a feedback button to the bottom right corner of your application. Users can then click it to open up a feedback form where they can submit feedback.

Several options are supported and passable via the integration constructor. See the configuration section below for more details.

import * as Sentry from '@sentry/browser';
// or from a framework specific SDK, e.g.
// import * as Sentry from '@sentry/react';
import { Feedback } from '@sentry-internal/feedback';

Sentry.init({
  dsn: '__DSN__',
  integrations: [
    new Feedback({
      // Additional SDK configuration goes in here, for example:
      // See below for all available options
    })
  ],
  // ...
});

Configuration

General Integration Configuration

The following options can be configured as options to the integration, in new Feedback({}):

User/form Related Configuration

By default the Feedback integration will attempt to fill in the name/email fields if you have set a user context via Sentry.setUser. By default it expects the email and name fields to be email and username. Below is an example configuration with non-default user fields.

Sentry.setUser({
    email: 'foo@example.com',
    fullName: 'Jane Doe',
});


new Feedback({
    useSentryUser({
        email: 'email',
        name: 'fullName',
    }),
})

Text Customization

Most text that you see in the default Feedback widget can be customized.

Example of customization

new Feedback({
  buttonLabel: 'Feedback',
  submitButtonLabel: 'Send Feedback',
  formTitle: 'Send Feedback',
});

Theme Customization

Colors can be customized via the Feedback constructor or by defining CSS variables on the widget button. If you use the default widget button, it will have an id="sentry-feedback, meaning you can use the #sentry-feedback selector to define CSS variables to override.

Here is an example of customizing only the background color for the light theme using the Feedback constructor configuration.

new Feedback({
    themeLight: {
        background: "#cccccc",
    },
})

Or the same example above but using the CSS variables method:

#sentry-feedback {
  --background: #cccccc;
}

Additional UI Customization

Similar to theme customization above, these are additional CSS variables that can be overridden. Note these are not supported in the constructor.

Event Callbacks

Sometimes it’s important to know when someone has started to interact with the feedback form, so you can add custom logging, or start/stop background timers on the page until the user is done.

Pass these callbacks when you initialize the Feedback integration:

new Feedback({
  onActorClick: () => {},
  onDialogOpen: () => {},
  onDialogClose: () => {},
  onSubmitSuccess: () => {},
  onSubmitError: () => {},
});

Further Customization

There are two more methods in the integration that can help customization.

Bring Your Own Button

You can skip the default widget button and use your own button. 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 (e.g. for text labels and colors).

const feedback = new Feedback({
  // Disable injecting the default widget
  autoInject: false,
});

feedback.attachTo(document.querySelector('#your-button'), {
    formTitle: "Report a Bug!"
});

Bring Your Own Widget

You can also bring your own widget and UI and simply pass a feedback object to the sendFeedback() function.

<form id="my-feedback-form">
  <input name="name" />
  <input name="email" />
  <textarea name="message" placeholder="What's the issue?" />
</form>

<script>
document.getElementById('my-feedback-form').addEventListener('submit', (event) => {
  const formData = new FormData(event.currentTarget);
  Feedback.sendFeedback(formData);
  event.preventDefault();
});
</script>

Alerting on User Feedback Reports

Note: The following instructions are to be followed in the Sentry product.

If you have Sentry's default issue alert ("Alert me on every new issue") turned on for the project you are setting up User Feedback on, no action is required to have alerting on each user feedback report.

If you don't have Sentry's default issue alert turned on, follow these steps:

1. Navigate to Create New Alert Rule in Sentry (Click "Alerts" in the left-nav menu, "Create Alert" in the top right corner, ensure the "Issues" radio button is selected under the "Errors" category, and then click "Set Conditions")
2. In "Set conditions", add an "IF" filter for The issue's category is equal to "Feedback"
3. Add any other alert rules