From 2404c450324bd02d1e329da215a9bee9f07401d6 Mon Sep 17 00:00:00 2001 From: Andrew McKnight Date: Wed, 21 Aug 2024 15:22:53 -0700 Subject: [PATCH] wip --- .../apple/common/user-feedback/index.mdx | 110 +++++++++++++++++- 1 file changed, 104 insertions(+), 6 deletions(-) diff --git a/docs/platforms/apple/common/user-feedback/index.mdx b/docs/platforms/apple/common/user-feedback/index.mdx index 76a65cd6d9f0f..a2f591b4e086c 100644 --- a/docs/platforms/apple/common/user-feedback/index.mdx +++ b/docs/platforms/apple/common/user-feedback/index.mdx @@ -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. -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 or the return value of the method capturing an event. +The User Feedback widget allows users to submit feedback from anywhere inside your application. - +### 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 + 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. + +### 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: "john.doe@example.com", + 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. \ No newline at end of file