> ## Documentation Index
> Fetch the complete documentation index at: https://test-8ad8522e-feat-ai-sre.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Flutter SDK 兼容性

> 了解 Flutter RUM SDK 支持的平台、Flutter 版本、伴生包和当前限制

本文说明 Flutter SDK 的支持范围和当前限制，帮助你在接入前判断工程是否满足要求。

## 支持范围

| 项目             | 支持情况                                         |
| -------------- | -------------------------------------------- |
| SDK 版本         | `flashcat_flutter_plugin` 0.1.3              |
| 目标平台           | **iOS 和 Android**（不支持 Flutter Web / Desktop） |
| Flutter / Dart | Flutter ≥ 3.27.0，Dart ≥ 3.6.0                |
| iOS            | 部署目标 ≥ 12.0                                  |
| Android        | `minSdkVersion` ≥ 23                         |
| RUM 数据源        | 事件固定写入 `source: "flutter"`                   |
| 实现方式           | 基于原生 iOS / Android SDK 封装的 Flutter plugin    |
| 数据上报           | `POST /api/v2/rum`                           |

## 包和能力

| 包                  | pub 名                           | 说明                                                            |
| ------------------ | ------------------------------- | ------------------------------------------------------------- |
| RUM / Core / Crash | `flashcat_flutter_plugin`       | 初始化、配置、RUM（view / action / resource / error / session）、原生崩溃采集 |
| HTTP 追踪            | `flashcat_tracking_http_client` | 自动把 `dart:io` / `http` 请求记录为 resource 并注入追踪头                  |
| WebView 追踪         | `flashcat_webview_tracking`     | 关联 WebView 内的 RUM 数据                                          |

<Note>
  Dart 类名以 `Datadog*` 开头，站点枚举为 `FlashcatSite`。面向客户的生产环境请使用默认的 `.cn`；私有化部署请配置完整的 `customEndpoint`。文档示例中的 `DatadogSdk`、`DatadogConfiguration`、`DatadogRumConfiguration`、`DatadogNavigationObserver` 等均为实际导出的类名。
</Note>

## 支持的自动采集

| 能力          | 支持情况     | 说明                                                                                 |
| ----------- | -------- | ---------------------------------------------------------------------------------- |
| 自动 view     | 支持       | 需为 `MaterialApp` 添加 `DatadogNavigationObserver`                                    |
| 自动 action   | 支持       | 需用 `RumUserActionDetector` 包裹子树；`trackFrustrations` 默认开启                           |
| 自动 resource | 支持（需伴生包） | 通过 `flashcat_tracking_http_client` 的 `enableHttpTracking()`                        |
| 未处理异常       | 支持       | 使用 `DatadogSdk.runApp` 时自动接管 `FlutterError.onError` / `PlatformDispatcher.onError` |
| 原生崩溃        | 支持       | 需 `nativeCrashReportEnabled: true`                                                 |
| 分布式追踪       | 支持       | 对 `firstPartyHosts` 命中的域名注入 W3C `traceparent`                                      |
| 原生移动端性能指标   | 支持       | 默认采集启动耗时（TTID）、刷新率与内存                                                              |
| 卡顿检测        | 支持       | Android 支持 ANR；iOS 设置 `appHangThreshold` 后支持 App Hang                              |

## 当前限制

| 限制               | 说明                                                                                   |
| ---------------- | ------------------------------------------------------------------------------------ |
| 平台范围             | 仅 iOS / Android；Flutter Web 与 Desktop 不支持                                            |
| Logs             | 不支持日志上报（`DatadogLoggingConfiguration` 为空操作）                                          |
| Session Replay   | 不支持                                                                                  |
| dio / gql / grpc | 对应拦截包暂不支持                                                                            |
| Flutter 渲染耗时     | `reportFlutterPerformance` 默认关闭；仅控制 Flutter build / raster timing，不影响默认采集的原生移动端性能指标  |
| 最低版本             | 请使用 `flashcat_flutter_plugin` 0.1.3 或更高版本；更低版本 `flutter build apk --release` 会失败于 R8 |

## 符号解析兼容性

Flutter 崩溃栈可能同时包含 Dart 帧与原生（iOS / Android）帧。要把栈帧还原到源码位置，需要上传对应符号文件：

| 栈帧类型           | 所需上传文件                                                 |
| -------------- | ------------------------------------------------------ |
| Dart（Android）  | Flutter symbols（`flutter build --split-debug-info` 产物） |
| Dart（iOS）      | 暂不支持，见下方说明                                             |
| iOS Native     | dSYM                                                   |
| Android Native | mapping 文件                                             |

<Warning>
  **iOS 的 Dart 堆栈暂不支持符号化。** Flutter 为 Apple 平台生成的符号文件是 Mach-O 格式，平台当前只能解析 Android 侧的 ELF 格式，因此 iOS 的 `.symbols` 上传会被拒绝。iOS 原生崩溃不受影响，上传 dSYM 即可符号化。

  如果你的应用同时发布 iOS 和 Android，`--obfuscate` 仍可开启：Android 的 Dart 堆栈会正常还原，iOS 的 Dart 堆栈则保持混淆状态。若 iOS 的可读堆栈更重要，则该端构建时不要开启 `--obfuscate`。
</Warning>

<Tip>
  符号文件通过 FlashCat CLI 上传。符号与崩溃事件按构建产物的 build ID 关联，因此每次改动代码后都需要重新上传该版本的符号文件。
</Tip>