tencent cloud

腾讯云可观测平台

文档腾讯云可观测平台终端性能监控 Pro接入指南Flutter SDK 接入指引SDK 初始化

SDK 初始化

下载
聚焦模式
字号
最后更新时间： 2026-05-25 18:01:56
本文将为您介绍如何初始化终端性能监控 Pro Bugly Flutter SDK。

初始化示例代码

在项目 main.dart 文件的 main 函数中添加初始化代码。
import 'package:bugly_pro_flutter/bugly.dart';

void main() {
  Bugly.setSdkRegion(SdkRegion.BUGLY_CLOUD);  // 设置上报域名
  BuglyOptions options = BuglyOptions(appId: '', appKey: '', bundleId: '');
  options.monitorTypes = [
    MonitorType.launchMetric,
    MonitorType.looperMetric,
    MonitorType.looperStack,
    MonitorType.exception
  ];
  options.userId = 'pro_tester';

  Bugly.init(options, appRunner: (){
    runApp(const MyApp());
  },
  beforeInitRunner: (options){
    options.appId = 'afxxxxb01';          // 注册产品的appid
    options.appKey = 'aef434ba-xxxx-xxxx-xxxx-030b10aae88b'; // 注册产品的appkey
    options.bundleId = 'com.xxx.bundleid';
  });
}
注意：
在初始化代码的第一行，需要调用 Bugly.setSdkRegion(SdkRegion.BUGLY_CLOUD)，设置上报域名为腾讯云。
建议在用户授权《终端性能监控 Pro SDK 个人信息保护规则》 后再初始化终端性能监控 Pro SDK。

集成 FAQ

解决 Flutter 启动时的 "Zone mismatch" 错误。

错误现象​：启动时出现 Dart 错误 "Zone mismatch"。
​原因分析​：该错误通常是因为 WidgetsFlutterBinding.ensureInitialized() 和 runApp() 方法在不同的 Zone 中执行导致的。
​解决方案​：确保这两个方法在同一个 Zone 中执行。
以下是正确的代码组织方式：
import 'package:bugly_pro_flutter/bugly.dart';

void main() {
  BuglyOptions options = BuglyOptions(appId: '', appKey: '', bundleId: '');
  options.monitorTypes = [
    MonitorType.launchMetric,
    MonitorType.looperMetric,
    MonitorType.looperStack,
    MonitorType.exception
  ];
  options.userId = 'pro_tester';

  WidgetsFlutterBinding.ensureInitialized();
  final zone = Zone.current;    // ！！！！！！获取 zone！！！！！

  Bugly.init(options, appRunner: (){
    // runApp(const MyApp());
    zone.run(() => runApp(const MyApp())); // ！！！！！！这里改成在 zone 中运行 runApp！！！！！！！
  },
  beforeInitRunner: (options){
    options.appId = 'afxxxxb01';          // 注册产品的 appid
    options.appKey = 'aef434ba-xxxx-xxxx-xxxx-030b10aae88b'; // 注册产品的 appkey
    options.bundleId = 'com.xxx.bundleid';
  });
}


说明：
先执行 WidgetsFlutterBinding.ensureInitialized()，并保存执行该接口的 Zone。
在 Bugly.Init 中使用前面保存的 Zone 执行 runApp()，可以保证 WidgetsFlutterBinding.ensureInitialized() 和 runApp() 在同一个 Zone 中执行。
如果有异步操作，需使用 async/await 正确处理。

解决 Android 平台编译问题

接入后如果启动 crash 报 Abort message: 'JNI DETECTED ERROR IN APPLICATION: java_class == null in call to GetStaticMethodID，且项目开启了代码混淆，需要将 Bugly 相关的类加入 keep 白名单。
-keep class java.com.tencent.bugly.**{*;}

解决 iOS 平台的编译问题

当您在 iOS 原生工程（宿主工程）中集成 Flutter APM SDK 时，如果遇到 ​C++ 链接错误​，例如 Undefined symbols for architecture arm64，提示缺少 C++ 符号，原因如下：
​Bugly Flutter SDK 的部分逻辑是采用 C++ 实现的，因此需要宿主工程支持 C++ 运行时库。
​iOS 工程的默认配置不包含 C++ 库，​Xcode 新建的工程默认不会自动链接 C++ 标准库（libc++），需要手动添加。
解决方案步骤​如下：
在 Xcode 中明确添加 libc++.tbd（或 libc++.dylib）依赖：
1. 打开 Xcode 工程​。
双击您项目的 ios/Runner.xcworkspace（Flutter 工程）或原生工程文件。
2. ​导航到构建配置​，在项目导航器中执行如下操作：
2.1 选择您的 ​Target​（通常是 Runner）。
2.2 切换到 ​​"Build Phases"​​ 标签页。
3. ​添加 C++ 库​。
3.1 找到 ​​"Link Binary With Libraries"​​ 部分。
3.2 单击 ​​+​​ 按钮，然后搜索 libc++。
3.3 选择 ​libc++.tbd​（推荐）或 libc++.dylib（两者功能相同，.tbd 是较新的轻量版）。
4. ​验证配置​。在 ​​"Build Settings"​​ 标签页中执行如下操作：
4.1 搜索 Other Linker Flags。
4.2 确保包含 -lc++（如果手动添加过，可移除以避免重复）。
5. ​重新编译​。
执行 Clean Build（Cmd + Shift + K）后重新运行。

解决依赖库冲突的问题

如果在接入 Flutter SDK 后运行 flutter pub get 报依赖库冲突，可以先尝试将冲突的库版本改成业务使用的版本。例如业务依赖的 uuid 库版本是^4.4.2，但是 Flutter SDK 依赖的是^3.0.6，执行 flutter pub get 就会报错，可以在 pubspec.yaml 中添加如下内容，一般就能解决冲突问题。如果还是无法解决，请 提交工单 联系我们。
# 将 uuid 依赖强制改写成4.4.2版本
dependency_overrides:
  uuid: ^4.4.2



上一篇: SDK 集成下一篇: 数据上报验证

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