跳到主要内容

安装 Feedback Widget

Almirant Feedback Widget 让应用程序的用户能够直接向项目提交反馈。反馈会作为条目进入 Almirant 的创意看板，您可以在那里进行分类、确定优先级并将其转换为工作项。

有两种安装方式：使用脚本标签（适用于任何网站），或使用 React/Next.js 软件包。

脚本标签（HTML）​

这是最简单的方式。无论使用何种框架，均适用于任何网站。

1. 获取公钥​

  1. 在您的 Almirant 项目中，前往 设置 > 集成 > Feedback Widget
  2. 复制公钥（pk_...）

2. 添加脚本​

在 HTML 中的闭合 </body> 标签之前添加以下行：

<script src="https://cdn.almirant.ai/feedback-widget.iife.js"></script>
<script>
  FeedbackWidget.init({
    publicKey: 'pk_your_public_key',
    position: 'bottom-right',
    theme: 'auto',
  });
</script>

完成。您的网站右下角会出现一个浮动按钮。点击它会打开一个用于提交反馈的表单。

完整 HTML 示例​

<!DOCTYPE html>
<html lang="zh-Hans">
<head>
  <meta charset="UTF-8">
  <title>我的应用程序</title>
</head>
<body>
  <h1>欢迎使用我的应用程序</h1>

  <!-- Almirant Feedback Widget -->
  <script src="https://cdn.almirant.ai/feedback-widget.iife.js"></script>
  <script>
    FeedbackWidget.init({
      publicKey: 'pk_your_public_key',
      position: 'bottom-right',
      theme: 'auto',
    });
  </script>
</body>
</html>

React / Next.js​

如果您的应用程序使用 React 或 Next.js，可以使用包含组件和 Hook 的官方软件包。

1. 安装软件包​

bun add @almirant/feedback-react

或使用 npm：

npm install @almirant/feedback-react

2. 使用组件​

import { FeedbackWidget } from '@almirant/feedback-react';

export default function App() {
  return (
    <>
      <main>
        <h1>我的应用程序</h1>
      </main>

      <FeedbackWidget
        publicKey="pk_your_public_key"
        position="bottom-right"
        theme="auto"
      />
    </>
  );
}

在 Next.js App Router 中使用​

在使用 App Router 的 Next.js 中，将小部件放在根布局中，以便在所有页面上都可用：

// app/layout.tsx
import { FeedbackWidget } from '@almirant/feedback-react';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="zh-Hans">
      <body>
        {children}
        <FeedbackWidget
          publicKey="pk_your_public_key"
          position="bottom-right"
          theme="auto"
        />
      </body>
    </html>
  );
}
注意

FeedbackWidget 组件仅在客户端渲染。无需在布局中使用 'use client'；该组件会在内部处理。

在 Next.js Pages Router 中使用​

// pages/_app.tsx
import { FeedbackWidget } from '@almirant/feedback-react';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <FeedbackWidget
        publicKey="pk_your_public_key"
        position="bottom-right"
        theme="auto"
      />
    </>
  );
}

配置选项​

脚本标签和 React 组件均接受相同的选项：

选项类型默认值描述
publicKeystring--（必填）您项目的公钥（pk_...）
positionstring'bottom-right'按钮位置：'bottom-right'、'bottom-left'、'top-right'、'top-left'
themestring'auto'视觉主题：'light'、'dark'、'auto'（检测系统偏好）
提示

使用 theme: 'auto'，让小部件自动适应用户浏览器的浅色/深色模式偏好。如果您的应用程序有自己的主题切换控件，可以动态传入 'light' 或 'dark'。

有关高级视觉自定义选项，请参阅自定义页面。