diff --git a/develop-docs/application-architecture/feedback-architecture.mdx b/develop-docs/application-architecture/feedback-architecture.mdx index 94cb24b03a6a3..af7b45e3fe4ad 100644 --- a/develop-docs/application-architecture/feedback-architecture.mdx +++ b/develop-docs/application-architecture/feedback-architecture.mdx @@ -11,17 +11,17 @@ It will: ## Creation sources -When broken down, there are **5** ways to create feedback in our system 😵‍💫. -(But 4 of them, related to user reports, are quite similar!) A good reference is the +When broken down, there are **4** ways to create feedback in our system, with +3 sharing the same data model. A good reference is the `FeedbackCreationSource(Enum)` in [create_feedback.py](https://github.com/getsentry/sentry/blob/2b642e149c79b251e1c2f4339fc73d656347d74e/src/sentry/feedback/usecases/create_feedback.py#L33-L33). The 4 ways _clients_ can create feedback are: -`NEW_FEEDBACK_ENVELOPE`: [The new format](https://develop.sentry.dev/sdk/data-model/envelopes/#full-examples) created by the Replay team when adding +`NEW_FEEDBACK_ENVELOPE`: [The new format](/sdk/data-model/envelope-items/#user-feedback) created by the Replay team when adding the [User Feedback Widget](https://docs.sentry.io/product/user-feedback/#user-feedback-widget) to the JavaScript SDK. It allows adding more information, for example tags, release, url, etc. -`USER_REPORT_ENVELOPE`: [The older format](https://develop.sentry.dev/sdk/data-model/envelope-items/#user-feedback) with name/email/comments, that requires +`USER_REPORT_ENVELOPE`: [The older format](/sdk/data-model/envelope-items/#user-report) with name/email/comments, that requires `event_id` to link a Sentry error event. `USER_REPORT_DJANGO_ENDPOINT`: [The deprecated Web API](https://docs.sentry.io/api/projects/submit-user-feedback/) @@ -31,7 +31,7 @@ release, url, etc. ## How feedback is stored On the backend, each feedback submission in Sentry's UI is **an un-grouped issue occurrence**, -saved via the [issues platform](https://develop.sentry.dev/issue-platform/). +saved via the [issues platform](/issue-platform/). The entrypoint is [**`create_feedback_issue()`**](https://github.com/getsentry/sentry/blob/2b642e149c79b251e1c2f4339fc73d656347d74e/src/sentry/feedback/usecases/create_feedback.py#L184-L184), which @@ -42,7 +42,7 @@ which ## Feedback events -The new and preferred way to send feedback from the SDK is in an [event envelope](https://develop.sentry.dev/sdk/data-model/envelopes/#full-examples). +The preferred way of sending feedback from the SDK is in [feedback envelope](/sdk/data-model/envelope-items/#user-feedback). The format is the same as error events, except the `type` header = `"feedback"`. While user reports have an associated event, **new feedback _is_ an event**. This offers 2 improvements: @@ -94,7 +94,7 @@ In Relay v24.5.1, we migrated feedback to its own kafka topic + consumer, ### Attachments We only use attachments for the widget’s screenshot feature, which allows users -to submit **at most 1 screenshot per feedback**. Attachments are another [item type](https://develop.sentry.dev/sdk/data-model/envelopes/#attachment) +to submit **at most 1 screenshot per feedback**. Attachments are another [item type](/sdk/data-model/envelopes/#attachment) in an envelope. - SDK v8.0.0+, Relay v24.5.1+: Sends the feedback and attachment items in the same envelope. @@ -186,9 +186,7 @@ graph TD ### Envelopes -User reports are also sent to Relay in [envelope format](https://develop.sentry.dev/sdk/data-model/envelope-items/#user-feedback). -**This item type is misleadingly called “user feedback” in some of our docs, but the -item header will read `"user_report"`.** +User reports are also sent to Relay in envelope format, item type [user_report](/sdk/data-model/envelope-items/#user-report). The SDK function that sends these is `captureUserFeedback`. diff --git a/develop-docs/sdk/data-model/envelope-items.mdx b/develop-docs/sdk/data-model/envelope-items.mdx index 009412e1a683d..c5adff7fb6d2b 100644 --- a/develop-docs/sdk/data-model/envelope-items.mdx +++ b/develop-docs/sdk/data-model/envelope-items.mdx @@ -16,7 +16,7 @@ The headers described in this section are **in addition to the common headers**. ### Event -Item type `"event"`. This Item contains an error or default event payload +Item type `"event"`. This Item contains an error or default [event payload](/sdk/data-model/event-payloads/) encoded in JSON. **Constraints:** @@ -181,18 +181,101 @@ details. ### User Feedback -User Feedback was called User Report in the beginning. Therefore the envelope item type is `"user_report"`. -The item contains a user feedback / user report JSON payload: +Item type `"feedback"`. This Item contains an [event payload](/sdk/data-model/event-payloads/) encoded in JSON, with an additional `feedback` context object. + +Example payload: ```json -{"event_id":"9ec79c33ec9942ab8353589fcb2e04dc","email":"john@me.com","name":"John Me","comments":"It broke."}\n +{ + "event_id": "9ec79c33ec9942ab8353589fcb2e04dc", + "timestamp": "2011-05-02T17:41:36Z", + "platform": "javascript", + "level": "error", + "contexts": { + "feedback": { + "contact_email": "john@example.com", + "name": "John Smith", + "message": "I love session replay!", + "url": "https://sentry.io/replays/", + "associated_event_id": "32fd1995636d446385016e2747623e11", + "replay_id":"82840977e85b4ed3bc27f7b5b25cec15" + } + } +} ``` -**Attributes** +**Payload Attributes** + +We only document attributes for the `contexts.feedback` object, which is **required** +for this item type. For other attributes, see [Event Payloads](/sdk/data-model/event-payloads/). + +`message` + +: **String, required.** Comments of the user, describing what happened and/or sharing +feedback. The max length is **4096 characters**. + +`contact_email` + +: *String, optional.* The email of the user who submitted the feedback. If excluded, Sentry attempts to fill this in with user context. Anonymous feedbacks (no name or email) are still accepted. + +`name` + +: *String, optional.* The name of the user who submitted the feedback. If excluded, Sentry attempts to fill this in with user context. Anonymous feedbacks (no name or email) are still accepted. + +`url` + +: *String, optional.* The URL of the webpage the user was on when submitting feedback. + This may be used to search for or set alerts on feedback. + +`associated_event_id` + +: *UUID String, optional.* The identifier of an error event in the same project. + Use this to explicitly link a related error in the feedback UI. + +`replay_id` + +: *UUID String, optional.* The identifier of a related Session Replay in the same + project. Sentry uses this ID to render a Replay clip in the feedback UI. + +**Attaching Screenshots:** + +You can associate screenshots with a feedback by sending image data as +[attachment items](/sdk/data-model/envelope-items/#attachment), with `event_id` +corresponding to the feedback item. We recommend sending the items in the same +Envelope. + +**Constraints:** + +- This Item may occur at most once per Envelope. +- This Item is mutually exclusive with `"transaction"` items. + +**Required Envelope Headers:** `event_id` -: **UUID String, required.** The identifier of the event or transaction. +: **UUID String, required.** Corresponds to the `event_id` field of the event + payload. **It is not equal to the `associated_event_id`** field in the feedback + context. Clients are required to generate an event identifier ahead of time + and set it at least in the Envelope headers. If the identifier mismatches + between the Envelope and payload, the Envelope header takes precedence. + +### User Report - Deprecated +Item type `"user_report"`. This is an older way of submitting user feedback we +are have now deprecated. It continues to work so older SDKs won't break. But new implementation should follow the `feedback` item type described above. + +This item works by associating user information and comments with an event. If both the item and its associated event are accepted, we convert it to a user feedback. + +The item contains a JSON payload like this: +```json +{"event_id":"9ec79c33ec9942ab8353589fcb2e04dc","email":"john@example.com","name":"John Me","comments":"It broke."}\n +``` + +**Payload Attributes** + +`event_id` + +: **UUID String, required.** The identifier of the associated event, ideally +an error. `email` @@ -204,19 +287,25 @@ The item contains a user feedback / user report JSON payload: `comments` -: *String, recommended.* Comments of the user about what happened. +: *String, recommended.* Comments of the user about what happened. The max length is **4096 characters**. **Constraints:** - This Item may occur once per Envelope. -- User Feedbacks / Reports can be ingested separately from their events. We recommended to - send them in the same Envelope. +- User Reports can be ingested separately from their events. However, we recommend + sending them in the same Envelope. +- You may not associate multiple User Reports to the same event. +- The event can not be more than 30 minutes old. +- If the event does not exist in the same project or was never ingested, the report + is discarded and never converted to feedback. **Envelope Headers:** `event_id` -: **UUID String, required.** The identifier of the event or transaction. +: **UUID String, required.** Corresponds to the `event_id` field of the payload. + If the identifier mismatches between the Envelope and payload, the Envelope + header takes precedence. **Additional Item Headers:** diff --git a/develop-docs/sdk/expected-features/index.mdx b/develop-docs/sdk/expected-features/index.mdx index 6e289961777ab..47db946201eb9 100644 --- a/develop-docs/sdk/expected-features/index.mdx +++ b/develop-docs/sdk/expected-features/index.mdx @@ -147,7 +147,7 @@ Ability to get the ID of the last event sent. Event IDs are useful for correlati ## User Feedback -For all SDKs, it is strongly recommended to send the `User Feedback` as an [envelope item](/sdk/data-model/envelope-items/#user-feedback). Alternatively, the SDKs can +For all SDKs, it is strongly recommended to send the `User Feedback` as an [envelope item](/sdk/data-model/envelope-items/#user-report). Alternatively, the SDKs can use the [User Feedback endpoint](https://docs.sentry.io/api/projects/submit-user-feedback/), which is not recommended. ### User Facing Platforms