按平台安装
iOS、Android、Flutter、React Native
安装 one package per platform
每个平台都有一个接收公钥和项目 id 的 Blipit 包,全部基于 Blipit 自有内核构建,内部不含第三方崩溃库:blipit-android v0.7.5、blipit-swift 0.8.0、@blipit/react-native 0.6.3 和 blipit_flutter 0.5.3。崩溃、ANR、卡死和未捕获的异常会自动上报,先写入磁盘,在下次启动时发送;离线队列会保留报告,直到网络恢复。原生崩溃请保留调试符号,因为目前还不读取符号文件。
1获取密钥
登录 app.blipit.io,打开侧边栏中的“API 密钥”,然后选择你的项目。每个项目有两个密钥。公钥以 blipit_pk_ 开头:它用于浏览器和应用代码,只能发送事件,任何人看到都没关系。私密密钥以 blipit_sk_ 开头:它留在你的服务器或 Odoo 中,切勿放进浏览器,因为它还可以读取和更改问题。私密密钥只在创建后显示一次,请当时就复制;如果丢失,请点击“创建新的密钥”,旧密钥会立即失效。部分 SDK 还需要项目 id,它显示在同一页面上。
2React Native
该包会链接一个小型原生模块,用于启动 Blipit 自己的 Android 和 iOS SDK 以捕获原生崩溃;其 Gradle 文件会自动添加 JitPack 仓库。包装根组件,渲染错误也会被上报。
npm install @blipit/react-native
npx pod-installimport * as Blipit from "@blipit/react-native";
Blipit.init({ key: "<public key>", project: <project id>, environment: "production", release: "myapp@1.4.2" });
export default Blipit.wrap(App);3Flutter
把 main.dart 中的 runApp 替换为 Blipit.init。插件会启动 Blipit 自己的 Android 和 iOS SDK 以捕获原生崩溃,Flutter 框架错误和未捕获的异步错误会自动上报。
flutter pub add blipit_flutterimport 'package:blipit_flutter/blipit_flutter.dart';
Future<void> main() async {
await Blipit.init(
key: '<public key>',
project: <project id>,
environment: 'production',
release: 'myapp@1.4.2',
appRunner: () => runApp(const MyApp()),
);
}4iOS 和 macOS(Swift Package)
在 Xcode 中选择 File、Add Package Dependencies,输入仓库 URL;或者把它加入 Package.swift,并将 BlipitSwift 添加到你的 target。使用 CocoaPods 时,请用 BlipitSwift pod。然后在启动时调用一次 start。密钥或项目 id 为空时,start 会打印一条警告并返回 false,而不会让应用崩溃。
.package(url: "https://github.com/blipit-io/blipit-swift", from: "0.8.0")pod "BlipitSwift", "~> 0.8.0"import BlipitSwift
Blipit.start(key: "<public key>", project: "<project id>", environment: "production", release: "myapp@1.4.2")5Android
在 settings.gradle.kts 的 repositories 中添加 JitPack,在 app 模块中添加依赖,并在 Application.onCreate 中调用 init。
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
maven("https://jitpack.io")
}
}implementation("com.github.blipit-io:blipit-android:v0.7.5")import io.blipit.android.Blipit
class App : Application() {
override fun onCreate() {
super.onCreate()
Blipit.init(this) {
key = "<public key>"
project = "<project id>"
environment = "production"
release = "myapp@1.4.2"
}
}
}6应用中的密钥放在哪里
应用会把公钥和项目 id 打包在应用内,这没有问题:公钥只能发送事件。切勿把私密密钥放进应用。请在构建时传入它们,避免进入你的代码仓库。
flutter run --dart-define=BLIPIT_KEY=blipit_pk_your_public_key --dart-define=BLIPIT_PROJECT=12const key = String.fromEnvironment('BLIPIT_KEY');
const project = int.fromEnvironment('BLIPIT_PROJECT');EXPO_PUBLIC_BLIPIT_KEY=blipit_pk_your_public_key
EXPO_PUBLIC_BLIPIT_PROJECT=12buildConfigField("String", "BLIPIT_KEY", "\"${project.findProperty("blipitKey")}\"")BLIPIT_KEY = blipit_pk_your_public_key7应用中的错误报告
从你自己的菜单项调用 showReport,或开启悬浮的“报告问题”按钮。报告工具会先询问如何展示问题:截屏、录屏(iOS)或只描述。截图以全屏打开,工具栏位于图片上方和下方,从不遮挡图片;双指捏合或双击即可缩放,标出问题,再填写标题和发生了什么后发送。报告会连同设备信息出现在“错误报告”中。React Native 截图需要 react-native-view-shot。
import * as Blipit from "@blipit/react-native";
export default function Root() {
return (
<Blipit.BlipitReporter showButton>
<App />
</Blipit.BlipitReporter>
);
}
Blipit.showReport();appRunner: () => runApp(const BlipitReporter(showButton: true, child: MyApp())),
Blipit.showReport();Blipit.showReportButton()
Blipit.showReport()Blipit.showReportButton()
Blipit.showReport()8在出问题的屏幕上报告
放在“个人资料”等菜单里的“报告问题”截到的是菜单,而不是问题。请开启从当前屏幕直接发起的方式;它们默认都关闭,也不会请求任何权限。shakeToReport 在摇动手机时打开报告页面。screenshotToReport 在普通截屏后询问“要用此屏幕报告问题吗?”,并附上 Blipit 自己的截图(iOS 以及 Android 14 及以上)。twoFingerReport 在双指按住约一秒后打开,不会妨碍应用自身的触摸。reportAfterCrash 在崩溃后的第一次启动时询问用户当时在做什么,并把报告关联到该崩溃。默认开启的 screenPicker 让从菜单打开报告的人选择问题出现在最近的哪个屏幕:快照只保存在设备内存中,只上传选中的那一张。Jetpack Compose 和 SwiftUI 应用用 setScreen 为屏幕命名。
Blipit.init(this) {
key = "<public key>"
project = "<project id>"
shakeToReport = true
screenshotToReport = true
twoFingerReport = true
reportAfterCrash = true
}
navController.addOnDestinationChangedListener { _, destination, _ ->
Blipit.setScreen(destination.route ?: "screen")
}Blipit.start(key: "<public key>", project: "<project id>") { options in
options.shakeToReport = true
options.screenshotToReport = true
options.twoFingerReport = true
options.reportAfterCrash = true
}
CartView().onAppear { Blipit.setScreen("Cart") }Blipit.init({
key: "<public key>",
project: <project id>,
shakeToReport: true,
screenshotToReport: true,
twoFingerReport: true,
reportAfterCrash: true,
});
<NavigationContainer ref={navigation} onReady={() => Blipit.trackNavigation(navigation)}>await Blipit.init(
key: '<public key>',
project: <project id>,
shakeToReport: true,
screenshotToReport: true,
twoFingerReport: true,
reportAfterCrash: true,
appRunner: () => runApp(BlipitReporter(child: MaterialApp(navigatorObservers: [BlipitNavigatorObserver()], home: const Home()))),
);10发现卡住的应用
有些故障从不崩溃:启动画面一直转圈,或登录一直没有返回。打开 waitForReady,并在第一个可用界面出现时调用 reportReady。用 startFlow 和 endFlow 包住登录等流程,并用 flowStep 标记步骤。如果某个流程没有按时完成,Blipit 会创建一个“卡住”问题,附上最后一步和之前的轨迹。只计算显示在屏幕上的时间,时间上限由 Blipit 设定。名称会按原样发送,请使用固定名称,绝不要使用邮箱或其他用户数据。
Blipit.init(this) {
key = "<public key>"
project = "<project id>"
waitForReady = true
}
Blipit.reportReady()
Blipit.startFlow("sign-in")
Blipit.flowStep("sign-in", "google-picker")
Blipit.endFlow("sign-in")Blipit.start(key: "<public key>", project: "<project id>", waitForReady: true)
Blipit.reportReady()
Blipit.startFlow("sign-in")
Blipit.flowStep("sign-in", "apple-sheet")
Blipit.endFlow("sign-in")Blipit.init({ key: "<public key>", project: <project id>, waitForReady: true });
Blipit.reportReady();
Blipit.startFlow("sign-in");
Blipit.flowStep("sign-in", "google-picker");
Blipit.endFlow("sign-in");await Blipit.init(key: '<public key>', project: <project id>, waitForReady: true, appRunner: () => runApp(const MyApp()));
Blipit.reportReady();
Blipit.startFlow('sign-in');
Blipit.flowStep('sign-in', 'google-picker');
Blipit.endFlow('sign-in');11验证是否生效
打开 app.blipit.io 中的“问题”。首个事件几秒钟内就会出现,并归组为一个问题,负责人会收到邮件。
Blipit.captureMessage("Hello from React Native");await Blipit.captureMessage('Hello from Flutter');Blipit.captureMessage("Hello from iOS")Blipit.captureMessage("Hello from Android")须知
- 所有平台都支持手动捕获:captureException、captureMessage、setUser、setTag、addBreadcrumb,以及用于登录尝试的 captureSecurity。
- Expo:运行 npx expo prebuild 或使用 development build。Expo Go 不含自定义原生代码,因此在其中 JavaScript 错误仍会上报,但原生崩溃不会。
- 从 0.4 升级 React Native:卸载 0.4 随附安装的第三方监控包,并删除其 Expo 配置插件;dsn() 和 withIdentity() 已移除。从 0.3 升级 Flutter:同样从 pubspec.yaml 中删除该包;级别和用户类型现在是 BlipitLevel 和 BlipitUser,capture 调用以 String? 形式返回事件 id,Blipit.dsn、Blipit.configure 以及 init 的 options: 回调已移除。两者都接受 tracesSampleRate,但此版本不发送性能 trace。
- 将 Android 升级到 v0.5.0、iOS 升级到 0.5.0:大多数应用只需提升版本号。capture 调用以字符串形式返回事件 id,级别类型是 Blipit 自己的 Level,Blipit.dsn 已移除。Android 上移除了 configure 和 apply,回放遮盖标签现在是 blipit-mask。iOS 上 Options 是 Blipit 自己的类,beforeSend 以字典形式处理事件。
- 报告方式的应用商店审核:没有新的权限请求。iOS 使用 UIKit 的摇动事件(不是 CoreMotion)和截屏通知,因此隐私清单无需新增条目。在 Android 14 及以上,SDK 声明 DETECT_SCREEN_CAPTURE,这是安装时授予的普通权限;对于 Google Play 的数据安全表单,不会收集任何新数据,因为 Blipit 只知道发生了截屏,从不读取截图或相册。较旧的 Android 版本不提供截屏报告。Huawei AppGallery 版本行为相同,不使用 Google Play 服务。
- 用 npm ls @blipit/react-native(或 pnpm list @blipit/react-native)查看已安装的版本。pnpm 11 会在新版本发布一天后才安装它(minimum-release-age),所以在发布当天 pnpm add 会悄悄安装上一个版本;要立即获得新版本,运行 pnpm add @blipit/react-native@<version> --config.minimum-release-age=0。
- 让 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 密钥”下。

