flutter_tencent_bugly #

Language: 中文 | English

A lightweight Flutter plugin wrapping Tencent Bugly, providing Dart exception capture, native crash / ANR / block monitoring and operational data analysis, with the full native API surface exposed through a simple static Dart API and data reported to the Bugly console.

It covers both native and Dart-side errors: Bugly's native crash / ANR / block monitoring is initialized per platform, while runGuarded captures Flutter framework exceptions (FlutterError.onError) and uncaught asynchronous exceptions (runZonedGuarded) from the Dart side and reports them to Bugly — no extra wiring required.

Getting started #

Version constraints #

  sdk: ^3.11.0
  flutter: ">=3.41.0"

Step 1: Create products and get your App IDs #

Sign in to the Bugly console and create a product for each platform (one for Android, one for iOS — each gets its own App ID).
Open the product you just created, go to 更多 → 产品设置 in the upper right corner, and record the App ID for the initialization below.

This plugin wraps the open-source Bugly (the crashreport SDK): only an App ID is needed — no AppKey, and no traffic package to purchase. Those belong to Bugly Pro (bugly_pro_flutter), a different, paid offering; don't confuse the two.

Step 2: Add the dependency #

dependencies:
  flutter_tencent_bugly: ^1.0.0

import 'package:flutter_tencent_bugly/flutter_tencent_bugly.dart';

Step 3: Initialize and guard the app (recommended) #

In main(), wrap the entire app with FlutterTencentBugly.runGuarded so that Flutter framework exceptions and unhandled async exceptions are captured and reported automatically, then initialize Bugly inside it. See example/lib/main.dart for the complete example.

Step 4: Verify the integration #

Trigger a test exception — report one with FlutterTencentBugly.postException, or simply throw a Dart exception (captured automatically by runGuarded) — then check the 错误分析 in the Bugly console a moment later to confirm the report arrived.

Usage #

User and device metadata #

Attach identity and device information to subsequent crash reports:

await FlutterTencentBugly.setUserId('user_001');
await FlutterTencentBugly.setUserTag(9527);
await FlutterTencentBugly.setDeviceID('device-id');
await FlutterTencentBugly.setVersion('1.0.0');

// Android-only; these are no-ops on other platforms.
await FlutterTencentBugly.setDeviceModel('Pixel 8');
await FlutterTencentBugly.setChannel('play_store'); // on iOS, set the channel in init config instead
await FlutterTencentBugly.setPackageName('com.example.demo');

Custom key-value data #

Custom data is attached to crash reports when a crash occurs:

await FlutterTencentBugly.putUserData(key: 'level', value: 'vip');

At most 50 key-value pairs (extras are dropped). Keys are truncated to 50 bytes and values to 200 bytes.

Report exceptions manually #

Caught business exceptions can be reported explicitly:

try {
  throw const FormatException('simulated business exception');
} catch (e, stack) {
  await FlutterTencentBugly.postException(
    message: e,
    detail: stack,
    type: e.runtimeType,
    extra: <String, dynamic>{'page': 'demo', 'action': 'postCaughtException'},
  );
}

Custom logs #

Logs printed through the plugin are uploaded to Bugly together with crash reports:

await FlutterTencentBugly.log(
  tag: 'BuglyDemo',
  message: 'an INFO level log',
  level: LogLevel.INFO,
);

Android: set isLogUpload to true in FlutterTencentBuglyAndroidConfig for logs to be uploaded to the Bugly server.

iOS: controlled by reportLogLevel in FlutterTencentBuglyIOSConfig — the default BuglyLogLevelSilent (0) disables log recording; set e.g. BuglyLogLevelWarn (2) to upload Warn / Error logs on crash.

Parameters #

Methods #

Name	Signature	Description
`init`	`({FlutterTencentBuglyConfig? config, FlutterTencentBuglyAndroidConfig? android, FlutterTencentBuglyIOSConfig? ios}) → Future<bool>`	Initializes Bugly. A platform is only initialized when its config is passed.
`setUserId`	`(String value)`	Sets the user ID.
`setUserTag`	`(int value)`	Sets the user tag.
`setDeviceID`	`(String value)`	Sets the device ID.
`setDeviceModel`	`(String value)`	Sets the device model. Android only.
`setChannel`	`(String value)`	Sets the channel. Android only — on iOS, configure it via `FlutterTencentBuglyConfig.channel` at init.
`setVersion`	`(String value)`	Sets the app version.
`setPackageName`	`(String value)`	Sets the package name. Android only.
`putUserData`	`({required String key, required String value})`	Sets custom key-value data, uploaded with crash reports.
`postException`	`({required dynamic message, required dynamic detail, dynamic type, Map<String, dynamic>? extra})`	Reports a custom exception.
`log`	`({required String tag, required String message, LogLevel level = LogLevel.INFO})`	Prints a Bugly log, uploaded with crash reports.
`runGuarded`	`<T>(ValueGetter<T> body, {FlutterExceptionHandler? onException, String? filterPattern, bool reportInDebugMode = false})`	Equivalent to `runZonedGuarded`: runs `body` while capturing and reporting framework and async exceptions. Pure Dart; never crosses the method channel.