HarmonyOS 应用接入¶

通过收集 HarmonyOS 应用的指标数据，以可视化方式分析应用性能。

阅读路径¶

首次接入：先看快速开始
完整接入：继续阅读本文
旧版包名迁移：查看旧配置迁移
HAR 包下载：查看 HAR 获取方式
初始化参数：查看 SDK 初始化、RUM 配置、Log 配置、Trace 配置
自定义标签：查看自定义标签与全局上下文
高级场景：查看 WebView 数据监测
数据模型：查看应用数据采集
问题排查：查看故障排查

前置条件¶

注意

若您已开通 RUM Headless 服务，前置条件已自动配置，可直接接入应用。

应用接入¶

进入 用户访问监测 > 新建应用 > HarmonyOS
输入应用名称和应用 ID
选择应用接入方式：
公网 DataWay：直接接收 RUM 数据，无需安装 DataKit 采集器
本地环境部署：满足前置条件后接收 RUM 数据

安装¶

可根据项目接入方式，选择以下任一安装方案。

方案一：通过 ohpm 安装¶

第三方仓库已配置完成时，可直接通过 ohpm 安装：

ohpm install @guancecloud/ft_sdk

ohpm install @guancecloud/ft_sdk_ext #可选
ohpm install @guancecloud/ft_native  #可选

方案二：通过本地 HAR 安装¶

根据 HarmonyOS 官方文档（HAR 包导入指南），请先参考 HAR 获取方式准备安装包，再将 HAR 文件放在项目的 libs 目录下，并在 oh-package.json5 中按需添加 scoped 依赖。

{
  "dependencies": {
    "@guancecloud/ft_sdk": "file:../libs/ft_sdk.har",

    "@guancecloud/ft_sdk_ext": "file:../libs/ft_sdk_ext.har", //可选
    "@guancecloud/ft_native": "file:../libs/ft_native.har"    //可选
  }
}

如果使用 HAR 包依赖，建议在工程根目录的 oh-package.json5 中同时追加 overrides，把模块内部的远程依赖改写到本地 HAR，避免 ft_sdk_ext 继续从远程仓库解析 @guancecloud/ft_sdk：

//root/oh-package.json5
{
  "overrides": {
    "@guancecloud/ft_sdk": "file:./libs/ft_sdk.har"
  }
}

然后执行：

ohpm install

安装完成后，HAR 包会被安装到项目的 oh_modules/ 目录下。使用 scoped 依赖时，目录通常表现为 oh_modules/@guancecloud/ft_sdk、oh_modules/@guancecloud/ft_sdk_ext、oh_modules/@guancecloud/ft_native。

HAR 获取方式¶

新 HAR 获取方式¶

先进入对应 ohpm 页面
再找到目标版本的 dist.tarball
从 dist.tarball 中下载并解出对应 HAR 包

对应地址：

@guancecloud/ft_sdk：https://repo.harmonyos.com/ohpm/@guancecloud/ft_sdk
@guancecloud/ft_sdk_ext：https://repo.harmonyos.com/ohpm/@guancecloud/ft_sdk_ext
@guancecloud/ft_native：https://repo.harmonyos.com/ohpm/@guancecloud/ft_native

请注意：

新方式下载时，请选择与项目接入版本一致的 dist.tarball
ft_sdk_ext 与 ft_sdk 建议保持相同版本
下载后的 HAR 文件仍可放入工程的 libs/ 目录继续按本地 HAR 方式接入

旧 HAR 下载方式¶

下载旧版 ft_sdk.har 文件：下载地址
按需下载 ft_sdk_ext.har 文件：下载地址
按需下载 ft_native.har 文件：下载地址

包说明¶

请根据实际能力按需引入相关包：

ft_sdk.har 为核心包，必须安装；通过第三方仓库安装时对应包名为 @guancecloud/ft_sdk
ft_sdk_ext.har 为扩展包，仅在需要使用基于 @kit.NetworkKit 的 HttpInterceptorChain 自动采集能力时安装，HttpInterceptor 相关能力自 0.1.14-alpha03 起支持，且依赖 HarmonyOS API 22 及以上版本；通过第三方仓库安装时对应包名为 @guancecloud/ft_sdk_ext
ft_native.har 为可选包，仅在需要 Native Crash 等原生能力时安装；通过第三方仓库安装时对应包名为 @guancecloud/ft_native
仅需将实际使用到的 HAR 文件放入 libs/ 目录；如果不存在，请先创建该目录，如果 HAR 文件当前位于工程根目录，请先移动到 libs/ 目录

