> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/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.2.1 |
| 目标平台 | **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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.