> ## 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. # HarmonyOS SDK 接入 > 在 HarmonyOS NEXT 应用中接入 Flashduty RUM SDK，采集视图、操作、网络、错误和崩溃数据 HarmonyOS SDK 通过 ArkTS HAR 模块提供 RUM、Trace 和 Crash 能力。初始化后，SDK 会把应用中的视图、用户操作、网络请求、错误和崩溃事件上报到 Flashduty RUM，并使用 `source: "harmony"` 标识数据来源。 当前 SDK 模块版本为 `0.4.0`。示例使用 `@flashcatcloud/core`、`@flashcatcloud/rum`、`@flashcatcloud/trace` 和 `@flashcatcloud/crash`。使用 axios 的应用还需要 `@flashcatcloud/axios`。 ## 前提条件 接入前，请先完成以下准备： * 在 Flashduty 控制台创建或选择一个 RUM 应用，并获取 **Application ID** 和 **Client Token** * 确认应用可以访问 `https://browser.flashcat.cloud/api/v2/rum` * 在宿主应用中声明 `ohos.permission.INTERNET` 权限，用于 SDK 批量上报数据 * 使用 HarmonyOS NEXT / Stage 模型工程，并在应用启动早期完成 SDK 初始化 ## 安装 SDK 在应用模块的 `oh-package.json5` 中添加需要的 Flashduty 模块。只接入 RUM 时至少需要 `core` 和 `rum`；需要网络 Trace 或崩溃采集时再添加对应模块。 ```json5 oh-package.json5 theme={null} { dependencies: { "@flashcatcloud/core": "0.4.0", "@flashcatcloud/rum": "0.4.0", "@flashcatcloud/trace": "0.4.0", "@flashcatcloud/crash": "0.4.0", // 仅在应用使用 @ohos/axios 时需要 "@flashcatcloud/axios": "0.4.0" } } ``` ## 初始化 SDK 建议在 `AbilityStage.onCreate` 中初始化 SDK。这样可以在页面、网络请求和异常发生前完成核心实例、RUM、Trace 和 Crash 功能注册。 ```ts MyAbilityStage.ets theme={null} import { AbilityStage } from '@kit.AbilityKit'; import { Flashcat, ConfigurationBuilder, FlashcatSite, TrackingConsent } from '@flashcatcloud/core'; import { FlashcatRum, RumConfigurationBuilder } from '@flashcatcloud/rum'; import { FlashcatTrace, TraceConfigurationBuilder } from '@flashcatcloud/trace'; import { FlashcatCrash, CrashConfigurationBuilder } from '@flashcatcloud/crash'; export default class MyAbilityStage extends AbilityStage { onCreate(): void { const coreConfig = new ConfigurationBuilder('', 'production') .setService('shopping-app') .setVariant('default') .useSite(FlashcatSite.CN) .build(); Flashcat.initialize(this.context, coreConfig, TrackingConsent.GRANTED); FlashcatRum.enable( new RumConfigurationBuilder('') .setSessionSampleRate(100) .setTrackUserInteractions(true) .setTrackNavigation(true) .setTrackNetworkRequests(true) .build() ); FlashcatTrace.enable( new TraceConfigurationBuilder() .setSampleRate(100) .setFirstPartyHosts(['api.example.com']) .build() ); FlashcatCrash.enable(new CrashConfigurationBuilder().build()); } } ``` 请不要在客户端代码中使用服务端密钥。`clientToken` 只用于客户端 RUM 数据上报，`applicationId` 用于归属 RUM 应用数据。 ## 采集页面视图 如果应用使用 ArkUI `router`，请在 UI 页面拿到 `UIContext` 后启动自动视图追踪。该能力只有在 RUM 配置中启用 `setTrackNavigation(true)` 后才会生效。 ```ts pages/Index.ets theme={null} import { FlashcatRum } from '@flashcatcloud/rum'; @Entry @Component struct Index { aboutToAppear(): void { FlashcatRum.startViewTracking(this.getUIContext()); } } ``` 自动视图追踪会监听 `routerPageUpdate`： | 页面状态 | SDK 行为 | | -------------- | --------------------------------------- | | `ON_PAGE_SHOW` | 生成 `startView`，视图名称优先使用路由名称，缺省时使用路径最后一段 | | `ON_PAGE_HIDE` | 生成 `stopView`，关闭当前视图并刷新停留时长 | 如果你的页面没有使用 `router`，可以使用手动 API 管理视图。 ```ts theme={null} import { GlobalRumMonitor } from '@flashcatcloud/rum'; const monitor = GlobalRumMonitor.get(); monitor.startView('checkout', 'Checkout'); monitor.stopView('checkout'); ``` ## 采集用户操作 启用 `setTrackUserInteractions(true)` 后，可以通过 `FlashcatRum.trackTap()` 在统一点击处理器中记录点击事件。该方法不会自动遍历所有组件，你需要在按钮或公共事件封装处显式调用。 ```ts theme={null} import { FlashcatRum } from '@flashcatcloud/rum'; Button('Pay') .onClick(() => { FlashcatRum.trackTap('pay_button'); // 执行业务逻辑 }); ``` 你也可以通过 `GlobalRumMonitor` 手动记录即时操作或带耗时的操作。 ```ts theme={null} import { GlobalRumMonitor, RumActionType } from '@flashcatcloud/rum'; const monitor = GlobalRumMonitor.get(); monitor.addAction(RumActionType.TAP, 'checkout_button'); monitor.startAction(RumActionType.SCROLL, 'product_feed'); monitor.stopAction(RumActionType.SCROLL, 'product_feed'); ``` ## 采集网络请求和 Trace HarmonyOS SDK 按网络库提供三种接入方式。**它们都只有在 RUM 配置中启用 `setTrackNetworkRequests(true)` 后才会生成 resource 事件，该开关默认关闭。** | 应用使用的网络库 | 接入方式 | | ------------------------------------- | -------------------------------------------- | | `@kit.RemoteCommunicationKit` 的 `rcp` | 添加 `FlashcatTrace.interceptor()` | | `@kit.NetworkKit` | 改用 `FlashcatHttp.request()` | | `@ohos/axios` | 调用 `trackAxios(instance)` | | 其他网络栈 | 用 `FlashcatTrace.startTracedResource()` 自行接入 | SDK 不会自动挂钩 `@kit.NetworkKit` 的 `http.createHttp()`。直接用它发起的请求不会被采集，请改用上表中对应的接入方式。 ### rcp 拦截器 如果应用使用 `@kit.RemoteCommunicationKit` 的 `rcp`，在 session 中添加 `FlashcatTrace.interceptor()`。拦截器会注入 W3C `traceparent` 和 `tracestate`，并把请求生命周期发送给 RUM 生成 resource 事件。 ```ts theme={null} import { rcp } from '@kit.RemoteCommunicationKit'; import { FlashcatTrace } from '@flashcatcloud/trace'; const session = rcp.createSession({ interceptors: [FlashcatTrace.interceptor()] }); const response = await session.get('https://api.example.com/orders'); session.close(); ``` ### FlashcatHttp 包装器 如果应用使用 `@kit.NetworkKit`，可以用 `FlashcatHttp.request()` 替代 `http.createHttp().request(...)`。该包装器会在请求完成或失败时生成 RUM resource 或 network error。 ```ts theme={null} import { http } from '@kit.NetworkKit'; import { FlashcatHttp } from '@flashcatcloud/trace'; const response = await FlashcatHttp.request('https://api.example.com/orders', { method: http.RequestMethod.GET }); ``` ### axios `@ohos/axios` 有自己的网络适配层，不经过上面两条路径，需要安装 `@flashcatcloud/axios` 并对每个 axios 实例调用一次 `trackAxios()`。 ```ts theme={null} import axios from '@ohos/axios'; import { trackAxios } from '@flashcatcloud/axios'; const apiClient = axios.create({ baseURL: 'https://api.example.com' }); trackAxios(apiClient); ``` 放在你已经创建 axios 实例的地方即可，通常是统一封装 token 和错误处理的那个文件。 拦截器是**按实例**注册的：`axios` 默认导出和 `axios.create()` 创建的实例互不共享。每个需要上报的实例都要调用一次，且**只调一次**——重复调用会导致同一请求上报两次。 ### 其他网络栈 自研网络库或上面未覆盖的三方库，用 `FlashcatTrace.startTracedResource()` 接入。它登记 resource 并返回要注入的请求头，采集同意与一方域名门控、采样判断、id 编码都在 SDK 内部完成。 ```ts theme={null} import { FlashcatTrace, TracedResource } from '@flashcatcloud/trace'; const traced: TracedResource = FlashcatTrace.startTracedResource(url, 'GET'); // 把 traced.headers 合并进请求后再发送 try { const response = await send(url, traced.headers); FlashcatTrace.stopTracedResource(traced.key, response.status, response.size); } catch (e) { // 拿到了响应（哪怕是 404）应传给 stopTracedResource，保留为对应状态码的 // resource；只有完全没拿到响应的传输失败才用 failTracedResource。 FlashcatTrace.failTracedResource(traced.key, `${e}`); } ``` 务必传入**完整 URL**：相对路径解析不出域名，一方域名检查会因此跳过注入，resource 上也会缺少 host。每次 `startTracedResource` 都要配对一次 `stopTracedResource` 或 `failTracedResource`，包括失败路径，否则 resource 不会关闭。 `traceparent` 和 `tracestate` 只有在追踪同意状态为 `TrackingConsent.GRANTED` 时才会注入，并按 `setFirstPartyHosts()` 限制注入域名；未配置一方域名时会对所有 host 注入。请求已带有 `traceparent` 时，SDK 不会覆盖已有 Trace 上下文。以上对四种接入方式一致生效。 ## 关联用户信息 登录后，你可以设置当前用户。SDK 会把用户字段写入后续 RUM 事件的 `usr` 对象。 ```ts theme={null} import { Flashcat } from '@flashcatcloud/core'; Flashcat.getInstance().setUserInfo({ id: 'user-1001', name: 'Alice', email: 'alice@example.com' }); ``` 当前 `setUserInfo()` 仅用于设置 `id`、`name` 和 `email`。服务端不接收其他用户字段；如需上报业务维度，请使用 RUM 全局属性或单事件属性写入 `context`。 用户退出登录时清除用户信息。 ```ts theme={null} Flashcat.getInstance().clearUserInfo(); ``` ## 验证接入 完成接入后，可以按以下方式验证： 1. 在初始化配置中临时启用 `setVerbose(true)`，通过 HiLog 查看 `Flashcat` 标签日志 2. 打开应用并触发页面切换、按钮点击、网络请求或手动错误 3. 在 Flashduty RUM 应用中筛选 `source:harmony`，确认出现 view、action、resource 或 error 事件 4. 对网络请求检查后端 Trace 是否收到 `traceparent` 5. 触发 Crash 功能后重新启动应用；HarmonyOS 系统会在下一次启动时回放崩溃事件 ## 下一步 配置采样率、隐私同意、事件过滤、Trace 和崩溃符号上传。 了解支持的 HarmonyOS 工程、Kit、权限和当前限制。 查看 SDK 自动和手动采集的事件类型、字段与上报行为。