导入方式¶

可按以下方式导入：

import { FTSDK } from '@guancecloud/ft_sdk/src/main/ets/components/FTSDK';
import { FTSDKConfig, FTRUMConfig, FTLoggerConfig } from '@guancecloud/ft_sdk/src/main/ets/components/Configs';

如需使用基于 HttpInterceptorChain 的 HTTP 自动采集能力，请从 @guancecloud/ft_sdk_ext 导入：

import { applyFTHttpTrack, createFTHttpInterceptorChain } from '@guancecloud/ft_sdk_ext/src/main/ets/components/network/FTHttpAutoTrackExt';

说明：

@guancecloud/ft_sdk：默认接入和 Axios 兼容模式的导入入口
@guancecloud/ft_sdk_ext：HttpInterceptorChain 自动采集相关导入入口
applyFTAxiosTrack 等 Axios 兼容路径仍然从 @guancecloud/ft_sdk 导出

权限说明¶

SDK 已自动包含以下权限声明，无需手动额外配置：

权限名称	用途说明
`ohos.permission.INTERNET`	网络访问权限，用于数据上报和网络请求追踪
`ohos.permission.GET_WIFI_INFO`	获取 WiFi 信息，用于网络类型检测和信号强度采集
`ohos.permission.GET_NETWORK_INFO`	获取网络信息，用于网络状态监控和类型识别

详细配置入口¶

高级场景¶

旧配置迁移¶

本文用于说明 HarmonyOS SDK 从旧版包名迁移到当前 scoped 包名的方式，适用于以下两类项目：

已通过本地 HAR 方式接入，并使用过 ft_sdk.har、ft_sdk_ext.har、ft_native.har
已通过 ohpm 安装，但仍使用旧版未加 scope 的包名配置或导入路径

迁移内容概览¶

ft_sdk -> @guancecloud/ft_sdk
ft_sdk_ext -> @guancecloud/ft_sdk_ext
ft_native -> @guancecloud/ft_native

请注意：

HAR 文件名本身可以继续沿用 ft_sdk.har、ft_sdk_ext.har、ft_native.har
需要调整的是 oh-package.json5 中的依赖名，以及代码中的导入路径
无论是本地 HAR 安装还是通过 ohpm 安装，依赖名和导入路径都应统一迁移到 scoped 包名
如需重新获取本地 HAR 包，可参考 HAR 获取方式

配置文件改动¶

旧写法：

//root/entry/oh-package.json5
{
  "dependencies": {
    "ft_sdk": "file:../libs/ft_sdk.har",
    "ft_sdk_ext": "file:../libs/ft_sdk_ext.har",
    "ft_native": "file:../libs/ft_native.har"
  }
}

新写法：

//root/entry/oh-package.json5
{
  "dependencies": {
    "@guancecloud/ft_sdk": "file:../libs/ft_sdk.har",
    "@guancecloud/ft_sdk_ext": "file:../libs/ft_sdk_ext.har",
    "@guancecloud/ft_native": "file:../libs/ft_native.har"
  }
}

//root/oh-package.json5
{
  "overrides": {
    "@guancecloud/ft_sdk": "file:./libs/ft_sdk.har"
  }
}

如果是通过 ohpm 安装，依赖名同样需要改为 scoped 包名，例如：

ohpm install @guancecloud/ft_sdk
ohpm install @guancecloud/ft_sdk_ext
ohpm install @guancecloud/ft_native

对比说明：

新写法把依赖名从旧的 ft_sdk、ft_sdk_ext、ft_native 改成了 scoped 包名
如果是通过 ohpm 安装，也应使用新的 scoped 包名执行安装命令
overrides 需要配置在工程根目录的 oh-package.json5 中
当项目以本地 HAR 方式接入 ft_sdk_ext.har 时，overrides["@guancecloud/ft_sdk"] 用于把它内部的远程依赖改写到本地 ft_sdk.har
如果只使用 ft_sdk.har 或 ft_native.har，可按实际需要保留对应的 dependencies

代码导入改动¶