tencent cloud

Tencent Cloud Observability Platform

DocumentationTencent Cloud Observability PlatformTerminal Performance Monitoring ProIntegration GuideFlutter SDK Integration GuideSDK Initialization

SDK Initialization

Download
Focus Mode
Font Size
Last updated: 2026-05-25 18:01:56
This article describes how to initialize the Terminal Performance Monitoring Pro (RUM Pro) Bugly Flutter SDK.

Sample Code

Add the initialization code to the main function in your project's main.dart file:
import 'package:bugly_pro_flutter/bugly.dart';

void main() {
  Bugly.setSdkRegion(SdkRegion.BUGLY_CLOUD);  // Sets the reporting domain.
  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 of the registered product
    options.appKey = 'aef434ba-xxxx-xxxx-xxxx-030b10aae88b'; // appkey of the registered product
    options.bundleId = 'com.xxx.bundleid';
  });
}
Note:
The first line of initialization code must call Bugly.setSdkRegion(SdkRegion.BUGLY_CLOUD) to set the reporting domain to Tencent Cloud.
It is recommended to initialize the RUM Pro SDK only after obtaining user consent to the RUM Pro SDK Personal Information Protection Rules.

Integration FAQs

Resolving "Zone mismatch" Error During Flutter Startup

Error description: A Dart error "Zone mismatch" occurs during startup.
Cause analysis: This error is typically caused by WidgetsFlutterBinding.ensureInitialized() and runApp() being executed in different zones.
Solution: Ensure both methods are executed in the same zone.
Correct code organization:
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;    // !!!!!! Capture the zone!!!!!!

  Bugly.init(options, appRunner: (){
    // runApp(const MyApp());
    zone.run(() => runApp(const MyApp())); // !!!!!!Change to run runApp within the zone here!!!!!!
  },
  beforeInitRunner: (options){
    options.appId = 'afxxxxb01';          // appid of the registered product
    options.appKey = 'aef434ba-xxxx-xxxx-xxxx-030b10aae88b'; // appkey of the registered product
    options.bundleId = 'com.xxx.bundleid';
  });
}


Note:
Execute WidgetsFlutterBinding.ensureInitialized() first and save the Zone where this API is executed.
Use the saved zone to execute runApp() in Bugly.Init to ensure WidgetsFlutterBinding.ensureInitialized() and runApp() are executed in the same zone.
For asynchronous operations, use async/await properly.

Solving Android Platform Compilation Issues

After integration, if the app crashes with the error message Abort message: 'JNI DETECTED ERROR IN APPLICATION: java_class == null in call to GetStaticMethodID, and code obfuscation is enabled in the project, you need to add Bugly-related classes to the keep allowlist.
-keep class java.com.tencent.bugly.**{*;}

Solving iOS Platform Compilation Issues

When integrating the Flutter APM SDK into an iOS native project (host project), you may encounter C++ linking errors such as Undefined symbols for architecture arm64. This error indicates missing C++ symbols. The causes are as follows:
Parts of the Bugly Flutter SDK are implemented in C++, so the host project must support C++ runtime libraries.
By default, iOS projects created with Xcode do not automatically link against the C++ standard library (libc++), so you need to add it manually.
Solution steps:
In Xcode, explicitly add the libc++.tbd (or libc++.dylib) dependency:
1. Open the Xcode project.
Double-click your project's ios/Runner.xcworkspace (for Flutter project) or the native project file.
2. ​Navigate to the build configuration. In the project navigator, perform the following operations:
2.1 Select your target (usually Runner).
2.2 Switch to the "Build Phases" Tab.
3. ​Add the C++ library.
3.1 Locate the "Link Binary With Libraries" section.
3.2 Click the "+" button, then search for libc++.
3.3 Select libc++.tbd (recommended) or libc++.dylib (both have the same functionality; .tbd is the newer lightweight version).
4. Verify the configuration. Perform the following operations in the "Build Settings" Tab:
4.1 Search for Other Linker Flags.
4.2 Ensure that -lc++ is included (if manually added earlier, you can remove it to avoid duplication).
5. Recompile the project.
Perform Clean Build (Cmd + Shift + K) and then rerun.

Resolving Dependency Library Conflicts

If running flutter pub get after integrating the Flutter SDK reports dependency conflicts, try adjusting the conflicting library version to match your project's requirements. For example, if the business depends on uuid library 4.4.2 but the Flutter SDK depends on 3.0.6, running flutter pub get will result in an error. To resolve this, add the following content in pubspec.yaml. If the issue persists, please submit a ticket to contact us.
# Force overwrite the uuid dependency to version 4.4.2.
dependency_overrides:
  uuid: ^4.4.2



Previous Topic: SDK IntegrationNext Topic: Data Reporting Verification

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback