配置
了解用户反馈的通用配置字段。
用户反馈小部件提供了许多自定义选项,如果这些选项不足以满足需求,您可以使用自己的 UI。
以下配置选项适用于 JavaScript SDK 8.0.0 及以上版本。SDK 7 版本中的反馈小部件是 beta 版,并已弃用。
以下选项可以在 feedbackIntegration({})
中配置:
键 | 类型 | 默认值 | 描述 |
---|---|---|---|
autoInject | boolean | true | 当集成被添加时,注入反馈小部件到应用程序中。如果您想直接调用 feedback.attachTo() 或 feedback.createWidget() ,或仅在某些视图中显示小部件,请设置 autoInject: false 。 |
showBranding | boolean | true | 在表单内显示 Sentry 标志。 |
colorScheme | "system" | "light" | "dark" | "system" | 显示颜色主题选择。"system" 将使用您的操作系统颜色方案。 |
id | string | sentry-feedback | 包含反馈小部件的 <div> 的 id 属性。更多内容请参阅 CSS 自定义。 |
tags | Record<string, number | string | boolean | bigint | symbol | null | undefined> | {} | 标签 用于设置在反馈事件上。 |
如果 autoInject: true
,一个按钮将被插入页面中,触发表单弹出,以便用户输入反馈。如果您希望控制何时进行此注入,可以调用 feedback.createWidget()
方法获取一个 Actor
对象的引用,然后调用 appendToDom()
将其插入页面。
const feedback = feedbackIntegration({
// Disable the injection of the default widget
autoInject: false,
});
// Create and render the button
const widget = feedback.createWidget();
// Later, when it's time to clean up:
widget.removeFromDom();
有关如何使用自己的 UI的更多信息,请参阅下文。
以下选项可以在 feedbackIntegration({})
中配置:
键 | 类型 | 默认值 | 描述 |
---|---|---|---|
showName | boolean | true | 在反馈表单中显示姓名字段。 |
showEmail | boolean | true | 在反馈表单中显示电子邮件字段。 |
enableScreenshot | boolean | true | 允许用户随反馈发送截图附件。对于自托管,还需要 24.4.2 版本。 |
isNameRequired | boolean | false | 要求反馈表单中的姓名字段必须填写。 |
isEmailRequired | boolean | false | 要求反馈表单中的电子邮件字段必须填写。 |
useSentryUser | Record<string, string> | { email: 'email', name: 'username'} | 将 email 和 name 字段设置为与调用 Sentry.setUser 时对应的 Sentry SDK 用户字段。 |
如果您通过调用 Sentry.setUser()
设置了用户上下文,这些值将作为 name
和 email
字段的默认值。如果这些字段对用户隐藏,默认值仍将随反馈消息一起发送。
以下是一个带有非默认用户字段的示例配置。
Sentry.setUser({
fullName: "Jane Doe",
email: "foo@example.com",
});
feedbackIntegration({
useSentryUser: {
name: "fullName",
email: "email",
},
});
默认反馈小部件中显示的大多数文本都可以自定义。
以下选项可以在 feedbackIntegration({})
中配置:
键 | 默认值 | 描述 |
---|---|---|
triggerLabel | "Report a Bug" | 打开反馈表单的注入按钮的标签。 |
triggerAriaLabel | triggerLabel || "Report a Bug" | 打开反馈表单的注入按钮的 aria 标签。从 SDK v8.20.0 开始可用。 |
formTitle | "Report a Bug" | 反馈表单顶部的标题。 |
submitButtonLabel | "Send Bug Report" | 反馈表单中提交按钮的标签。 |
cancelButtonLabel | "Cancel" | 反馈表单中取消按钮的标签。 |
confirmButtonLabel | "Confirm" | 反馈表单中确认按钮的标签。 |
addScreenshotButtonLabel | "Add a screenshot" | 添加截图按钮的标签。 |
removeScreenshotButtonLabel | "Remove screenshot" | 移除截图按钮的标签。 |
nameLabel | "Name" | 姓名输入字段的标签。 |
namePlaceholder | "Your Name" | 姓名输入字段的占位符。 |
emailLabel | "Email" | 电子邮件输入字段的标签。 |
emailPlaceholder | "your.email@example.org" | 电子邮件输入字段的占位符。 |
isRequiredLabel | "(required)" | 必填输入字段旁边的标签。 |
messageLabel | "Description" | 反馈描述输入字段的标签。 |
messagePlaceholder | "What's the bug? What did you expect?" | 反馈描述输入字段的占位符。 |
successMessageText | "Thank you for your report!" | 成功提交反馈后显示的消息。 |
自定义示例:
feedbackIntegration({
buttonLabel: "Feedback",
submitButtonLabel: "Send Feedback",
formTitle: "Send Feedback",
});
您可以自定义反馈组件在页面上的位置,以及浅色和深色模式下的字体和主题颜色。
在所有情况下,您可以通过设置 CSS 变量来覆盖任何值。默认情况下,<div>
容器具有属性 id="sentry-feedback"
,因此您可以使用 #sentry-feedback
选择器来定义 CSS 变量以覆盖默认值。
下面的示例展示了如何通过覆盖 CSS 变量来自定义浅色和深色主题的背景颜色:
#sentry-feedback {
--trigger-background: #cccccc;
}
@media (prefers-color-scheme: dark) {
#sentry-feedback {
--trigger-background: #222222;
}
}
或者,您也可以通过在 JavaScript 中设置主题值来实现相同的效果:
feedbackIntegration({
themeLight: {
background: "#cccccc",
},
themeDark: {
background: "#222222",
},
});
以下值仅作为 CSS 变量提供,并适用于浅色和深色主题。
CSS 变量 | 默认值 | 描述 |
---|---|---|
--font-family | "system-ui, 'Helvetica Neue', Arial, sans-serif" | 默认字体。 |
--font-size | 14px | 字体大小。 |
--z-index | 100000 | 小部件的 z-index。 |
--inset | auto 0 0 auto | 默认情况下,小部件具有固定位置,并位于右下角。 |
--page-margin | 16px | 小部件与屏幕边缘的距离。这也接受简写值,例如 10px 20px 30px 10px 分别表示上/右/下/左边距。 |
颜色可以通过定义覆盖默认值的 CSS 变量或通过在 feedbackIntegration({})
中传递 themeLight
和/或 themeDark
来自定义。
CSS 变量 | 配置键 | 默认浅色模式 | 默认深色模式 | 描述 |
---|---|---|---|---|
--foreground | foreground | #2b2233 | #ebe6ef | 前景(文本)颜色。 |
--background | background | #ffffff | #29232f | 小部件的背景颜色(注入按钮和表单)。 |
--accent-foreground | accentForeground | #ffffff | #ffffff | 提交按钮的前景颜色。 |
--accent-background | accentBackground | rgba(88, 74, 192, 1) | rgba(88, 74, 192, 1) | 提交按钮的背景颜色。 |
--success-color | successColor | #268d75 | #2da98c | 成功相关组件使用的颜色(例如成功提交反馈时的文本颜色)。 |
--error-color | errorColor | #df3338 | #f55459 | 错误相关组件使用的颜色(例如提交反馈时出错的文本颜色)。 |
--box-shadow | boxShadow | 0px 4px 24px 0px rgba(43, 34, 51, 0.12) | 0px 4px 24px 0px rgba(43, 34, 51, 0.12) | 小部件(注入按钮和表单)使用的阴影样式。 |
--outline | outline | 1px auto var(--accent-background) | 1px auto var(--accent-background) | 表单输入框聚焦时的轮廓。 |
CSS 变量优先于 feedbackIntegration()
中的配置值。在这个例子中,配置似乎可以使文本为 白色
或 黑色
,但由于设置了 CSS 变量,文本将始终为 红色
。
<script>
feedbackIntegration({
themeLight: {
foreground: "black",
},
themeDark: {
foreground: "white",
},
});
</script>
<style>
#sentry-feedback {
--foreground: "red"; /* overrides both `white` and `black` colors */
}
</style>
您可以将 id
配置值设置为不同于默认的 sentry-feedback
,并使用该自定义 ID 作为覆盖 CSS 变量时的选择器。
<script>
feedbackIntegration({
id: "feedback-theme", // The default is 'sentry-feedback'
});
</script>
<style>
#feedback-theme {
/* Target the custom id */
--foreground: "red";
}
</style>
有时了解用户何时开始与反馈表单交互非常有用,因此我们允许您添加自定义日志记录,或在页面上启动和停止后台计时器,以告知您用户何时完成操作。
以下选项可以在 feedbackIntegration({})
中配置:
feedbackIntegration({
onFormOpen: () => {},
onFormClose: () => {},
onSubmitSuccess: (data: FeedbackFormData) => {},
onSubmitError: (error: Error) => {},
});
您可以使用自己的按钮代替默认的注入按钮来触发表单显示,通过调用 feedback.attachTo()
让 SDK 为您的按钮附加点击监听器。您还可以提供与构造函数接受的相同的自定义选项(例如,文本标签和颜色)。
const feedback = feedbackIntegration({
// Disable the injection of the default widget
autoInject: false,
});
feedback.attachTo(document.querySelector("#your-button"), {
formTitle: "Report a Bug!",
});
或者,您可以调用 feedback.createForm()
并完全控制表单的加载、添加到 DOM 以及最终显示给用户的时间。
const feedback = feedbackIntegration({
// Disable the injection of the default widget
autoInject: false,
});
const form = await feedback.createForm();
form.appendToDom();
form.open();
您还可以使用自己的 UI 组件来收集反馈,并将反馈数据对象传递给 captureFeedback()
函数。captureFeedback
函数接受两个参数:
- 一个包含必需的
message
属性以及可选的name
和email
属性的 JavaScript 对象。 - 一个可选的 "hints" 对象。
Sentry.captureFeedback(
{
name: "Jane Doe", // optional
email: "email@example.org", // optional
message: "This is an example feedback", // required
},
{
includeReplay: true, // optional
attachments: [], // optional
},
);
这里是一个简单的示例:
<form id="my-feedback-form">
<input name="name" placeholder="Your Name" />
<input name="email" placeholder="Your Email" />
<textarea name="message" placeholder="What's the issue?" />
<input type="file" name="attachment" />
<button type="submit">Submit</button>
</form>
由于 feedbackIntegration
是面向用户的集成,我们提供了两种对包大小有影响的加载策略。
对于大多数用户,我们建议在 Sentry.init
调用中使用 feedbackIntegration
。这将以良好的默认配置设置用户反馈,匹配您的环境。
本页面上的所有代码示例都默认使用 feedbackIntegration
,因为它无论您选择的是 CDN 还是 NPM 安装方法都可用。然而,feedbackIntegration
的实现对于这两种安装方法是不同的。对于 NPM 用户,feedbackIntegration
是 feedbackSyncIntegration
的别名。对于 CDN 用户,feedbackIntegration
是 feedbackAsyncIntegration
的别名。
如果您通过 NPM 安装了 SDK,默认使用此加载策略。如果通过 CDN 安装 SDK,则无法使用此策略。
此集成包含渲染“发送反馈”按钮以及点击按钮时触发的表单所需的所有代码。选择此加载策略意味着接受应用程序中最大的初始包大小。这样做的好处是,当用户与反馈小部件交互时,可以确保小部件能够打开,但无论如何,发送反馈消息都需要网络连接。
如果您通过 CDN 安装了 SDK,默认使用此加载策略。如果您使用 NPM 安装,仍然可以通过在 Sentry.init
调用中添加此集成来选择使用此加载策略。
此集成仅包含页面加载时在屏幕上显示“发送反馈”按钮所需的最小代码量。当用户点击该按钮时,集成将从 https://browser.sentry-cdn.com
异步加载内部集成以显示表单并允许用户输入反馈消息。这样做的好处是包大小最小。缺点是,如果用户有广告拦截器,异步加载可能会失败。
对于 CDN 用户,feedbackIntegration
是 feedbackAsyncIntegration
的别名。
import * as Sentry from "@sentry/browser";
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
integrations: [
// Use the default strategy, an alias for `feedbackAsyncIntegration`
Sentry.feedbackIntegration({
// Additional SDK configuration goes in here, for example:
colorScheme: "system",
}),
],
});
对于 NPM 用户,feedbackIntegration
是 feedbackSyncIntegration
的别名。
import * as Sentry from "@sentry/browser";
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
integrations: [
// Use the default strategy, an alias for `feedbackSyncIntegration`
Sentry.feedbackIntegration({
// Additional SDK configuration goes in here, for example:
colorScheme: "system",
}),
],
});
您可以根据组织的需求自定义崩溃报告模态框,例如用于本地化。所有选项都可以通过 Sentry.showReportDialog
调用传递。
参数 | 默认值 |
---|---|
eventId | 手动设置事件的 ID。 |
dsn | 手动设置要报告到的 DSN。 |
user | 手动设置用户数据 [包含以下键的对象]。 |
user.email | 用户的电子邮件地址。 |
user.name | 用户的姓名。 |
lang | [自动] – (覆盖 Sentry 的语言代码。) |
title | 看起来我们遇到了一些问题。 |
subtitle | 我们的团队已收到通知。 |
subtitle2 | 如果您愿意帮助,请在下方告诉我们发生了什么。– (在小屏幕分辨率下不可见。) |
labelName | 姓名 |
labelEmail | 电子邮件 |
labelComments | 发生了什么? |
labelClose | 关闭 |
labelSubmit | 提交 |
errorGeneric | 在提交您的报告时发生了一个未知错误。请重试。 |
errorFormEntry | 某些字段无效。请修正错误并重试。 |
successMessage | 您的反馈已发送。感谢! |
onLoad | n/a - (当小部件打开时调用的可选回调。) |
onClose | n/a - (当小部件关闭时调用的可选回调。) |
可选回调 onLoad
在用户看到小部件时被调用。您可以使用此回调来运行自定义逻辑,例如记录分析事件:
Sentry.showReportDialog({
// ...
onLoad() {
// Log an event to amplitude when the report dialog opens
amplitude.logEvent("report_dialog_seen");
},
});
可选回调 onClose
在用户关闭小部件时被调用。您可以使用此回调来运行自定义逻辑,例如重新加载页面:
需要 JS SDK 版本 v7.82.0 或更高。
Sentry.showReportDialog({
// ...
onClose() {
// Refresh the page after the user closes the report dialog
location.reload();
},
});