配置

了解用户反馈的通用配置字段。

用户反馈小部件提供了许多自定义选项,如果这些选项不足以满足需求,您可以使用自己的 UI

以下配置选项适用于 JavaScript SDK 8.0.0 及以上版本。SDK 7 版本中的反馈小部件是 beta 版,并已弃用。

显示用户反馈小部件可用自定义选项的图像

以下选项可以在 feedbackIntegration({}) 中配置:

类型默认值描述
autoInjectbooleantrue当集成被添加时,注入反馈小部件到应用程序中。如果您想直接调用 feedback.attachTo()feedback.createWidget(),或仅在某些视图中显示小部件,请设置 autoInject: false
showBrandingbooleantrue在表单内显示 Sentry 标志。
colorScheme"system" | "light" | "dark""system"显示颜色主题选择。"system" 将使用您的操作系统颜色方案。
idstringsentry-feedback包含反馈小部件的 <div>id 属性。更多内容请参阅 CSS 自定义
tagsRecord<string, number | string | boolean | bigint | symbol | null | undefined>{}标签 用于设置在反馈事件上。

如果 autoInject: true,一个按钮将被插入页面中,触发表单弹出,以便用户输入反馈。如果您希望控制何时进行此注入,可以调用 feedback.createWidget() 方法获取一个 Actor 对象的引用,然后调用 appendToDom() 将其插入页面。

Copied
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({}) 中配置:

类型默认值描述
showNamebooleantrue在反馈表单中显示姓名字段。
showEmailbooleantrue在反馈表单中显示电子邮件字段。
enableScreenshotbooleantrue允许用户随反馈发送截图附件。对于自托管,还需要 24.4.2 版本。
isNameRequiredbooleanfalse要求反馈表单中的姓名字段必须填写。
isEmailRequiredbooleanfalse要求反馈表单中的电子邮件字段必须填写。
useSentryUserRecord<string, string>{ email: 'email', name: 'username'}emailname 字段设置为与调用 Sentry.setUser 时对应的 Sentry SDK 用户字段。

如果您通过调用 Sentry.setUser() 设置了用户上下文,这些值将作为 nameemail 字段的默认值。如果这些字段对用户隐藏,默认值仍将随反馈消息一起发送。

以下是一个带有非默认用户字段的示例配置。

Copied
Sentry.setUser({
  fullName: "Jane Doe",
  email: "foo@example.com",
});

feedbackIntegration({
  useSentryUser: {
    name: "fullName",
    email: "email",
  },
});

默认反馈小部件中显示的大多数文本都可以自定义。

以下选项可以在 feedbackIntegration({}) 中配置:

默认值描述
triggerLabel"Report a Bug"打开反馈表单的注入按钮的标签。
triggerAriaLabeltriggerLabel || "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!"成功提交反馈后显示的消息。

自定义示例:

Copied
feedbackIntegration({
  buttonLabel: "Feedback",
  submitButtonLabel: "Send Feedback",
  formTitle: "Send Feedback",
});

您可以自定义反馈组件在页面上的位置,以及浅色和深色模式下的字体和主题颜色。

在所有情况下,您可以通过设置 CSS 变量来覆盖任何值。默认情况下,<div> 容器具有属性 id="sentry-feedback",因此您可以使用 #sentry-feedback 选择器来定义 CSS 变量以覆盖默认值。

下面的示例展示了如何通过覆盖 CSS 变量来自定义浅色和深色主题的背景颜色:

Copied
#sentry-feedback {
  --trigger-background: #cccccc;
}
@media (prefers-color-scheme: dark) {
  #sentry-feedback {
    --trigger-background: #222222;
  }
}

或者,您也可以通过在 JavaScript 中设置主题值来实现相同的效果:

Copied
feedbackIntegration({
  themeLight: {
    background: "#cccccc",
  },
  themeDark: {
    background: "#222222",
  },
});

以下值仅作为 CSS 变量提供,并适用于浅色和深色主题。

CSS 变量默认值描述
--font-family"system-ui, 'Helvetica Neue', Arial, sans-serif"默认字体。
--font-size14px字体大小。
--z-index100000小部件的 z-index。
--insetauto 0 0 auto默认情况下,小部件具有固定位置,并位于右下角。
--page-margin16px小部件与屏幕边缘的距离。这也接受简写值,例如 10px 20px 30px 10px 分别表示上/右/下/左边距。

颜色可以通过定义覆盖默认值的 CSS 变量或通过在 feedbackIntegration({}) 中传递 themeLight 和/或 themeDark 来自定义。

