From f6e5f023f8c9e91d18f1eb92cece772a8e8644da Mon Sep 17 00:00:00 2001 From: Fiona Date: Mon, 13 Jul 2026 00:43:17 -0700 Subject: [PATCH] docs(rum): add Flutter SDK integration docs Add zh + en documentation for the Flutter RUM SDK (flashcat_flutter_plugin v0.1.0, iOS + Android), mirroring the HarmonyOS page structure: sdk-integration, advanced-config, compatible, data-collection. Register the Flutter nav group in both language sections of docs.json. Content is grounded in the actual v1 SDK API (DatadogSdk.runApp, FlashcatSite.cn, customEndpoint on DatadogRumConfiguration, DatadogNavigationObserver) and flags v1 limitations (git dependency until pub.dev is confirmed, no Logs/Session Replay, HTTP tracking needs a dependency_override). Validated with mint broken-links. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs.json | 18 +++ en/rum/sdk/flutter/advanced-config.mdx | 114 +++++++++++++++ en/rum/sdk/flutter/compatible.mdx | 69 +++++++++ en/rum/sdk/flutter/data-collection.mdx | 79 ++++++++++ en/rum/sdk/flutter/sdk-integration.mdx | 195 +++++++++++++++++++++++++ zh/rum/sdk/flutter/advanced-config.mdx | 114 +++++++++++++++ zh/rum/sdk/flutter/compatible.mdx | 69 +++++++++ zh/rum/sdk/flutter/data-collection.mdx | 79 ++++++++++ zh/rum/sdk/flutter/sdk-integration.mdx | 195 +++++++++++++++++++++++++ 9 files changed, 932 insertions(+) create mode 100644 en/rum/sdk/flutter/advanced-config.mdx create mode 100644 en/rum/sdk/flutter/compatible.mdx create mode 100644 en/rum/sdk/flutter/data-collection.mdx create mode 100644 en/rum/sdk/flutter/sdk-integration.mdx create mode 100644 zh/rum/sdk/flutter/advanced-config.mdx create mode 100644 zh/rum/sdk/flutter/compatible.mdx create mode 100644 zh/rum/sdk/flutter/data-collection.mdx create mode 100644 zh/rum/sdk/flutter/sdk-integration.mdx diff --git a/docs.json b/docs.json index c75b2e9..b6f426d 100644 --- a/docs.json +++ b/docs.json @@ -407,6 +407,15 @@ "zh/rum/sdk/harmony/data-collection" ] }, + { + "group": "Flutter", + "pages": [ + "zh/rum/sdk/flutter/sdk-integration", + "zh/rum/sdk/flutter/advanced-config", + "zh/rum/sdk/flutter/compatible", + "zh/rum/sdk/flutter/data-collection" + ] + }, { "group": "微信小程序", "pages": [ @@ -1616,6 +1625,15 @@ "en/rum/sdk/harmony/data-collection" ] }, + { + "group": "Flutter", + "pages": [ + "en/rum/sdk/flutter/sdk-integration", + "en/rum/sdk/flutter/advanced-config", + "en/rum/sdk/flutter/compatible", + "en/rum/sdk/flutter/data-collection" + ] + }, { "group": "WeChat Mini Program", "pages": [ diff --git a/en/rum/sdk/flutter/advanced-config.mdx b/en/rum/sdk/flutter/advanced-config.mdx new file mode 100644 index 0000000..93f4d0e --- /dev/null +++ b/en/rum/sdk/flutter/advanced-config.mdx @@ -0,0 +1,114 @@ +--- +title: "Flutter SDK advanced configuration" +description: "Configure sampling, tracking consent, event filtering, distributed tracing, and symbol file upload for the Flutter RUM SDK" +keywords: ["RUM", "Flutter SDK", "advanced configuration", "sampling", "tracking consent", "symbol upload"] +--- + +This page describes the advanced configuration options of the Flutter SDK. All configuration is passed through `DatadogConfiguration` and `DatadogRumConfiguration`. + +## Sampling rate + +```dart +DatadogRumConfiguration( + applicationId: '', + sessionSamplingRate: 100.0, // Session sampling rate + traceSampleRate: 20.0, // Trace sampling rate on resources +); +``` + +## Tracking consent + +`TrackingConsent` controls whether data is collected and reported, to meet compliance requirements such as GDPR: + +| Value | Behavior | +|------|------| +| `TrackingConsent.granted` | Collect and report | +| `TrackingConsent.notGranted` | Do not collect | +| `TrackingConsent.pending` | Cache first, then decide whether to report or drop after the user grants consent | + +```dart +// Pass in during initialization +await DatadogSdk.runApp(configuration, TrackingConsent.pending, () async { + runApp(const MyApp()); +}); + +// Update after the user grants consent +DatadogSdk.instance.setTrackingConsent(TrackingConsent.granted); +``` + +## Event filtering and masking + +Event mappers run before events are reported; return `null` to drop the event, or return it after modification. You can use them to mask sensitive fields, remove noise, or rename views. + +```dart +DatadogRumConfiguration( + applicationId: '', + viewEventMapper: (event) => event, + actionEventMapper: (event) => event, + resourceEventMapper: (event) { + // For example, remove the query token from the URL + return event; + }, + errorEventMapper: (event) => event, + longTaskEventMapper: (event) => event, +); +``` + +## Distributed tracing + +For hosts that match `firstPartyHosts`, the SDK injects the W3C `traceparent` to correlate frontend RUM with backend APM. Tracing requires network collection (`enableHttpTracking()`). + +```dart +DatadogConfiguration( + clientToken: '', + env: 'production', + site: FlashcatSite.cn, + firstPartyHosts: ['api.example.com', 'gateway.example.com'], + rumConfiguration: DatadogRumConfiguration( + applicationId: '', + traceSampleRate: 100.0, + ), +)..enableHttpTracking(); +``` + +## Custom reporting endpoint + +For on-premises deployments, override the default reporting endpoint through `customEndpoint`: + +```dart +DatadogRumConfiguration( + applicationId: '', + customEndpoint: 'https://your-ingest.example.com', +); +``` + +## Symbol file upload + +To resolve crash and error stacks back to source locations, you need to upload symbol files. A Flutter application may contain both Dart and native frames: + +| Frame type | Required files | How to generate | +|----------|----------|----------| +| Dart | Flutter symbols | `flutter build --split-debug-info= --obfuscate` | +| iOS Native | dSYM | Xcode build output | +| Android Native | mapping files | R8 / ProGuard output | + +Use the FlashCat CLI to upload symbol files: + +```bash +# Example: upload the symbol files for the corresponding version +flashcat-cli flutter-symbols upload --service --version +``` + + +The `version` and `service` used at upload time must exactly match the values in the SDK initialization. Otherwise the console can receive crash events but cannot resolve stack frames back to source locations. Make symbol upload part of your release build process. + + +## Other configuration + +| Configuration | Default | Description | +|------|--------|------| +| `nativeCrashReportEnabled` | false | Whether to collect native crashes | +| `detectLongTasks` | true | Whether to collect long tasks | +| `longTaskThreshold` | 0.1s | Long task threshold | +| `trackBackgroundEvents` | false | Whether to collect events while the application is in the background | +| `batchSize` / `uploadFrequency` | — | Upload batch size and frequency, balancing real-time delivery against battery usage | diff --git a/en/rum/sdk/flutter/compatible.mdx b/en/rum/sdk/flutter/compatible.mdx new file mode 100644 index 0000000..a087142 --- /dev/null +++ b/en/rum/sdk/flutter/compatible.mdx @@ -0,0 +1,69 @@ +--- +title: "Flutter SDK compatibility" +description: "Review the platforms, Flutter versions, companion packages, and current limits supported by the Flutter RUM SDK" +keywords: ["RUM", "Flutter SDK", "compatibility", "Dart", "iOS", "Android"] +--- + +This page describes the Flutter SDK support scope and current limits so you can determine whether your project meets the requirements before integration. + +## Support scope + +| Item | Support | +|------|----------| +| SDK version | `flashcat_flutter_plugin` 0.1.0 | +| Target platforms | **iOS and Android** (Flutter Web / Desktop not supported) | +| Flutter / Dart | Flutter ≥ 3.0, Dart ≥ 3.0 | +| iOS | Deployment target ≥ 12.0 | +| Android | `minSdkVersion` ≥ 21 | +| RUM data source | Events always write `source: "flutter"` | +| Implementation | A Flutter plugin wrapping the native iOS / Android SDKs | +| Data upload | `POST /api/v2/rum` | + +## Packages and capabilities + +| Package | pub name | Description | +|------|------|------| +| RUM / Core / Crash | `flashcat_flutter_plugin` | Initialization, configuration, RUM (view / action / resource / error / session), and native crash collection | +| HTTP tracking | `datadog_tracking_http_client` | Automatically records `dart:io` / `http` requests as resources and injects trace headers (requires `dependency_overrides`, not v1 core) | +| WebView tracking | `flashcat_webview_tracking` | Correlates RUM data inside WebViews | + + +The Dart class names still follow the upstream `Datadog*` naming; only the site enum `FlashcatSite` (`.cn` default / `.staging`) and the package name are rebranded. The `DatadogSdk`, `DatadogConfiguration`, `DatadogRumConfiguration`, `DatadogNavigationObserver`, and other classes in the documentation examples are the actual exported class names. + + +## Supported automatic collection + +| Capability | Support | Description | +|------|----------|------| +| Automatic views | Supported | Requires a `DatadogNavigationObserver` on `MaterialApp` | +| Automatic actions | Supported | Requires wrapping the subtree with `RumUserActionDetector`; `trackFrustrations` is enabled by default | +| Automatic resources | Supported (requires companion package) | Through `enableHttpTracking()` from `datadog_tracking_http_client` | +| Unhandled exceptions | Supported | When using `DatadogSdk.runApp`, automatically takes over `FlutterError.onError` / `PlatformDispatcher.onError` | +| Native crashes | Supported | Requires `nativeCrashReportEnabled: true` | +| Distributed tracing | Supported | Injects W3C `traceparent` for hosts that match `firstPartyHosts` | + +## Current limits + +| Limit | Description | +|------|------| +| Platform scope | iOS / Android only; Flutter Web and Desktop are not supported | +| Logs | v1 does not support log reporting (`DatadogLoggingConfiguration` is a no-op) | +| Session Replay | Not supported in v1 (`datadog_session_replay` is a preview, not in the core scope) | +| Companion package naming | `datadog_tracking_http_client` / `datadog_session_replay` still declare their dependency on `datadog_flutter_plugin: ^3.0.0`, so integrating this fork requires `dependency_overrides` | +| dio / gql / grpc | The corresponding interceptor packages are not yet adapted to this fork in v1 | +| Page performance metrics | `reportFlutterPerformance` is disabled by default; the console performance page is currently hidden for Flutter to avoid showing zero-value empty data | +| pub.dev publication | Official publication is being confirmed; git dependencies are currently recommended | + +## Symbolication compatibility + +Flutter crash stacks can contain both Dart frames and native (iOS / Android) frames. To resolve stack frames back to source locations, you need to upload the corresponding symbol files: + +| Frame type | Required uploaded files | +|----------|--------------| +| Dart | Flutter symbols (`flutter build --split-debug-info` output) | +| iOS Native | dSYM | +| Android Native | mapping files | + + +Symbol files are uploaded through the FlashCat CLI, and the `version` used at upload time must match the `version` in the SDK initialization. Otherwise the console can receive crash events but cannot resolve the stacks. + diff --git a/en/rum/sdk/flutter/data-collection.mdx b/en/rum/sdk/flutter/data-collection.mdx new file mode 100644 index 0000000..3fb8f68 --- /dev/null +++ b/en/rum/sdk/flutter/data-collection.mdx @@ -0,0 +1,79 @@ +--- +title: "Flutter SDK data collection" +description: "Learn about the event types, fields, and upload behavior collected by the Flutter RUM SDK" +keywords: ["RUM", "Flutter SDK", "data collection", "view", "action", "resource", "error"] +--- + +This page describes which data the Flutter SDK collects, how it is uploaded, and how to control the collection scope. All events write `source: "flutter"`. + +## Event types + +| Event | Trigger | Description | +|------|----------|------| +| view | Route change (`DatadogNavigationObserver`) or manual API | One page visit, recording load time and the number of internal actions / resources / errors | +| action | Automatic recognition by `RumUserActionDetector` or `rum.addAction` | User interaction (tap / scroll / swipe / custom), can correlate frustration signals | +| resource | `enableHttpTracking()` or `DatadogClient` | One network request, recording URL, method, status code, duration, and size | +| error | Automatic (unhandled exceptions / native crashes) or `rum.addError` | Errors and crashes, including type, message, and stack | +| long task | `detectLongTasks` enabled by default | Main-thread blocking that exceeds `longTaskThreshold` (default 0.1s) | + +## Automatically collected context + +Each event automatically carries the following context (collected by the native layer): + +- **Application information**: `service`, `version`, `env`, and `application_id` +- **Device information**: device model, operating system and version, screen size +- **Session information**: `session.id`, sampled by `sessionSamplingRate` +- **Connection information**: network type (when available) +- **User information**: `usr.id` / `usr.name` / `usr.email` set through `setUserInfo` + +## Manual instrumentation + +In addition to automatic collection, you can manually record events and attributes. + +```dart +final rum = DatadogSdk.instance.rum; + +// Manually manage views +rum?.startView('checkout', 'Checkout'); +rum?.stopView('checkout'); + +// Manually record an action +rum?.addAction(RumActionType.tap, 'pay_button'); + +// Manually report an error +rum?.addErrorInfo('payment failed', RumErrorSource.source); + +// Attach a global attribute (written to all subsequent events) +rum?.addAttribute('tenant', 'acme'); +``` + +## Sampling and control + +| Configuration | Default | Description | +|------|--------|------| +| `sessionSamplingRate` | 100.0 | Session sampling rate (percentage); unsampled sessions produce no RUM data | +| `traceSampleRate` | 100.0 | Sampling rate for distributed tracing on resources | +| `telemetrySampleRate` | 20.0 | Sampling rate for the SDK's own telemetry | +| `detectLongTasks` | true | Whether to collect long tasks | +| `trackFrustrations` | true | Whether to generate frustration signals from user actions | +| `trackAnonymousUser` | true | Whether to generate an anonymous ID for signed-out users | + +## Data masking + +Event mappers let you modify or drop data before events are reported, for masking or filtering out noise. See Advanced configuration. + +```dart +DatadogRumConfiguration( + applicationId: '', + resourceEventMapper: (event) { + // Return null to drop the event, or return it after modification + return event; + }, +); +``` + +## Upload behavior + +- The SDK batches and caches at the native layer, uploading in batches by `batchSize` and `uploadFrequency` +- When the network is unavailable, events are persisted locally and retried after recovery +- The upload endpoint defaults to the site's endpoint (`FlashcatSite.cn` → `browser.flashcat.cloud`); on-premises deployments can override it through `customEndpoint` diff --git a/en/rum/sdk/flutter/sdk-integration.mdx b/en/rum/sdk/flutter/sdk-integration.mdx new file mode 100644 index 0000000..a39e817 --- /dev/null +++ b/en/rum/sdk/flutter/sdk-integration.mdx @@ -0,0 +1,195 @@ +--- +title: "Flutter SDK integration" +description: "Integrate Flashduty RUM SDK into Flutter applications to collect views, actions, network requests, errors, and crashes" +keywords: ["RUM", "Flutter SDK", "Dart", "user monitoring", "mobile monitoring"] +--- + +The Flutter SDK wraps the native iOS / Android SDKs and provides RUM capabilities through `flashcat_flutter_plugin`. After initialization, the SDK reports the application's views, user actions, network requests, errors, and crashes to Flashduty RUM, with `source: "flutter"` identifying the data source. + + +The current SDK version is `0.1.0` and supports only the **iOS and Android** platforms (Flutter Web is not supported). The Dart class names still follow the upstream `Datadog*` naming (such as `DatadogSdk` and `DatadogConfiguration`); only the package name `flashcat_flutter_plugin` and the site enum `FlashcatSite` are rebranded. v1 does not yet include Logs, Session Replay, or the dio / gql / grpc companion packages. + + +## Prerequisites + +Before integrating the SDK, complete these steps: + +- Create or select a RUM application in the Flashduty console, then obtain the **Application ID** and **Client Token** +- Make sure your application can reach `https://browser.flashcat.cloud/api/v2/rum` +- Flutter SDK ≥ 3.0, Dart ≥ 3.0; iOS deployment target ≥ 12.0, Android `minSdkVersion` ≥ 21 +- Initialize the SDK early in application startup (in `main()`) + +## Install the SDK + +Add `flashcat_flutter_plugin` to `pubspec.yaml`, then run `flutter pub get`. + + +The pub.dev publication of `flashcat_flutter_plugin` is still being confirmed. To keep the dependency resolvable, the example below uses a git source. Once it is officially published to pub.dev, you can switch to the hosted form `flashcat_flutter_plugin: ^0.1.0`. + + +```yaml pubspec.yaml +dependencies: + flashcat_flutter_plugin: + git: + url: https://github.com/flashcatcloud/fc-sdk-flutter + path: packages/datadog_flutter_plugin +``` + +## Initialize the SDK + +We recommend initializing in `main()`, before `runApp`. When you start the application with `DatadogSdk.runApp`, the SDK automatically takes over `FlutterError.onError` and `PlatformDispatcher.instance.onError`, so it can collect unhandled exceptions without manual wiring. + +```dart main.dart +import 'package:flutter/widgets.dart'; +import 'package:flashcat_flutter_plugin/flashcat_flutter_plugin.dart'; + +Future main() async { + final configuration = DatadogConfiguration( + clientToken: '', + env: 'production', + service: 'com.example.shopping', + site: FlashcatSite.cn, + nativeCrashReportEnabled: true, // Collect native iOS / Android crashes + firstPartyHosts: ['api.example.com'], // Inject distributed trace headers for these hosts + rumConfiguration: DatadogRumConfiguration( + applicationId: '', + sessionSamplingRate: 100.0, + // customEndpoint: 'https://your-ingest.example.com', // Custom reporting endpoint for on-premises deployments + ), + ); + + await DatadogSdk.runApp(configuration, TrackingConsent.granted, () async { + runApp(const MyApp()); + }); +} +``` + + +Do not use server-side secrets in client code. `clientToken` is only for client-side RUM reporting, and `applicationId` assigns events to the RUM application. + + +If you need to control the startup flow yourself, outside of `runApp`, you can also initialize manually, but you must wire up error collection yourself: + +```dart +WidgetsFlutterBinding.ensureInitialized(); +await DatadogSdk.instance.initialize(configuration, TrackingConsent.granted); + +final originalOnError = FlutterError.onError; +FlutterError.onError = (details) { + DatadogSdk.instance.rum?.handleFlutterError(details); + originalOnError?.call(details); +}; +``` + +## Track views + +Add a `DatadogNavigationObserver` to your `MaterialApp` (or `CupertinoApp`), and the SDK automatically records the Navigator's route changes as RUM views. + +```dart +import 'package:flashcat_flutter_plugin/flashcat_flutter_plugin.dart'; + +MaterialApp( + navigatorObservers: [ + DatadogNavigationObserver(datadogSdk: DatadogSdk.instance), + ], + home: const HomeScreen(), +); +``` + + +The `DatadogNavigationObserver` constructor uses the named parameter `datadogSdk:`. By default it uses the route's `settings.name` as the view name; you can customize the view name or filter routes through the `viewInfoExtractor` callback. + + +For scenarios that do not use named routes, you can use `DatadogNavigationObserverProvider` together with `DatadogRouteAwareMixin` to manage views manually. + +## Track user actions + +In the RUM configuration, `trackFrustrations` is enabled by default. After you wrap your application subtree with `RumUserActionDetector`, the SDK automatically recognizes interactions such as taps and generates action events; you can also record actions manually. + +```dart +// Automatically recognize user interactions in the subtree +RumUserActionDetector( + rum: DatadogSdk.instance.rum, + child: const MyApp(), +); + +// Manually record one action +DatadogSdk.instance.rum?.addAction(RumActionType.tap, 'Checkout'); +``` + +## Track network requests + +Automatic network collection is provided by the separate `datadog_tracking_http_client` package and enabled through the `enableHttpTracking()` extension method on the configuration object. It globally replaces `HttpClient`, records `dart:io` / `http` requests as RUM resources, and injects W3C trace headers for hosts that match `firstPartyHosts`. + +```dart +final configuration = DatadogConfiguration( + clientToken: '', + env: 'production', + site: FlashcatSite.cn, + firstPartyHosts: ['api.example.com'], + rumConfiguration: DatadogRumConfiguration(applicationId: ''), +)..enableHttpTracking(); +``` + + +`datadog_tracking_http_client` currently declares its dependency on `datadog_flutter_plugin` (`^3.0.0`), which cannot be resolved directly with this fork's `flashcat_flutter_plugin` 0.1.0. When you enable network collection, add a `dependency_overrides` entry in `pubspec.yaml` pointing to this fork. This capability is not part of the v1 core scope and can be integrated as needed. + + +## Identify users + +After sign-in, you can set the current user. The SDK writes the user fields to the `usr` object on subsequent RUM events. + +```dart +DatadogSdk.instance.setUserInfo( + id: 'user-1001', + name: 'Alice', + email: 'alice@example.com', +); +``` + +Clear user information when the user signs out: + +```dart +DatadogSdk.instance.setUserInfo(); +``` + +## Report errors + +When you use `DatadogSdk.runApp`, unhandled exceptions are collected automatically. You can also manually report caught exceptions: + +```dart +try { + // ... business logic ... +} catch (e, st) { + DatadogSdk.instance.rum?.addError(e, RumErrorSource.source, stackTrace: st); +} +``` + + +Crash and error stacks require uploaded symbol files to resolve back to source locations. Flutter symbols, iOS dSYM, and Android mapping files are uploaded through the FlashCat CLI, and the `version` used at upload time must match the `version` in the SDK initialization. See Advanced configuration. + + +## Verify the integration + +After integration, verify it with these steps: + +1. Temporarily set `DatadogSdk.instance.sdkVerbosity = CoreLoggerLevel.debug` during initialization, and inspect the console logs to observe the SDK's reporting behavior +2. Run the application and trigger page navigation, taps, network requests, or a manual error +3. In the Flashduty RUM application, filter for `source:flutter` and confirm that view, action, resource, or error events appear +4. For network requests, check whether the backend receives the W3C `traceparent` + +## Next steps + + + +Configure sampling, tracking consent, event filtering, tracing, and symbol file upload. + + + +Review supported platforms, Flutter versions, companion packages, and current limits. + + + +Review event types, fields, and upload behavior collected automatically and manually by the SDK. + + diff --git a/zh/rum/sdk/flutter/advanced-config.mdx b/zh/rum/sdk/flutter/advanced-config.mdx new file mode 100644 index 0000000..b8a9c8b --- /dev/null +++ b/zh/rum/sdk/flutter/advanced-config.mdx @@ -0,0 +1,114 @@ +--- +title: "Flutter SDK 高级配置" +description: "配置 Flutter RUM SDK 的采样率、隐私同意、事件过滤、分布式追踪和符号文件上传" +keywords: ["RUM", "Flutter SDK", "高级配置", "采样", "隐私同意", "符号上传"] +--- + +本文介绍 Flutter SDK 的进阶配置项。所有配置都通过 `DatadogConfiguration` 与 `DatadogRumConfiguration` 传入。 + +## 采样率 + +```dart +DatadogRumConfiguration( + applicationId: '', + sessionSamplingRate: 100.0, // 会话采样率 + traceSampleRate: 20.0, // resource 上的追踪采样率 +); +``` + +## 隐私同意 + +`TrackingConsent` 控制是否采集与上报数据，适配 GDPR 等合规要求： + +| 取值 | 行为 | +|------|------| +| `TrackingConsent.granted` | 采集并上报 | +| `TrackingConsent.notGranted` | 不采集 | +| `TrackingConsent.pending` | 先缓存，待用户授权后决定上报或丢弃 | + +```dart +// 初始化时传入 +await DatadogSdk.runApp(configuration, TrackingConsent.pending, () async { + runApp(const MyApp()); +}); + +// 用户授权后更新 +DatadogSdk.instance.setTrackingConsent(TrackingConsent.granted); +``` + +## 事件过滤与脱敏 + +事件映射器在事件上报前执行，返回 `null` 丢弃事件，或修改后返回。可用于脱敏敏感字段、去除噪声、重命名视图。 + +```dart +DatadogRumConfiguration( + applicationId: '', + viewEventMapper: (event) => event, + actionEventMapper: (event) => event, + resourceEventMapper: (event) { + // 例如去除 URL 中的 query token + return event; + }, + errorEventMapper: (event) => event, + longTaskEventMapper: (event) => event, +); +``` + +## 分布式追踪 + +对 `firstPartyHosts` 命中的域名，SDK 会注入 W3C `traceparent`，实现前端 RUM 与后端 APM 的链路关联。追踪需要配合网络采集（`enableHttpTracking()`）。 + +```dart +DatadogConfiguration( + clientToken: '', + env: 'production', + site: FlashcatSite.cn, + firstPartyHosts: ['api.example.com', 'gateway.example.com'], + rumConfiguration: DatadogRumConfiguration( + applicationId: '', + traceSampleRate: 100.0, + ), +)..enableHttpTracking(); +``` + +## 自定义上报地址 + +私有化部署时，通过 `customEndpoint` 覆盖默认上报地址： + +```dart +DatadogRumConfiguration( + applicationId: '', + customEndpoint: 'https://your-ingest.example.com', +); +``` + +## 符号文件上传 + +要把崩溃与错误堆栈还原到源码位置，需要上传符号文件。Flutter 应用可能同时包含 Dart 与原生帧： + +| 栈帧类型 | 所需文件 | 生成方式 | +|----------|----------|----------| +| Dart | Flutter symbols | `flutter build --split-debug-info= --obfuscate` | +| iOS Native | dSYM | Xcode 构建产物 | +| Android Native | mapping 文件 | R8 / ProGuard 产物 | + +使用 FlashCat CLI 上传符号文件： + +```bash +# 示例：上传对应 version 的符号文件 +flashcat-cli flutter-symbols upload --service --version +``` + + +上传时的 `version` 与 `service` 必须与 SDK 初始化中的值完全一致，否则控制台可以收到崩溃事件，但无法把栈帧还原到源码位置。请把符号上传纳入发布构建流程。 + + +## 其他配置 + +| 配置 | 默认值 | 说明 | +|------|--------|------| +| `nativeCrashReportEnabled` | false | 是否采集原生崩溃 | +| `detectLongTasks` | true | 是否采集 long task | +| `longTaskThreshold` | 0.1s | long task 判定阈值 | +| `trackBackgroundEvents` | false | 是否采集应用后台期间的事件 | +| `batchSize` / `uploadFrequency` | — | 上报批量大小与频率，权衡实时性与耗电 | diff --git a/zh/rum/sdk/flutter/compatible.mdx b/zh/rum/sdk/flutter/compatible.mdx new file mode 100644 index 0000000..3783007 --- /dev/null +++ b/zh/rum/sdk/flutter/compatible.mdx @@ -0,0 +1,69 @@ +--- +title: "Flutter SDK 兼容性" +description: "了解 Flutter RUM SDK 支持的平台、Flutter 版本、伴生包和当前限制" +keywords: ["RUM", "Flutter SDK", "兼容性", "Dart", "iOS", "Android"] +--- + +本文说明 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 数据 | + + +Dart 类名仍沿用上游 `Datadog*` 命名，仅站点枚举 `FlashcatSite`（`.cn` 默认 / `.staging`）与包名做了品牌化。文档示例中的 `DatadogSdk`、`DatadogConfiguration`、`DatadogRumConfiguration`、`DatadogNavigationObserver` 等均为实际导出的类名。 + + +## 支持的自动采集 + +| 能力 | 支持情况 | 说明 | +|------|----------|------| +| 自动 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 文件 | + + +符号文件通过 FlashCat CLI 上传，且上传时的 `version` 必须与 SDK 初始化中的 `version` 一致，否则控制台可以收到崩溃事件，但无法还原堆栈。 + diff --git a/zh/rum/sdk/flutter/data-collection.mdx b/zh/rum/sdk/flutter/data-collection.mdx new file mode 100644 index 0000000..922cc6b --- /dev/null +++ b/zh/rum/sdk/flutter/data-collection.mdx @@ -0,0 +1,79 @@ +--- +title: "Flutter SDK 数据收集" +description: "了解 Flutter RUM SDK 采集的事件类型、字段与上报行为" +keywords: ["RUM", "Flutter SDK", "数据收集", "view", "action", "resource", "error"] +--- + +本文说明 Flutter SDK 采集哪些数据、如何上报，以及如何控制采集范围。所有事件都写入 `source: "flutter"`。 + +## 事件类型 + +| 事件 | 触发方式 | 说明 | +|------|----------|------| +| view | 路由切换（`DatadogNavigationObserver`）或手动 API | 一次页面停留，记录加载耗时、内部的 action / resource / error 数量 | +| action | `RumUserActionDetector` 自动识别或 `rum.addAction` | 用户交互（tap / scroll / swipe / custom），可关联 frustration 信号 | +| resource | `enableHttpTracking()` 或 `DatadogClient` | 一次网络请求，记录 URL、方法、状态码、耗时、大小 | +| error | 自动（未处理异常 / 原生崩溃）或 `rum.addError` | 错误与崩溃，含类型、消息、堆栈 | +| long task | `detectLongTasks` 默认开启 | 超过 `longTaskThreshold`（默认 0.1s）的主线程阻塞 | + +## 自动采集的上下文 + +每个事件会自动附带以下上下文（由原生层采集）： + +- **应用信息**：`service`、`version`、`env`，以及 `application_id` +- **设备信息**：设备型号、操作系统与版本、屏幕尺寸 +- **会话信息**：`session.id`，按 `sessionSamplingRate` 采样 +- **连接信息**：网络类型（如可用） +- **用户信息**：通过 `setUserInfo` 设置的 `usr.id` / `usr.name` / `usr.email` + +## 手动埋点 + +除了自动采集，你可以手动记录事件与属性。 + +```dart +final rum = DatadogSdk.instance.rum; + +// 手动管理视图 +rum?.startView('checkout', 'Checkout'); +rum?.stopView('checkout'); + +// 手动记录操作 +rum?.addAction(RumActionType.tap, 'pay_button'); + +// 手动上报错误 +rum?.addErrorInfo('payment failed', RumErrorSource.source); + +// 附加全局属性（写入后续所有事件） +rum?.addAttribute('tenant', 'acme'); +``` + +## 采样与控制 + +| 配置 | 默认值 | 说明 | +|------|--------|------| +| `sessionSamplingRate` | 100.0 | 会话采样率（百分比）；未命中的会话不产生 RUM 数据 | +| `traceSampleRate` | 100.0 | resource 上分布式追踪的采样率 | +| `telemetrySampleRate` | 20.0 | SDK 自身遥测采样率 | +| `detectLongTasks` | true | 是否采集 long task | +| `trackFrustrations` | true | 是否从用户操作生成 frustration 信号 | +| `trackAnonymousUser` | true | 是否为未登录用户生成匿名 ID | + +## 数据脱敏 + +通过事件映射器（event mapper）可以在事件上报前修改或丢弃数据，用于脱敏或过滤噪声。详见 高级配置。 + +```dart +DatadogRumConfiguration( + applicationId: '', + resourceEventMapper: (event) { + // 返回 null 丢弃事件，或修改后返回 + return event; + }, +); +``` + +## 上报行为 + +- SDK 在原生层做批量缓存，按 `batchSize` 与 `uploadFrequency` 分批上报 +- 网络不可用时事件会持久化到本地，恢复后重试 +- 上报地址默认为站点对应地址（`FlashcatSite.cn` → `browser.flashcat.cloud`），私有化可通过 `customEndpoint` 覆盖 diff --git a/zh/rum/sdk/flutter/sdk-integration.mdx b/zh/rum/sdk/flutter/sdk-integration.mdx new file mode 100644 index 0000000..7419fe2 --- /dev/null +++ b/zh/rum/sdk/flutter/sdk-integration.mdx @@ -0,0 +1,195 @@ +--- +title: "Flutter SDK 接入" +description: "在 Flutter 应用中接入 Flashduty RUM SDK，采集视图、操作、网络、错误和崩溃数据" +keywords: ["RUM", "Flutter SDK", "Dart", "用户监控", "移动端监控"] +--- + +Flutter SDK 基于原生 iOS / Android SDK 封装，通过 `flashcat_flutter_plugin` 提供 RUM 能力。初始化后，SDK 会把应用中的视图、用户操作、网络请求、错误和崩溃事件上报到 Flashduty RUM，并使用 `source: "flutter"` 标识数据来源。 + + +当前 SDK 版本为 `0.1.0`，仅支持 **iOS 和 Android** 平台（不支持 Flutter Web）。Dart 类名仍沿用上游 `Datadog*` 命名（如 `DatadogSdk`、`DatadogConfiguration`），仅包名 `flashcat_flutter_plugin` 与站点枚举 `FlashcatSite` 做了品牌化。v1 暂不包含 Logs、Session Replay、dio / gql / grpc 伴生包。 + + +## 前提条件 + +接入前，请先完成以下准备： + +- 在 Flashduty 控制台创建或选择一个 RUM 应用，并获取 **Application ID** 和 **Client Token** +- 确认应用可以访问 `https://browser.flashcat.cloud/api/v2/rum` +- Flutter SDK ≥ 3.0，Dart ≥ 3.0；iOS 部署目标 ≥ 12.0，Android `minSdkVersion` ≥ 21 +- 在应用启动早期（`main()` 中）完成 SDK 初始化 + +## 安装 SDK + +在 `pubspec.yaml` 中添加 `flashcat_flutter_plugin`，然后执行 `flutter pub get`。 + + +`flashcat_flutter_plugin` 的 pub.dev 发布仍在确认中。为保证依赖可解析，下方示例使用 git 源。待正式发布到 pub.dev 后，可切换为 `flashcat_flutter_plugin: ^0.1.0` 的托管形式。 + + +```yaml pubspec.yaml +dependencies: + flashcat_flutter_plugin: + git: + url: https://github.com/flashcatcloud/fc-sdk-flutter + path: packages/datadog_flutter_plugin +``` + +## 初始化 SDK + +建议在 `main()` 中、`runApp` 之前完成初始化。使用 `DatadogSdk.runApp` 启动应用时，SDK 会自动接管 `FlutterError.onError` 与 `PlatformDispatcher.instance.onError`，无需手动接线即可采集未处理异常。 + +```dart main.dart +import 'package:flutter/widgets.dart'; +import 'package:flashcat_flutter_plugin/flashcat_flutter_plugin.dart'; + +Future main() async { + final configuration = DatadogConfiguration( + clientToken: '', + env: 'production', + service: 'com.example.shopping', + site: FlashcatSite.cn, + nativeCrashReportEnabled: true, // 采集原生 iOS / Android 崩溃 + firstPartyHosts: ['api.example.com'], // 对这些域名注入分布式追踪头 + rumConfiguration: DatadogRumConfiguration( + applicationId: '', + sessionSamplingRate: 100.0, + // customEndpoint: 'https://your-ingest.example.com', // 私有化自定义上报地址 + ), + ); + + await DatadogSdk.runApp(configuration, TrackingConsent.granted, () async { + runApp(const MyApp()); + }); +} +``` + + +请不要在客户端代码中使用服务端密钥。`clientToken` 只用于客户端 RUM 数据上报，`applicationId` 用于归属 RUM 应用数据。 + + +如果你需要在 `runApp` 之外自行控制启动流程，也可以手动初始化，但需要自己接线错误采集： + +```dart +WidgetsFlutterBinding.ensureInitialized(); +await DatadogSdk.instance.initialize(configuration, TrackingConsent.granted); + +final originalOnError = FlutterError.onError; +FlutterError.onError = (details) { + DatadogSdk.instance.rum?.handleFlutterError(details); + originalOnError?.call(details); +}; +``` + +## 采集页面视图 + +为 `MaterialApp`（或 `CupertinoApp`）添加 `DatadogNavigationObserver`，SDK 会把 Navigator 的路由切换自动记录为 RUM 视图。 + +```dart +import 'package:flashcat_flutter_plugin/flashcat_flutter_plugin.dart'; + +MaterialApp( + navigatorObservers: [ + DatadogNavigationObserver(datadogSdk: DatadogSdk.instance), + ], + home: const HomeScreen(), +); +``` + + +`DatadogNavigationObserver` 的构造函数使用命名参数 `datadogSdk:`。默认使用路由的 `settings.name` 作为视图名称，可以通过 `viewInfoExtractor` 回调自定义视图名或过滤路由。 + + +对于没有使用命名路由的场景，可以用 `DatadogNavigationObserverProvider` 配合 `DatadogRouteAwareMixin` 手动管理视图。 + +## 采集用户操作 + +在 RUM 配置中 `trackFrustrations` 默认开启。用 `RumUserActionDetector` 包裹应用子树后，SDK 会自动识别点击等交互并生成 action 事件；你也可以手动记录操作。 + +```dart +// 自动识别子树内的用户交互 +RumUserActionDetector( + rum: DatadogSdk.instance.rum, + child: const MyApp(), +); + +// 手动记录一次操作 +DatadogSdk.instance.rum?.addAction(RumActionType.tap, 'Checkout'); +``` + +## 采集网络请求 + +自动网络采集由独立的 `datadog_tracking_http_client` 包提供，通过配置对象上的扩展方法 `enableHttpTracking()` 开启。它会全局替换 `HttpClient`，把 `dart:io` / `http` 请求记录为 RUM resource，并对 `firstPartyHosts` 命中的域名注入 W3C 追踪头。 + +```dart +final configuration = DatadogConfiguration( + clientToken: '', + env: 'production', + site: FlashcatSite.cn, + firstPartyHosts: ['api.example.com'], + rumConfiguration: DatadogRumConfiguration(applicationId: ''), +)..enableHttpTracking(); +``` + + +`datadog_tracking_http_client` 当前仍以 `datadog_flutter_plugin` 命名声明依赖（`^3.0.0`），与本 fork 的 `flashcat_flutter_plugin` 0.1.0 不能直接解析。启用网络采集时需要在 `pubspec.yaml` 中加 `dependency_overrides` 指向本 fork。该能力不属于 v1 核心范围，可按需接入。 + + +## 关联用户信息 + +登录后，你可以设置当前用户。SDK 会把用户字段写入后续 RUM 事件的 `usr` 对象。 + +```dart +DatadogSdk.instance.setUserInfo( + id: 'user-1001', + name: 'Alice', + email: 'alice@example.com', +); +``` + +用户退出登录时清除用户信息： + +```dart +DatadogSdk.instance.setUserInfo(); +``` + +## 上报错误 + +使用 `DatadogSdk.runApp` 时未处理异常会被自动采集。你也可以手动上报捕获到的异常： + +```dart +try { + // ... 业务逻辑 ... +} catch (e, st) { + DatadogSdk.instance.rum?.addError(e, RumErrorSource.source, stackTrace: st); +} +``` + + +崩溃与错误堆栈需要上传符号文件才能还原到源码位置。Flutter symbols、iOS dSYM、Android mapping 文件通过 FlashCat CLI 上传，且上传时的 `version` 必须与 SDK 初始化中的 `version` 一致。详见 高级配置。 + + +## 验证接入 + +完成接入后，可以按以下方式验证： + +1. 在初始化时临时设置 `DatadogSdk.instance.sdkVerbosity = CoreLoggerLevel.debug`，通过控制台日志查看 SDK 上报行为 +2. 运行应用并触发页面切换、点击、网络请求或手动错误 +3. 在 Flashduty RUM 应用中筛选 `source:flutter`，确认出现 view、action、resource 或 error 事件 +4. 对网络请求检查后端是否收到 W3C `traceparent` + +## 下一步 + + + +配置采样率、隐私同意、事件过滤、追踪和符号文件上传。 + + + +了解支持的平台、Flutter 版本、伴生包和当前限制。 + + + +查看 SDK 自动和手动采集的事件类型、字段与上报行为。 + +