按平台安装
任意网站
安装 npm install @blipit/browser
Blipit 浏览器 SDK 只有 10 KB。它会捕获未捕获的错误、未处理的 promise rejection 和失败的请求,保留导致每个错误的点击和请求,记录 Web 指标,在每个页面放置“报告问题”按钮,并可在发生错误时录制会话回放。在打包应用中通过 npm 安装,或在任意页面中加入一个 script 标签。
1获取密钥
登录 app.blipit.io,打开侧边栏中的“API 密钥”,然后选择你的项目。每个项目有两个密钥。公钥以 blipit_pk_ 开头:它用于浏览器和应用代码,只能发送事件,任何人看到都没关系。私密密钥以 blipit_sk_ 开头:它留在你的服务器或 Odoo 中,切勿放进浏览器,因为它还可以读取和更改问题。私密密钥只在创建后显示一次,请当时就复制;如果丢失,请点击“创建新的密钥”,旧密钥会立即失效。部分 SDK 还需要项目 id,它显示在同一页面上。
2使用 npm
在入口文件中、应用渲染之前,用公钥调用一次 init。使用 Vite(React、Vue、Svelte)时,把密钥以 VITE_BLIPIT_KEY 保存在 .env 中;只有 VITE_ 开头的变量会传到浏览器,而且开发服务器只在启动时读取 .env。
npm install @blipit/browserVITE_BLIPIT_KEY=blipit_pk_your_public_keyimport * as Blipit from "@blipit/browser";
Blipit.init({
key: import.meta.env.VITE_BLIPIT_KEY,
environment: import.meta.env.MODE,
release: "2026.09.28",
replay: { onErrorSampleRate: 1 },
});3不用打包器:一个 script 标签
把这段代码粘贴到每个页面的 <head> 中,或粘贴到你所用平台的自定义代码位置,并写入你的公钥。这没有问题:公钥只能发送事件。
<script src="https://blipit.io/sdk/blipit.js"></script>
<script>
Blipit.init({ key: "blipit_pk_your_public_key", environment: "production", release: "2026.09.28", replay: { onErrorSampleRate: 1 } });
</script>4不要把密钥放进 git
请把密钥保存在环境变量或托管平台的密钥设置中,切勿写进你提交的代码,并把 .env 文件加入 .gitignore。网页中出现公钥是正常的。如果私密密钥曾出现在 git、公开页面、截图或聊天中,请打开“API 密钥”,点击“创建新的密钥”,并在所有用过旧密钥的地方粘贴新密钥:旧密钥会立即失效。
.env
.env.local
.env.*.local5告诉 Blipit 用户是谁(可选)
登录后附加用户信息,问题就能显示受影响的人,回放也可以按用户查找。
Blipit.setUser({ id: "42", email: "ana@example.com" });6React、Vue、Angular 和 Svelte:上报已捕获的错误
框架会在浏览器看到之前捕获组件内部的错误,所以也要把这些错误传给 Blipit。其他地方未捕获的错误会自动上报。
createRoot(document.getElementById("root")!, {
onCaughtError: (error) => Blipit.captureException(error),
onUncaughtError: (error) => Blipit.captureException(error),
}).render(<App />);class ErrorBoundary extends React.Component<{ children: React.ReactNode }, { failed: boolean }> {
state = { failed: false };
static getDerivedStateFromError() {
return { failed: true };
}
componentDidCatch(error: Error) {
Blipit.captureException(error);
}
render() {
return this.state.failed ? <p>Something went wrong.</p> : this.props.children;
}
}const app = createApp(App);
app.config.errorHandler = (err) => Blipit.captureException(err);
app.mount("#app");import { ErrorHandler } from "@angular/core";
import * as Blipit from "@blipit/browser";
class BlipitErrorHandler implements ErrorHandler {
handleError(error: unknown) {
Blipit.captureException(error);
console.error(error);
}
}
export const appConfig = { providers: [{ provide: ErrorHandler, useClass: BlipitErrorHandler }] };import * as Blipit from "@blipit/browser";
import type { HandleClientError } from "@sveltejs/kit";
export const handleError: HandleClientError = ({ error }) => {
Blipit.captureException(error);
};10预填报告器并添加上下文
在用户登录后调用 setUser:报告者的姓名和邮箱会自动填写,你回复或更改状态时对方会收到邮件。setReportMetadata 会把你自己的字段(例如套餐或购物车数量)添加到每份报告中;它在报告发送时运行,因此值始终是最新的。
Blipit.setUser({ id: "42", username: "Ana Lima", email: "ana@example.com" });
Blipit.setReportMetadata(() => ({ plan: "pro", cartItems: cart.length }));11全部选项和函数
- key:公钥(blipit_pk_)。必填。
- environment 和 release:显示在每个事件上;release 用于回归检测和 source map。environment 默认为 production。
- debug: true 会把 SDK 的操作记录到控制台,每行以 [blipit] 开头。
- sampleRate(0 到 1)、ignoreErrors(字符串或正则)和 beforeSend(修改事件,或返回 null 以丢弃)控制发送的内容。autoMuteExtensions(默认开启)会丢弃仅来自浏览器扩展的错误。
- webVitals(默认开启)、replay({ sessionSampleRate, onErrorSampleRate })和 autoSessionTracking(无崩溃率,需要 release)。
- feedbackWidget: false 会隐藏“报告问题”按钮;传入包含 position、style、text、color、font、match 和 shortcut 的对象则可更改它。theme: "light"、"dark" 或 "auto" 设置报告器的主题。
- user({ id, name, email })和 company(名称或 { id, name })会填入报告器并添加到报告中。
- endpoint:仅用于自托管的接收服务;默认值为 https://in.blipit.io/api/v1/events。
- 函数:captureException(error)、captureMessage(text, level)、setUser、setTag(key, value)、addBreadcrumb({ category, message })、openReport()、attachReport(element)、reportButton(options)、updateWidget(options)、setReportMetadata(fn)、showFeedback() 和 flush(),后者在排队的事件发送完成后返回一个 promise。
- 在仪表板中更改的小组件设置最多一小时内会传到浏览器,因为 SDK 会缓存这么久;无痕窗口会立即显示更改。
12验证是否生效
重新加载你的网站。右下角会出现“报告问题”按钮,一分钟内页面浏览会显示在 app.blipit.io 的“Web 指标”下。然后发送一个测试事件:在代码中调用一次 captureMessage,或者在使用 script 标签时,在浏览器控制台中运行下面这一行。它会在几秒内出现在“问题”下。
Blipit.captureMessage("Hello from " + location.host, "info");须知
- 选项:sampleRate(0 到 1)、ignoreErrors(字符串或正则)、beforeSend 用于丢弃或修改事件、maxBreadcrumbs、webVitals(默认开启)、autoSessionTracking 用于无崩溃率(需要 release)。
- blipit.io/sdk/blipit.js 始终提供最新版本(0.3.23)。如果你想自行控制升级,固定版本位于 blipit.io/sdk/0.3.23/blipit.js。
- 如果你的网站发送 Content Security Policy,请允许 script-src https://blipit.io(script 标签,以及首次使用时从 blipit.io/sdk/<version>/ 加载的报告编辑器和回放插件)、connect-src https://in.blipit.io(事件、截图和屏幕录制都发送到 in.blipit.io)、img-src data:(截图由页面的一张图片绘制而成)和 media-src blob:(录制内容在报告窗口中播放)。截图会重新加载页面的图片和字体,因此它们的主机也要加入 connect-src,否则会显示为空白。无需修改 style-src。使用 script 标签时,请从你自己的 .js 文件中调用 Blipit.init,或为内联脚本设置 nonce,因为严格的策略会阻止内联脚本。 要在屏幕录制中录入声音,网站的 Permissions-Policy 头必须允许 microphone=(self),屏幕录制还需要 display-capture=(self);设置为 microphone=() 时,录制没有声音。
- 让 Blipit 保持最新:《让 Blipit 保持最新》指南(docs.blipit.io/updates)介绍了更新横幅、重要版本的邮件、开发控制台中的提示以及此平台的更新命令。
- 每个应用每个平台一个项目:每个项目在创建时选择自己的平台(Android、iOS、React Native、Flutter、Web、Backend 或 Odoo),Blipit 会以明确的错误拒绝来自其他平台的数据,所以 iOS 应用和 Android 应用需要两个项目、两个密钥。各平台的发布、版本、崩溃率和商店构建都不同,混在一个项目里会让这些数据全部失真。Web 项目也接收同一 Web 应用的服务器端数据(Next.js 服务器或 Node),React Native 或 Flutter 项目也接收它自己的 Android 和 iOS 原生崩溃报告。
遇到问题?发邮件至 support@blipit.io。每个项目的密钥和项目 id 在 app.blipit.io 的“API 密钥”下。





