Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Cocoa User Feedback #11191

Open
wants to merge 8 commits into
base: master
Choose a base branch
from
+211 −7
Open

Cocoa User Feedback #11191

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
2404c45
wip
armcknight Aug 21, 2024
ba6ee47
early pr feedback
armcknight Sep 3, 2024
996c961
Merge remote-tracking branch 'origin/master' into armcknight/feat(use…
armcknight Jan 11, 2025
3098036
reformat code snippet, update a couple things to align with current i…
armcknight Jan 11, 2025
553d56f
copy over javascript config doc
armcknight Jan 11, 2025
541ecfc
convert to swift doc
armcknight Jan 11, 2025
2fec940
remove the config image, since it's not accurate for iOS
armcknight Jan 11, 2025
12e4e79
remove redundant customization docs; remove crash dialog
armcknight Jan 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
154 changes: 154 additions & 0 deletions docs/platforms/apple/common/user-feedback/configuration/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,154 @@
---
title: Beta SDK
sidebar_order: 6900
description: "Learn about general User Feedback configuration fields for version TBD of the sentry-cocoa SDK."
---

<PlatformSection notSupported={["apple.macos", "apple.tvos", "apple.watchos", "apple.visionos"]}>

## 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).

### General

The following options can be configured for the integration in `SentryUserFeedbackConfiguration`:

| Key | Type | Default | Description |
| ----------------------- | ------------------------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `autoInject` | `Bool` | `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. |
| `animations` | `Bool` | `true` | Whether or not to show animations, like for presenting and dismissing the form. |
| `useShakeGesture` | `Bool` | `false` | Use a shake gesture to display the form. |
| `showFormForScreenshots`| `Bool` | `false` | Any time a user takes a screenshot, bring up the form with the screenshot attached. |
| `tags` | `[String: Any]` | `nil` | Tags to set on the feedback event. This is a dictionary where keys are strings and values can be different data types such as `NSNumber`, `NSString`, etc. |
| `useSentryUser` | `Bool` | `false` | Sets the email and name field text content to `SentryUser.email` and `SentryUser.name`. |

### User and Form

You can customize which form elements are shown, whether they are required, and even prefill some info, in `SentryUserFeedbackFormConfiguration`:

| Key | Type | Default | Description |
| ------------------ | ------------------------ | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `showBranding` | `Bool` | `true` | Displays the Sentry logo inside of the form |
| `showName` | `Bool` | `true` | Displays the name field on the feedback form. |
| `showEmail` | `Bool` | `true` | Displays the email field on the feedback form. |
| `isNameRequired` | `Bool` | `false` | Requires the name field on the feedback form to be filled in. |
| `isEmailRequired` | `Bool` | `false` | Requires the email field on the feedback form to be filled in. |
| `useSentryUser` | `Bool` | `true` | Sets the `email` and `name` fields to the corresponding Sentry SDK user fields that were called with `Sentry.setUser`. |

Example:

```swift
SentrySDK.start { options in
options.configureForm { form in
form.isEmailRequired = true
form.useSentryUser = false
}
}
```

### Text Customization

Most text that you see in the default Feedback widget can be customized via `SentryUserFeedbackThemeConfiguration`:

| Key | Default | Description |
| ----------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `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` | `[email protected]` | 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 successful feedback submission. |
| `isRequiredText` | `(required)` | The text displayed next to a required field. |

Example of customization:

```swift
SentrySDK.start { options in
options.configureUserFeedback { config in
config.configureForm { form in
form.isRequiredText = "*"
form.title = "We want to hear from you!"
}
}
}
```

### Theme Customization

Colors can be customized via the top-level config object, configuring for both light and dark themes.

| Key | CSS Variable | Light | Dark | Description |
| ------------------------- | ------------------------------ | ----------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `foreground` | `--foreground` | `#2b2233` | `#ebe6ef` | Foreground text color of the widget and form. |
| `background` | `--background` | `#ffffff` | `#29232f` | Background color of the widget and form. |
| `submitForeground` | `--submit-foreground` | `#ffffff` | `#ffffff` | Foreground color for the form submit button. |
| `submitBackground` | `--submit-background` | `rgba(88, 74, 192, 1)` | `rgba(88, 74, 192, 1)` | Background color for the form submit button. |
| `buttonForeground` | `--cancel-foreground` | Same as `foreground` | Same as `foreground` | Foreground color for the cancel and screenshot buttons. |
| `buttonBackground` | `--cancel-background` | `transparent` | `transparent` | Background color for the form cancel and screenshot buttons. |
| `successColor` | `--success` | `#268d75` | `#2da98c` | Color used for success-related components. |
| `errorColor` | `--error` | `#df3338` | `#f55459` | Color used for error-related components. |
| `inputBackground` | `--input-background` | `inherit` | `inherit` | Background color for form inputs. |
| `inputForeground` | `--input-foreground` | `inherit` | `inherit` | Foreground color for form inputs. |

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

```swift
SentrySDK.start { options in
options.configureUserFeedback { config in
// configureTheme is used for light themes on iOS versions that support dark mode, and as the sole theme configuration for earlier iOS versions that don't support dark mode
config.configureTheme { theme in
theme.background = .init(color: .yellow)
}
config.configureDarkTheme { theme in
theme.background = .init(color: .darkGray)
}
}
}
```

### 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 |
| --------------- | --------------------------------------- | ---------------------------------------------------------------------------------- |
| `SentryUserFeedbackWidgetConfiguration.location` | `[NSDirectionalRectEdge.bottom, NSDirectionalRectEdge.trailing]` | By default, the widget has a appears in the bottom trailing corner. |
| `SentryUserFeedbackWidgetConfiguration.windowLevel` | `UIWindow.Level.normal + 1` | The window level of the widget button. |
| `SentryUserFeedbackFormConfiguration.fontFamily` | `nil` | The font family to use for form text elements. Defaults to the system font. |

### 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.

Set these callbacks in `SentryUserFeedbackConfiguration`:

| Key | Type | Default | Description |
| `onFormOpen` | `() -> Void` | `nil` | Called when the feedback form is opened. |
| `onFormClose` | `() -> Void` | `nil` | Called when the feedback form is closed. |
| `onSubmitSuccess` | `([String: Any]) -> Void` | `nil` | Called when feedback is successfully submitted via the prepared form. |
| `onSubmitError` | `(Error) -> Void` | `nil` | Called when there is an error submitting feedback via the prepared form. |

### Bring Your Own Button

You can use your own button instead of the default injected button to trigger the form being displayed, by calling `SentrySDK.showUserFeedbackForm()` from your button's action handler.

### Bring Your Own Widget

You can also use your own UI components to gather feedback and pass the feedback data object to the `SentrySDK.capture(feedback: SentryFeedback)` function.

```swift
SentrySDK.capture(feedback: .init(
message: "This is an example feedback", // required
name: "Jane Doe", // optional
email: "[email protected]", // optional
source: .custom,
screenshot: somePngImageData // optional
));
```

</PlatformSection>
60 changes: 54 additions & 6 deletions docs/platforms/apple/common/user-feedback/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,63 @@
---
title: Set Up User Feedback
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."
description: "Learn how to enable User Feedback in your Cocoa app."
sidebar_order: 6000
---

When a user experiences an error, Sentry provides the ability to collect additional feedback. You can collect feedback according to the method supported by the SDK.
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.

## User Feedback API
<Note>
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.
</Note>

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.
## User Feedback Widget

Sentry pairs the feedback with the original event, giving you additional insight into issues. Sentry needs the `eventId` to be able to associate the user feedback to the corresponding event. For example, to get the `eventId`, you can use <PlatformLink to="/configuration/options/#before-send"><PlatformIdentifier name="before-send" /></PlatformLink> or the return value of the method capturing an event.
The User Feedback widget allows users to submit feedback from anywhere inside your application.

<PlatformContent includePath="user-feedback/sdk-api-example/" />
### Pre-requisites

Ensure that your project is set up with Sentry and that you have added the Sentry Cocoa SDK to your project.

### Installation

1. Install the Sentry Cocoa SDK using CocoaPods, Carthage, or Swift Package Manager.
2. Ensure you are using version 8.35.0 or above of the SDK to access the latest features.

### Set Up

To start using the User Feedback widget in your Cocoa application, enable the feedback integration and provide a configuration in your SentryOptions when starting the SDK:

```swift
SentrySDK.start { options in
options.configureUserFeedback = { config in
config.onSubmitSuccess = { data in
print("Feedback submitted successfully: \(data)")
}
config.onSubmitError = { error in
print("Failed to submit feedback: \(error)")
}
}
}
```

This setup will insert the widget into your app's view hierarchy. By default, it appears in the bottom trailing corner of the screen, but you can fully customize its appearance and behavior.

### Session Replay

The User Feedback widget integrates seamlessly with Session Replay. When the widget is opened, the Replay SDK buffers up to 30 seconds of the user's session. If feedback is submitted, this replay is sent along with the feedback, allowing you to view both the feedback and the user's actions leading up to the feedback submission.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bruno-garcia @brustolin I'm not sure if the 30 second thing checks out or not. All I'm doing is attaching any available session replay id when I package the envelope. Let me know if we need to look into this some more.


### User Feedback API

The User Feedback API allows you to collect user feedback while using your own UI components. You can submit feedback directly using the `SentrySDK.capture(feedback:)` method:

```swift
SentrySDK.capture(feedback: .init(
message: "I encountered a bug while using the app.",
name: "John Doe",
email: "[email protected]"
))
```

This method associates the feedback with the corresponding event in Sentry, giving you valuable insights into user issues.

Alternatively, you can use the [User Feedback API endpoint](/api/projects/submit-user-feedback/) directly if you prefer to handle the HTTP request manually.
Loading
Loading