SDK 接入文档

快速开始

SDK 仅提供 API 接口能力，不包含 UI 组件。你可以灵活地在浏览器或服务端环境中使用。

1. 安装

npm install finch-feedback-sdk

或使用 CDN（浏览器）：

<script src="https://unpkg.com/finch-feedback-sdk/dist/index.global.js"></script>

2. 初始化

import { FinchSDK } from 'finch-feedback-sdk'

// 完全匿名（无任何身份信息）
const finch = new FinchSDK({
  projectId: 'your-project-id',
  apiUrl: 'https://your-finch-api.com',
  environment: 'production',  // 可选，标识当前运行环境
})

// 业务方已识别用户（外部用户）—— 后端会将反馈标记为 EXTERNAL
const finch2 = new FinchSDK({
  projectId: 'your-project-id',
  apiUrl: 'https://your-finch-api.com',
  user: { id: 'biz-user-123', name: '张三', email: 'zhangsan@example.com' },
})

// finch 平台用户（内部用户）—— 传入 finchUserId，后端校验存在性后标记 INTERNAL
const finch3 = new FinchSDK({
  projectId: 'your-project-id',
  apiUrl: 'https://your-finch-api.com',
  finchUserId: 'finch-user-abc',
})

后端按下面优先级自动判定反馈来源：finchUserId 在 finch User 表存在视为 INTERNAL，仅带 user 画像视为 EXTERNAL，都没有则为 ANONYMOUS。内部用户也允许同时传 user 作为补充画像，控制台展示时优先显示 finch 用户身份。

⚠️ finchUserId 仅做存在性校验，不做密码学验证。被冒充的最坏后果只是垃圾反馈被抬高优先级，对本产品的威胁模型可接受。需要更高强度身份证明请走下面的 OAuth 登录 流程。

配置选项

错误追踪

Finch SDK 提供运行时错误自动捕获和手动上报能力。SDK 会自动检测运行环境（浏览器 / Node.js），注册对应的全局错误处理器。

浏览器端接入

SDK 默认自动启用错误追踪，无需额外配置即可捕获全局错误和 console.error。如需自定义可传入 errors 配置：

const finch = new FinchSDK({
  projectId: 'your-project-id',
  apiUrl: 'https://your-finch-api.com',
  // errors 配置可选，以下为默认值：
  errors: {
    captureGlobalErrors: true,   // 自动拦截 window.onerror / unhandledrejection
    captureConsoleErrors: true,   // 拦截 console.error（捕获框架内部错误）
    maxErrorsPerMinute: 10,      // 客户端限流
    ignorePatterns: [             // 忽略匹配的错误消息（正则字符串）
      'ResizeObserver',
      'Script error',
    ],
  },
  // 完全禁用错误追踪：errors: false,
})

SDK 默认自动启用错误追踪，浏览器端会监听：

• window.onerror — 捕获未处理的运行时错误
• unhandledrejection — 捕获未处理的 Promise 拒绝
• console.error — 拦截 console.error 调用（仍会正常输出到控制台），自动提取 Error 对象的堆栈信息

服务端接入（Node.js / Bun）

import { FinchSDK } from 'finch-feedback-sdk'

const finch = new FinchSDK({
  projectId: 'your-project-id',
  apiUrl: 'https://your-finch-api.com',
  // 默认自动启用，可选自定义：
  errors: {
    captureGlobalErrors: true,   // 自动拦截 uncaughtException / unhandledRejection
    captureConsoleErrors: true,   // 拦截 console.error
    maxErrorsPerMinute: 10,
  },
})

服务端环境会自动监听：

• process.on('uncaughtException') — 捕获未处理异常
• process.on('unhandledRejection') — 捕获未处理的 Promise 拒绝

内部定时器使用 unref()，不会阻止进程正常退出。

手动上报错误

// 捕获 Error 对象
try {
  riskyOperation()
} catch (error) {
  await finch.captureError(error, {
    context: 'payment-processing',
    orderId: '12345',
  })
}

// 上报消息（非 Error 对象）
await finch.captureMessage('用户触发了异常操作', 'WARNING', {
  action: 'deleteAccount',
})

