> ## 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.1.0              |
| 目标平台           | **iOS 和 Android**（不支持 Flutter Web / Desktop） |
| Flutter / Dart | Flutter ≥ 3.0，Dart ≥ 3.0                     |
| iOS            | 部署目标 ≥ 12.0                                  |
| Android        | `minSdkVersion` ≥ 21                         |
| 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 追踪            | `datadog_tracking_http_client` | 自动把 `dart:io` / `http` 请求记录为 resource 并注入追踪头（需 `dependency_overrides`，非 v1 核心） |
| WebView 追踪         | `flashcat_webview_tracking`    | 关联 WebView 内的 RUM 数据                                                           |

<Note>
  Dart 类名仍沿用上游 `Datadog*` 命名，仅站点枚举 `FlashcatSite`（`.cn` 默认 / `.staging`）与包名做了品牌化。文档示例中的 `DatadogSdk`、`DatadogConfiguration`、`DatadogRumConfiguration`、`DatadogNavigationObserver` 等均为实际导出的类名。
</Note>

## 支持的自动采集

| 能力          | 支持情况     | 说明                                                                                 |
| ----------- | -------- | ---------------------------------------------------------------------------------- |
| 自动 view     | 支持       | 需为 `MaterialApp` 添加 `DatadogNavigationObserver`                                    |
| 自动 action   | 支持       | 需用 `RumUserActionDetector` 包裹子树；`trackFrustrations` 默认开启                           |
| 自动 resource | 支持（需伴生包） | 通过 `datadog_tracking_http_client` 的 `enableHttpTracking()`                         |
| 未处理异常       | 支持       | 使用 `DatadogSdk.runApp` 时自动接管 `FlutterError.onError` / `PlatformDispatcher.onError` |
| 原生崩溃        | 支持       | 需 `nativeCrashReportEnabled: true`                                                 |
| 分布式追踪       | 支持       | 对 `firstPartyHosts` 命中的域名注入 W3C `traceparent`                                      |

## 当前限制

| 限制               | 说明                                                                                                                                    |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| 平台范围             | 仅 iOS / Android；Flutter Web 与 Desktop 不支持                                                                                             |
| Logs             | v1 不支持日志上报（`DatadogLoggingConfiguration` 为空操作）                                                                                        |
| Session Replay   | v1 不支持（`datadog_session_replay` 为 preview，不在核心范围）                                                                                     |
| 伴生包命名            | `datadog_tracking_http_client` / `datadog_session_replay` 仍以 `datadog_flutter_plugin: ^3.0.0` 声明依赖，接入本 fork 时需 `dependency_overrides` |
| dio / gql / grpc | 对应拦截包 v1 暂不适配本 fork                                                                                                                   |
| 页面性能指标           | `reportFlutterPerformance` 默认关闭；控制台性能页当前对 Flutter 隐藏，避免展示无数据的零值                                                                       |
| pub.dev 发布       | 正式发布确认中，当前推荐使用 git 依赖                                                                                                                 |

## 符号解析兼容性

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

| 栈帧类型           | 所需上传文件                                                 |
| -------------- | ------------------------------------------------------ |
| Dart           | Flutter symbols（`flutter build --split-debug-info` 产物） |
| iOS Native     | dSYM                                                   |
| Android Native | mapping 文件                                             |

<Tip>
  符号文件通过 FlashCat CLI 上传，且上传时的 `version` 必须与 SDK 初始化中的 `version` 一致，否则控制台可以收到崩溃事件，但无法还原堆栈。
</Tip>