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、卡死和未捕获的异常会自动上报,先写入磁盘,在下次启动时发送;离线队列会保留报告,直到网络恢复。原生崩溃请保留调试符号,因为目前还不读取符号文件。

复制给 AI 助手的提示词粘贴到 Claude Code、Cursor 或任何 AI 编程助手中。它包含步骤和代码。在 app.blipit.io 的“API 密钥”页面,同一提示词已填好你的密钥。
视频:在任何技术栈中安装 Blipit,从 1:56 开始

1获取密钥

登录 app.blipit.io,打开侧边栏中的“API 密钥”,然后选择你的项目。每个项目有两个密钥。公钥以 blipit_pk_ 开头:它用于浏览器和应用代码,只能发送事件,任何人看到都没关系。私密密钥以 blipit_sk_ 开头:它留在你的服务器或 Odoo 中,切勿放进浏览器,因为它还可以读取和更改问题。私密密钥只在创建后显示一次,请当时就复制;如果丢失,请点击“创建新的密钥”,旧密钥会立即失效。部分 SDK 还需要项目 id,它显示在同一页面上。

app.blipit.io 中的 API 密钥:公钥(blipit_pk_)用于浏览器代码,私密密钥(blipit_sk_)用于服务器和 Odoo。
app.blipit.io 中的 API 密钥:公钥(blipit_pk_)用于浏览器代码,私密密钥(blipit_sk_)用于服务器和 Odoo。
新的私密密钥只显示一次。请立即复制:它以哈希形式存储,无法再次显示。
新的私密密钥只显示一次。请立即复制:它以哈希形式存储,无法再次显示。

2React Native

该包会链接一个小型原生模块,用于启动 Blipit 自己的 Android 和 iOS SDK 以捕获原生崩溃;其 Gradle 文件会自动添加 JitPack 仓库。包装根组件,渲染错误也会被上报。

sh
npm install @blipit/react-native
npx pod-install
tsx
import * 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 框架错误和未捕获的异步错误会自动上报。

sh
flutter pub add blipit_flutter
main.dart
import '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.swift
.package(url: "https://github.com/blipit-io/blipit-swift", from: "0.8.0")
Podfile
pod "BlipitSwift", "~> 0.8.0"
swift
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。

settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven("https://jitpack.io")
    }
}
build.gradle.kts (app)
implementation("com.github.blipit-io:blipit-android:v0.7.5")
kotlin
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
flutter run --dart-define=BLIPIT_KEY=blipit_pk_your_public_key --dart-define=BLIPIT_PROJECT=12
main.dart
const key = String.fromEnvironment('BLIPIT_KEY');
const project = int.fromEnvironment('BLIPIT_PROJECT');
Expo(.env)
EXPO_PUBLIC_BLIPIT_KEY=blipit_pk_your_public_key
EXPO_PUBLIC_BLIPIT_PROJECT=12
Android build.gradle.kts
buildConfigField("String", "BLIPIT_KEY", "\"${project.findProperty("blipitKey")}\"")
iOS xcconfig
BLIPIT_KEY = blipit_pk_your_public_key

7应用中的错误报告

从你自己的菜单项调用 showReport,或开启悬浮的“报告问题”按钮。报告工具会先询问如何展示问题:截屏、录屏(iOS)或只描述。截图以全屏打开,工具栏位于图片上方和下方,从不遮挡图片;双指捏合或双击即可缩放,标出问题,再填写标题和发生了什么后发送。报告会连同设备信息出现在“错误报告”中。React Native 截图需要 react-native-view-shot。

React Native
import * as Blipit from "@blipit/react-native";

export default function Root() {
  return (
    <Blipit.BlipitReporter showButton>
      <App />
    </Blipit.BlipitReporter>
  );
}

Blipit.showReport();
Flutter
appRunner: () => runApp(const BlipitReporter(showButton: true, child: MyApp())),

Blipit.showReport();
iOS
Blipit.showReportButton()

Blipit.showReport()
Android
Blipit.showReportButton()

Blipit.showReport()

8在出问题的屏幕上报告

放在“个人资料”等菜单里的“报告问题”截到的是菜单,而不是问题。请开启从当前屏幕直接发起的方式;它们默认都关闭,也不会请求任何权限。shakeToReport 在摇动手机时打开报告页面。screenshotToReport 在普通截屏后询问“要用此屏幕报告问题吗?”,并附上 Blipit 自己的截图(iOS 以及 Android 14 及以上)。twoFingerReport 在双指按住约一秒后打开,不会妨碍应用自身的触摸。reportAfterCrash 在崩溃后的第一次启动时询问用户当时在做什么,并把报告关联到该崩溃。默认开启的 screenPicker 让从菜单打开报告的人选择问题出现在最近的哪个屏幕:快照只保存在设备内存中,只上传选中的那一张。Jetpack Compose 和 SwiftUI 应用用 setScreen 为屏幕命名。

Android
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")
}
iOS
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") }
React Native
Blipit.init({
  key: "<public key>",
  project: <project id>,
  shakeToReport: true,
  screenshotToReport: true,
  twoFingerReport: true,
  reportAfterCrash: true,
});

<NavigationContainer ref={navigation} onReady={() => Blipit.trackNavigation(navigation)}>
Flutter
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()))),
);

9仅对测试人员显示的悬浮按钮

在 app.blipit.io 打开项目,在问题报告按钮设置中把“手机应用中的悬浮按钮”设为“所有人”或“仅测试人员”,每位测试人员填写一个用户 ID 或邮箱。应用会发送通过 setUser 设置的用户,Blipit 只回答是或否,因此测试人员名单永远不会打包进应用。调用 showReportButton(React Native 和 Flutter 中为 showButton)仍会对所有人显示按钮。

Android
Blipit.setUser(id = user.id, email = user.email)
iOS
Blipit.setUser(id: user.id, email: user.email)
React Native
Blipit.setUser({ id: user.id, email: user.email });
Flutter
Blipit.setUser(BlipitUser(id: user.id, email: user.email));

10发现卡住的应用

有些故障从不崩溃:启动画面一直转圈,或登录一直没有返回。打开 waitForReady,并在第一个可用界面出现时调用 reportReady。用 startFlow 和 endFlow 包住登录等流程,并用 flowStep 标记步骤。如果某个流程没有按时完成,Blipit 会创建一个“卡住”问题,附上最后一步和之前的轨迹。只计算显示在屏幕上的时间,时间上限由 Blipit 设定。名称会按原样发送,请使用固定名称,绝不要使用邮箱或其他用户数据。

Android
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")
iOS
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")
React Native
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");
Flutter
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 中的“问题”。首个事件几秒钟内就会出现,并归组为一个问题,负责人会收到邮件。

React Native
Blipit.captureMessage("Hello from React Native");
Flutter
await Blipit.captureMessage('Hello from Flutter');
iOS
Blipit.captureMessage("Hello from iOS")
Android
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 密钥”下。