框架集成示例

Express / Hono 错误中间件：

app.use((err, req, res, next) => {
  finch.captureError(err, {
    method: req.method,
    path: req.path,
  })
  res.status(500).json({ error: 'Internal Server Error' })
})

Next.js App Router（error.tsx）：

'use client'
import { useEffect } from 'react'

export default function ErrorBoundary({ error }: { error: Error }) {
  useEffect(() => {
    finch.captureError(error)
  }, [error])

  return <div>Something went wrong</div>
}

错误去重机制

SDK 和服务端协作实现三层去重，避免高频错误导致数据库爆炸：

错误发生次数（eventCount）始终精确累计，但实际存储的事件详情行数被有效控制。 相同代码路径产生的错误会通过堆栈指纹自动归类到同一个错误组。

ErrorConfig 配置项

清理

SPA 卸载或服务端关闭时调用 destroy() 移除所有监听器和定时器：

finch.destroy()

提交反馈

// 不需要预先设置任何身份信息也能提交（匿名）
await finch.submitFeedback({
  type: 'BUG',         // BUG | UI | FEATURE | OTHER | AUTO
  description: '在 Safari 浏览器下首页无法正常显示',
  metadata: {          // 自定义元数据（可选）
    browser: 'Safari',
    os: 'macOS',
  },
})

// 业务方用户登录后调用 setUser，后续所有提交都会带上画像
finch.setUser({ id: 'biz-user-123', name: '张三', email: 'zhangsan@example.com' })

// 业务方用户登出
finch.clearUser()

在浏览器端，SDK 默认会自动捕获页面 HTML 快照并上传。通过 snapshot 和 snapshotOptions 配置可自定义此行为。服务端环境会自动跳过快照捕获。

OAuth 登录集成

通过 Finch OAuth，你可以让用户使用 Finch 账号登录，自动关联反馈信息到用户身份。

1. 创建 OAuth 应用

在 Finch 项目设置 → OAuth 应用 中创建应用，获取 client_id 和 client_secret。

2. 前端：引导用户登录

const finch = new FinchSDK({
  projectId: 'your-project-id',
  apiUrl: 'https://your-finch-api.com',
  oauth: {
    clientId: 'finch_xxxx',
    redirectUri: 'https://yourapp.com/callback',
  },
})

// 获取登录 URL，引导用户跳转
const loginUrl = finch.getLoginUrl()
window.location.href = loginUrl

3. 后端：用授权码换取令牌

用户授权后会重定向到回调地址，携带 code 参数。在你的后端服务中换取 access_token：

// 后端处理回调 (Node.js 示例)
import { FinchClient } from 'finch-feedback-sdk'

const client = new FinchClient({
  apiUrl: 'https://your-finch-api.com',
  projectId: 'your-project-id',
})

// 用 code 换取 access_token（需要 clientSecret，仅在后端使用）
const token = await client.exchangeCode({
  clientId: 'finch_xxxx',
  clientSecret: 'fncs_xxxx',
  redirectUri: 'https://yourapp.com/callback',
}, code)

// 获取用户信息
const user = await client.getUserInfo(token.access_token)
// => { id: 'user-id', name: '张三', email: 'user@example.com', image: '...' }

// 将 user.id 关联到你的系统用户

4. 拿 finch 用户信息后绑定 finchUserId

// 用 access_token 拉取 finch 用户信息
const user = await finch.getUserInfo(token.access_token)

// 把 finch userId 喂给 SDK，之后所有提交都标记为 INTERNAL
finch.setFinchUserId(user.id)

await finch.submitFeedback({
  type: 'BUG',
  description: '页面加载异常',
})

// 用户登出时
finch.clearFinchUserId()

说明：OAuth 流程在这里只是 finch 提供的「证明 finch 用户身份」的官方通道。如果接入方有自己的方式确认 finch 用户身份（比如先调过 /api/oauth/userinfo 然后把 userId 持久化），可以跳过这一步直接 setFinchUserId。

OAuth 端点参考

API 方法一览

环境兼容性