CSS 变量配置键默认浅色模式默认深色模式描述
--foregroundforeground#2b2233#ebe6ef前景(文本)颜色。
--backgroundbackground#ffffff#29232f小部件的背景颜色(注入按钮和表单)。
--accent-foregroundaccentForeground#ffffff#ffffff提交按钮的前景颜色。
--accent-backgroundaccentBackgroundrgba(88, 74, 192, 1)rgba(88, 74, 192, 1)提交按钮的背景颜色。
--success-colorsuccessColor#268d75#2da98c成功相关组件使用的颜色(例如成功提交反馈时的文本颜色)。
--error-colorerrorColor#df3338#f55459错误相关组件使用的颜色(例如提交反馈时出错的文本颜色)。
--box-shadowboxShadow0px 4px 24px 0px rgba(43, 34, 51, 0.12)0px 4px 24px 0px rgba(43, 34, 51, 0.12)小部件(注入按钮和表单)使用的阴影样式。
--outlineoutline1px auto var(--accent-background)1px auto var(--accent-background)表单输入框聚焦时的轮廓。

CSS 变量优先于 feedbackIntegration() 中的配置值。在这个例子中,配置似乎可以使文本为 白色黑色,但由于设置了 CSS 变量,文本将始终为 红色

Copied
<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 变量时的选择器。

Copied
<script>
  feedbackIntegration({
    id: "feedback-theme", // The default is 'sentry-feedback'
  });
</script>

<style>
  #feedback-theme {
    /* Target the custom id */
    --foreground: "red";
  }
</style>

有时了解用户何时开始与反馈表单交互非常有用,因此我们允许您添加自定义日志记录,或在页面上启动和停止后台计时器,以告知您用户何时完成操作。

以下选项可以在 feedbackIntegration({}) 中配置:

Copied
feedbackIntegration({
  onFormOpen: () => {},
  onFormClose: () => {},
  onSubmitSuccess: (data: FeedbackFormData) => {},
  onSubmitError: (error: Error) => {},
});

您可以使用自己的按钮代替默认的注入按钮来触发表单显示,通过调用 feedback.attachTo() 让 SDK 为您的按钮附加点击监听器。您还可以提供与构造函数接受的相同的自定义选项(例如,文本标签和颜色)。

Copied
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 以及最终显示给用户的时间。

Copied
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 属性以及可选的 nameemail 属性的 JavaScript 对象。
  • 一个可选的 "hints" 对象。
Copied
Sentry.captureFeedback(
  {
    name: "Jane Doe", // optional
    email: "email@example.org", // optional
    message: "This is an example feedback", // required
  },
  {
    includeReplay: true, // optional
    attachments: [], // optional
  },
);

这里是一个简单的示例:

Copied
<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 用户,feedbackIntegrationfeedbackSyncIntegration 的别名。对于 CDN 用户,feedbackIntegrationfeedbackAsyncIntegration 的别名。

如果您通过 NPM 安装了 SDK,默认使用此加载策略。如果通过 CDN 安装 SDK,则无法使用此策略。

此集成包含渲染“发送反馈”按钮以及点击按钮时触发的表单所需的所有代码。选择此加载策略意味着接受应用程序中最大的初始包大小。这样做的好处是,当用户与反馈小部件交互时,可以确保小部件能够打开,但无论如何,发送反馈消息都需要网络连接。

如果您通过 CDN 安装了 SDK,默认使用此加载策略。如果您使用 NPM 安装,仍然可以通过在 Sentry.init 调用中添加此集成来选择使用此加载策略。

此集成仅包含页面加载时在屏幕上显示“发送反馈”按钮所需的最小代码量。当用户点击该按钮时,集成将从 https://browser.sentry-cdn.com 异步加载内部集成以显示表单并允许用户输入反馈消息。这样做的好处是包大小最小。缺点是,如果用户有广告拦截器,异步加载可能会失败。

对于 CDN 用户,feedbackIntegrationfeedbackAsyncIntegration 的别名。

Copied
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 用户,feedbackIntegrationfeedbackSyncIntegration 的别名。

Copied
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您的反馈已发送。感谢!
onLoadn/a - (当小部件打开时调用的可选回调。)
onClosen/a - (当小部件关闭时调用的可选回调。)

可选回调 onLoad 在用户看到小部件时被调用。您可以使用此回调来运行自定义逻辑,例如记录分析事件:

Copied
Sentry.showReportDialog({
  // ...
  onLoad() {
    // Log an event to amplitude when the report dialog opens
    amplitude.logEvent("report_dialog_seen");
  },
});

可选回调 onClose 在用户关闭小部件时被调用。您可以使用此回调来运行自定义逻辑,例如重新加载页面:

需要 JS SDK 版本 v7.82.0 或更高。

Copied
Sentry.showReportDialog({
  // ...
  onClose() {
    // Refresh the page after the user closes the report dialog
    location.reload();
  },
});