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.

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
110 changes: 104 additions & 6 deletions docs/platforms/apple/common/user-feedback/index.mdx
Original file line number Diff line number Diff line change
@@ -1,15 +1,113 @@
---
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 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.
armcknight marked this conversation as resolved.
Show resolved Hide resolved

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 an optional configuration in your SentryOptions when starting the SDK:

```swift
SentrySDK.start { options in
options.enableUserFeedbackIntegration = true
options.configureUserFeedback = { config in
armcknight marked this conversation as resolved.
Show resolved Hide resolved
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.

### Customization

You can customize the widget by setting various properties in the `SentryUserFeedbackWidgetConfiguration` and `SentryUserFeedbackFormConfiguration` classes:

```swift
let widgetConfig = SentryUserFeedbackWidgetConfiguration()
widgetConfig.autoInject = true
widgetConfig.triggerLabel = "Feedback"
widgetConfig.triggerAccessibilityLabel = "Submit Feedback"

// Form customization
let formConfig = SentryUserFeedbackFormConfiguration()
formConfig.showName = true
formConfig.isNameRequired = false
formConfig.enableScreenshot = true
formConfig.formTitle = "Report an Issue"
formConfig.submitButtonLabel = "Submit"
formConfig.cancelButtonLabel = "Cancel"

let feedbackConfig = SentryUserFeedbackConfiguration { config in
config.widgetConfig = widgetConfig
config.uiFormConfig = formConfig
}

let feedbackIntegration = SentryUserFeedbackIntegration(configuration: feedbackConfig)
feedbackIntegration.createWidget()
```

This configuration customizes the widget's button text, form fields, and whether the user can attach screenshots.

### 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 `captureFeedback` method in the `SentryUserFeedbackIntegration` class:

```swift
feedbackIntegration.captureFeedback(
message: "I encountered a bug while using the app.",
name: "John Doe",
email: "[email protected]",
hints: ["page": "Settings"]
)
```

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.

## Crash-Report Modal

The Cocoa-based Crash-Report Modal is a customizable feature that prompts users for feedback when an error occurs. This modal captures the user's name, email, and a description of the issue, pairing the feedback with the event in Sentry.

### Integration

To integrate the Crash-Report Modal in your Cocoa app, configure it in your Sentry initialization:

```swift
SentrySDK.showReportDialog(eventId: eventId) {
print("Crash report dialog shown")
}
```

This will display a modal dialog where users can provide feedback related to a specific error event.

---

This adapted documentation aligns with the changes and functionality we implemented in the Cocoa platform, providing clear instructions for setting up and customizing the User Feedback widget in a Cocoa application.
armcknight marked this conversation as resolved.
Show resolved Hide resolved
Loading