Skip to content

Commit 395780b

Browse files
Fiona2016Fiona2016
authored
Merge pull request #227 from flashcatcloud/docs/fix-flutter-rum-audit
docs(rum): align Flutter integration with production
2 parents 28dd626 + 6cd4171 commit 395780b

8 files changed

Lines changed: 172 additions & 22 deletions

File tree

‎en/rum/sdk/flutter/advanced-config.mdx‎

Lines changed: 39 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,9 @@ DatadogRumConfiguration(
5959
For hosts that match `firstPartyHosts`, the SDK injects the W3C `traceparent` to correlate frontend RUM with backend APM. Tracing requires network collection (`enableHttpTracking()`).
6060

6161
```dart
62+
import 'package:flashcat_flutter_plugin/flashcat_flutter_plugin.dart';
63+
import 'package:flashcat_tracking_http_client/flashcat_tracking_http_client.dart';
64+
6265
DatadogConfiguration(
6366
clientToken: '<CLIENT_TOKEN>',
6467
env: 'production',
@@ -78,10 +81,41 @@ For on-premises deployments, override the default reporting endpoint through `cu
7881
```dart
7982
DatadogRumConfiguration(
8083
applicationId: '<APPLICATION_ID>',
81-
customEndpoint: 'https://your-ingest.example.com',
84+
customEndpoint: 'https://your-ingest.example.com/api/v2/rum',
8285
);
8386
```
8487

88+
<Warning>
89+
`customEndpoint` is the final RUM intake URL, not a base origin. It must include `/api/v2/rum`. If the deployment uses a path prefix, preserve it as well, for example `https://example.com/flashduty/api/v2/rum`.
90+
</Warning>
91+
92+
## WebView tracking
93+
94+
When a Flutter screen embeds a WebView, use `flashcat_webview_tracking` to correlate Browser RUM events from the WebView with the current native RUM session.
95+
96+
```yaml pubspec.yaml
97+
dependencies:
98+
flashcat_flutter_plugin: ^0.1.3
99+
webview_flutter: ^4.0.4
100+
flashcat_webview_tracking: ^0.1.0
101+
```
102+
103+
```dart
104+
import 'package:flashcat_flutter_plugin/flashcat_flutter_plugin.dart';
105+
import 'package:flashcat_webview_tracking/flashcat_webview_tracking.dart';
106+
import 'package:webview_flutter/webview_flutter.dart';
107+
108+
final webViewController = WebViewController()
109+
..setJavaScriptMode(JavaScriptMode.unrestricted)
110+
..trackDatadogEvents(
111+
DatadogSdk.instance,
112+
['myapp.example'],
113+
)
114+
..loadRequest(Uri.parse('https://myapp.example'));
115+
```
116+
117+
Pass the allowed hostnames to `trackDatadogEvents`. A hostname matches its subdomains, but wildcards are not supported. The page loaded in the WebView must already use the <a href="/en/rum/sdk/web/sdk-integration">Flashduty Browser SDK</a>. On Android, you must also enable `JavaScriptMode.unrestricted`, or correlation will not work.
118+
85119
## Symbol file upload
86120

87121
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:
@@ -119,4 +153,8 @@ What must match is the build ID: the `app.<platform>-<arch>.symbols` file produc
119153
| `detectLongTasks` | true | Whether to collect long tasks |
120154
| `longTaskThreshold` | 0.1s | Long task threshold |
121155
| `trackBackgroundEvents` | false | Whether to collect events while the application is in the background |
156+
| `vitalUpdateFrequency` | `VitalsFrequency.average` | Collection frequency for native mobile performance metrics; set to `null` to disable |
157+
| `reportFlutterPerformance` | false | Whether to additionally collect Flutter build / raster timings |
158+
| `trackNonFatalAnrs` | Platform default | Whether to collect non-fatal ANRs; disabled by default on Android 30+ and enabled by default on Android 29 and earlier |
159+
| `appHangThreshold` | null | iOS App Hang threshold in seconds; `null` disables collection |
122160
| `batchSize` / `uploadFrequency` | — | Upload batch size and frequency, balancing real-time delivery against battery usage |

‎en/rum/sdk/flutter/compatible.mdx‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,9 @@ This page describes the Flutter SDK support scope and current limits so you can
1212
|------|----------|
1313
| SDK version | `flashcat_flutter_plugin` 0.1.3 |
1414
| Target platforms | **iOS and Android** (Flutter Web / Desktop not supported) |
15-
| Flutter / Dart | Flutter ≥ 3.0, Dart ≥ 3.0 |
15+
| Flutter / Dart | Flutter ≥ 3.27.0, Dart ≥ 3.6.0 |
1616
| iOS | Deployment target ≥ 12.0 |
17-
| Android | `minSdkVersion` ≥ 21 |
17+
| Android | `minSdkVersion` ≥ 23 |
1818
| RUM data source | Events always write `source: "flutter"` |
1919
| Implementation | A Flutter plugin wrapping the native iOS / Android SDKs |
2020
| Data upload | `POST /api/v2/rum` |
@@ -28,7 +28,7 @@ This page describes the Flutter SDK support scope and current limits so you can
2828
| WebView tracking | `flashcat_webview_tracking` | Correlates RUM data inside WebViews |
2929

3030
<Note>
31-
Dart class names begin with `Datadog*`, and the site enum is `FlashcatSite` (`.cn` default / `.staging`). The `DatadogSdk`, `DatadogConfiguration`, `DatadogRumConfiguration`, `DatadogNavigationObserver`, and other classes in the documentation examples are the actual exported class names.
31+
Dart class names begin with `Datadog*`, and the site enum is `FlashcatSite`. Use the default `.cn` site for customer-facing production environments; configure the full `customEndpoint` for on-premises deployments. The `DatadogSdk`, `DatadogConfiguration`, `DatadogRumConfiguration`, `DatadogNavigationObserver`, and other classes in the documentation examples are the actual exported class names.
3232
</Note>
3333

3434
## Supported automatic collection
@@ -41,6 +41,8 @@ Dart class names begin with `Datadog*`, and the site enum is `FlashcatSite` (`.c
4141
| Unhandled exceptions | Supported | When using `DatadogSdk.runApp`, automatically takes over `FlutterError.onError` / `PlatformDispatcher.onError` |
4242
| Native crashes | Supported | Requires `nativeCrashReportEnabled: true` |
4343
| Distributed tracing | Supported | Injects W3C `traceparent` for hosts that match `firstPartyHosts` |
44+
| Native mobile performance metrics | Supported | Collects app start (TTID), refresh rate, and memory by default |
45+
| Hang detection | Supported | Android supports ANRs; iOS supports App Hangs after you set `appHangThreshold` |
4446

4547
## Current limits
4648

@@ -50,7 +52,7 @@ Dart class names begin with `Datadog*`, and the site enum is `FlashcatSite` (`.c
5052
| Logs | Log reporting is not supported (`DatadogLoggingConfiguration` is a no-op) |
5153
| Session Replay | Not supported |
5254
| dio / gql / grpc | The corresponding interceptor packages are not supported |
53-
| Page performance metrics | `reportFlutterPerformance` is disabled by default |
55+
| Flutter rendering timings | `reportFlutterPerformance` is disabled by default; it controls only Flutter build / raster timings and does not affect the native mobile performance metrics collected by default |
5456
| Minimum version | Use `flashcat_flutter_plugin` 0.1.3 or later; on earlier versions `flutter build apk --release` fails in R8 |
5557

5658
## Symbolication compatibility

‎en/rum/sdk/flutter/data-collection.mdx‎

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,12 +20,27 @@ This page describes which data the Flutter SDK collects, how it is uploaded, and
2020

2121
Each event automatically carries the following context (collected by the native layer):
2222

23-
- **Application information**: `service`, `version`, `env`, and `application_id`
23+
- **Application information**: `service`, `version`, `env`, and `application.id`
2424
- **Device information**: device model, operating system and version, screen size
2525
- **Session information**: `session.id`, sampled by `sessionSamplingRate`
2626
- **Connection information**: network type (when available)
2727
- **User information**: `usr.id` / `usr.name` / `usr.email` set through `setUserInfo`
2828

29+
## Performance data
30+
31+
The console displays the Performance page for Flutter applications and supports the following native iOS / Android performance data:
32+
33+
| Metric | Platform | Description |
34+
|------|------|------|
35+
| App start (TTID) | iOS / Android | Time from application launch until the initial screen is displayed |
36+
| Refresh rate | iOS / Android | View rendering smoothness |
37+
| Memory | iOS / Android | Memory usage while the application is running |
38+
| ANR | Android | Application Not Responding events; the Android version determines the default for non-fatal ANRs, which you can override with `trackNonFatalAnrs` |
39+
| App Hang | iOS | Main-thread hang events; requires `appHangThreshold` and is disabled by default |
40+
| Flutter build / raster timing | iOS / Android | Requires explicitly setting `reportFlutterPerformance: true` |
41+
42+
App start, refresh-rate, and memory vitals are controlled by `vitalUpdateFrequency`, which defaults to `VitalsFrequency.average`; set it to `null` to disable them. `reportFlutterPerformance` controls only Flutter frame build / raster timings and is disabled by default. It does not affect these native vitals.
43+
2944
## Manual instrumentation
3045

3146
In addition to automatic collection, you can manually record events and attributes.
@@ -57,6 +72,10 @@ rum?.addAttribute('tenant', 'acme');
5772
| `detectLongTasks` | true | Whether to collect long tasks |
5873
| `trackFrustrations` | true | Whether to generate frustration signals from user actions |
5974
| `trackAnonymousUser` | true | Whether to generate an anonymous ID for signed-out users |
75+
| `vitalUpdateFrequency` | `VitalsFrequency.average` | Collection frequency for native mobile performance metrics; set to `null` to disable |
76+
| `reportFlutterPerformance` | false | Whether to collect Flutter build / raster timings |
77+
| `trackNonFatalAnrs` | Platform default | Whether to collect non-fatal ANRs; disabled by default on Android 30+ and enabled by default on Android 29 and earlier |
78+
| `appHangThreshold` | null | iOS App Hang threshold in seconds; `null` disables collection |
6079

6180
## Data masking
6281

@@ -76,4 +95,4 @@ DatadogRumConfiguration(
7695

7796
- The SDK batches and caches at the native layer, uploading in batches by `batchSize` and `uploadFrequency`
7897
- When the network is unavailable, events are persisted locally and retried after recovery
79-
- The upload endpoint defaults to the site's endpoint (`FlashcatSite.cn` → `browser.flashcat.cloud`); on-premises deployments can override it through `customEndpoint`
98+
- The upload endpoint defaults to `https://browser.flashcat.cloud/api/v2/rum`; on-premises deployments can set `customEndpoint` to the full RUM intake URL (it must include `/api/v2/rum` and preserve any deployment path prefix)

‎en/rum/sdk/flutter/sdk-integration.mdx‎

Lines changed: 20 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ Before integrating the SDK, complete these steps:
1616

1717
- Create or select a RUM application in the Flashduty console, then obtain the **Application ID** and **Client Token**
1818
- Make sure your application can reach `https://browser.flashcat.cloud/api/v2/rum`
19-
- Flutter SDK ≥ 3.0, Dart ≥ 3.0; iOS deployment target ≥ 12.0, Android `minSdkVersion` ≥ 21
19+
- Flutter SDK ≥ 3.27.0, Dart ≥ 3.6.0; iOS deployment target ≥ 12.0, Android `minSdkVersion` ≥ 23
2020
- Initialize the SDK early in application startup (in `main()`)
2121

2222
## Install the SDK
@@ -51,7 +51,7 @@ Future<void> main() async {
5151
rumConfiguration: DatadogRumConfiguration(
5252
applicationId: '<APPLICATION_ID>',
5353
sessionSamplingRate: 100.0,
54-
// customEndpoint: 'https://your-ingest.example.com', // Custom reporting endpoint for on-premises deployments
54+
// customEndpoint: 'https://your-ingest.example.com/api/v2/rum', // On-premises RUM intake URL
5555
),
5656
);
5757
@@ -68,14 +68,27 @@ Do not use server-side secrets in client code. `clientToken` is only for client-
6868
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:
6969

7070
```dart
71+
import 'dart:ui';
72+
7173
WidgetsFlutterBinding.ensureInitialized();
72-
await DatadogSdk.instance.initialize(configuration, TrackingConsent.granted);
7374
7475
final originalOnError = FlutterError.onError;
7576
FlutterError.onError = (details) {
7677
DatadogSdk.instance.rum?.handleFlutterError(details);
7778
originalOnError?.call(details);
7879
};
80+
81+
final originalPlatformOnError = PlatformDispatcher.instance.onError;
82+
PlatformDispatcher.instance.onError = (error, stackTrace) {
83+
DatadogSdk.instance.rum?.addErrorInfo(
84+
error.toString(),
85+
RumErrorSource.source,
86+
stackTrace: stackTrace,
87+
);
88+
return originalPlatformOnError?.call(error, stackTrace) ?? false;
89+
};
90+
91+
await DatadogSdk.instance.initialize(configuration, TrackingConsent.granted);
7992
```
8093

8194
## Track views
@@ -120,10 +133,13 @@ Automatic network collection is provided by the separate `flashcat_tracking_http
120133

121134
```yaml pubspec.yaml
122135
dependencies:
123-
flashcat_tracking_http_client: ^0.1.0
136+
flashcat_tracking_http_client: ^0.1.1
124137
```
125138

126139
```dart
140+
import 'package:flashcat_flutter_plugin/flashcat_flutter_plugin.dart';
141+
import 'package:flashcat_tracking_http_client/flashcat_tracking_http_client.dart';
142+
127143
final configuration = DatadogConfiguration(
128144
clientToken: '<CLIENT_TOKEN>',
129145
env: 'production',

‎zh/rum/sdk/flutter/advanced-config.mdx‎

Lines changed: 39 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,9 @@ DatadogRumConfiguration(
5959
对 `firstPartyHosts` 命中的域名，SDK 会注入 W3C `traceparent`，实现前端 RUM 与后端 APM 的链路关联。追踪需要配合网络采集（`enableHttpTracking()`）。
6060

6161
```dart
62+
import 'package:flashcat_flutter_plugin/flashcat_flutter_plugin.dart';
63+
import 'package:flashcat_tracking_http_client/flashcat_tracking_http_client.dart';
64+
6265
DatadogConfiguration(
6366
clientToken: '<CLIENT_TOKEN>',
6467
env: 'production',
@@ -78,10 +81,41 @@ DatadogConfiguration(
7881
```dart
7982
DatadogRumConfiguration(
8083
applicationId: '<APPLICATION_ID>',
81-
customEndpoint: 'https://your-ingest.example.com',
84+
customEndpoint: 'https://your-ingest.example.com/api/v2/rum',
8285
);
8386
```
8487

88+
<Warning>
89+
`customEndpoint` 是最终的 RUM intake URL，不是仅包含协议和域名的基础地址。它必须包含 `/api/v2/rum`；如果部署在路径前缀下，还需要保留该前缀，例如 `https://example.com/flashduty/api/v2/rum`。
90+
</Warning>
91+
92+
## WebView 追踪
93+
94+
Flutter 页面内嵌 WebView 时，可通过 `flashcat_webview_tracking` 把 WebView 中的 Browser RUM 事件关联到当前原生 RUM 会话。
95+
96+
```yaml pubspec.yaml
97+
dependencies:
98+
flashcat_flutter_plugin: ^0.1.3
99+
webview_flutter: ^4.0.4
100+
flashcat_webview_tracking: ^0.1.0
101+
```
102+
103+
```dart
104+
import 'package:flashcat_flutter_plugin/flashcat_flutter_plugin.dart';
105+
import 'package:flashcat_webview_tracking/flashcat_webview_tracking.dart';
106+
import 'package:webview_flutter/webview_flutter.dart';
107+
108+
final webViewController = WebViewController()
109+
..setJavaScriptMode(JavaScriptMode.unrestricted)
110+
..trackDatadogEvents(
111+
DatadogSdk.instance,
112+
['myapp.example'],
113+
)
114+
..loadRequest(Uri.parse('https://myapp.example'));
115+
```
116+
117+
传给 `trackDatadogEvents` 的是允许关联的主机名列表。主机名会匹配其子域名，但不支持通配符。WebView 加载的页面必须已经接入 <a href="/zh/rum/sdk/web/sdk-integration">Flashduty Browser SDK</a>；Android 还必须启用 `JavaScriptMode.unrestricted`，否则无法建立关联。
118+
85119
## 符号文件上传
86120

87121
要把崩溃与错误堆栈还原到源码位置，需要上传符号文件。Flutter 应用可能同时包含 Dart 与原生帧：
@@ -119,4 +153,8 @@ FLASHCAT_API_KEY=<API_KEY> flashcat-cli flutter-symbols upload <symbols-dir> \
119153
| `detectLongTasks` | true | 是否采集 long task |
120154
| `longTaskThreshold` | 0.1s | long task 判定阈值 |
121155
| `trackBackgroundEvents` | false | 是否采集应用后台期间的事件 |
156+
| `vitalUpdateFrequency` | `VitalsFrequency.average` | 原生移动端性能指标的采集频率；设为 `null` 关闭 |
157+
| `reportFlutterPerformance` | false | 是否额外采集 Flutter build / raster timing |
158+
| `trackNonFatalAnrs` | 平台默认 | 是否采集非致命 ANR；Android 30+ 默认关闭，Android 29 及以下默认开启 |
159+
| `appHangThreshold` | null | iOS App Hang 的判定阈值（秒）；`null` 表示关闭 |
122160
| `batchSize` / `uploadFrequency` | — | 上报批量大小与频率，权衡实时性与耗电 |

‎zh/rum/sdk/flutter/compatible.mdx‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,9 @@ keywords: ["RUM", "Flutter SDK", "兼容性", "Dart", "iOS", "Android"]
1212
|------|----------|
1313
| SDK 版本 | `flashcat_flutter_plugin` 0.1.3 |
1414
| 目标平台 | **iOS 和 Android**（不支持 Flutter Web / Desktop） |
15-
| Flutter / Dart | Flutter ≥ 3.0，Dart ≥ 3.0 |
15+
| Flutter / Dart | Flutter ≥ 3.27.0，Dart ≥ 3.6.0 |
1616
| iOS | 部署目标 ≥ 12.0 |
17-
| Android | `minSdkVersion` ≥ 21 |
17+
| Android | `minSdkVersion` ≥ 23 |
1818
| RUM 数据源 | 事件固定写入 `source: "flutter"` |
1919
| 实现方式 | 基于原生 iOS / Android SDK 封装的 Flutter plugin |
2020
| 数据上报 | `POST /api/v2/rum` |
@@ -28,7 +28,7 @@ keywords: ["RUM", "Flutter SDK", "兼容性", "Dart", "iOS", "Android"]
2828
| WebView 追踪 | `flashcat_webview_tracking` | 关联 WebView 内的 RUM 数据 |
2929

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

3434
## 支持的自动采集
@@ -41,6 +41,8 @@ Dart 类名以 `Datadog*` 开头，站点枚举为 `FlashcatSite`（`.cn` 默认
4141
| 未处理异常 | 支持 | 使用 `DatadogSdk.runApp` 时自动接管 `FlutterError.onError` / `PlatformDispatcher.onError` |
4242
| 原生崩溃 | 支持 | 需 `nativeCrashReportEnabled: true` |
4343
| 分布式追踪 | 支持 | 对 `firstPartyHosts` 命中的域名注入 W3C `traceparent` |
44+
| 原生移动端性能指标 | 支持 | 默认采集启动耗时（TTID）、刷新率与内存 |
45+
| 卡顿检测 | 支持 | Android 支持 ANR；iOS 设置 `appHangThreshold` 后支持 App Hang |
4446

4547
## 当前限制
4648

@@ -50,7 +52,7 @@ Dart 类名以 `Datadog*` 开头，站点枚举为 `FlashcatSite`（`.cn` 默认
5052
| Logs | 不支持日志上报（`DatadogLoggingConfiguration` 为空操作） |
5153
| Session Replay | 不支持 |
5254
| dio / gql / grpc | 对应拦截包暂不支持 |
53-
| 页面性能指标 | `reportFlutterPerformance` 默认关闭 |
55+
| Flutter 渲染耗时 | `reportFlutterPerformance` 默认关闭；仅控制 Flutter build / raster timing，不影响默认采集的原生移动端性能指标 |
5456
| 最低版本 | 请使用 `flashcat_flutter_plugin` 0.1.3 或更高版本；更低版本 `flutter build apk --release` 会失败于 R8 |
5557

5658
## 符号解析兼容性

0 commit comments

Comments
 (0)