鸿蒙应用场景

最近更新时间:2025-07-11 09:28:52

我的收藏

操作场景

本文指导您使用鸿蒙 SDK 的集成与初始化。
注意:
最低支持鸿蒙 SDK 5.0.0(API12),最低支持系统版本 NEXT.0.0.36。

操作步骤

步骤1:SDK 下载

1. 配置鸿蒙三方仓库,执行以下命令。
ohpm config set registry https://ohpm.openharmony.cn/ohpm/
2. 下载安装。
ohpm install qapmsdk@latest

步骤2:加入 QAPMPlugin 插件

1. 在 entry 根目录加入 QAPMPlugin.ts 文件,代码爆红可忽略,可能是 IDE 解析问题,不影响使用。
2. 在 entry 模块的 hvigorfile.ts 中加入以下代码。
// 引入QAPMPlugin依赖
import { QAPMPlugin } from './QAPMPlugin'

...
export default {
...
plugins:[
// 加入插件
QAPMPlugin()
] /* Custom plugin to extend the functionality of Hvigor. */
...
}
...

步骤3:混淆规则配置

鸿蒙端二次混淆 Har 包代码,可能会导致 SDK 运行异常。为了避免 SDK 包跟随业务代码混淆,而导致功能失效,建议业务侧在 hap 工程下的混淆配置文件(obfuscation-rules.txt)中加入以下规则。
-keep
./oh_modules/qapmsdk

步骤4:初始化 SDK

1. 登录 腾讯云可观测平台 控制台,在终端性能监控页面 ,选择 应用管理 > 应用设置 后,获取 AppKey(上报 ID)。



2. 拷贝下面代码,并修改其中部分字段。
import { QAPM } from 'qapmsdk' // 导入QAPM模块 import BuildProfile from 'BuildProfile'; // 引入BuildProfile,该文件编译时生成,可忽略报错

initQAPM(context: common.UIAbilityContext): void { // 初始化SDK QAPM.getInstance() .setContext(context) // 需要传入UIAbilityContext,必须 .setAppKey("your appkey") // 填写你的AppKey,必填,用于区分上报的产品,该值由终端性能监控的产品配置页面获取,可参考前一步骤 .setUserId("userId") // 填写你的用户ID,选填,不填默认值为USER_NOT_SET .setDeviceId("deviceId") // 填写设备ID,必填,应保证该值的唯一性 .setModel("model") // 填写设备类型,选填,不填默认值为USER_NOT_SET,参考deviceInfo.productModel .setLogLevel(QAPM.LogDebugLevel) // 设置日志等级,选填,开发阶段开启Debug,线上请关闭 .setBuildId(BuildProfile.QAPM_UUID) // 设置BuildId,选填,用于拉取被混淆堆栈的mapping (若使用了QAPM符号表上传插件,可以直接使用该变量,否则请遵循UUID格式,自行传入该参数,请注意UUID与一次构建是相互对应关系,为了区分不同的构建版本,建议每次构建更新该参数),该变量会在编译前生成,报错信息可忽略,该设置如不填会影响后续堆栈翻译
.setHost("https://app.rumt-zh.com") // 设置QAPM的外网上报域名,必填
.
setCollectOptionalFields(true)
// 为响应工信部“26号文”要求,提供该设置用于告知SDK是否可以进行可选个人信息的采集,该设置需要最先配置,一旦设置则全局生效。默认可以采集,设置为false则不采集,可能会影响到控制台的搜索、展示等。可选个人信息包括但不限于以下信息:设备制造商、系统、设备型号等,详见《QAPM SDK合规使用指南》 }

// 启动QAPM
startQAPM(): void {
// 启动SDK
QAPM.getInstance()
.start(QAPM.ModeAll) // 开启所有功能,当前功能包含JsCrash、CppCrash、AppFreeze
}
说明:
AppKey 可参考步骤四,在 终端性能监控 > 应用管理 > 应用设置 页面获取。
崩溃与 AppFreeze 分析均采用全量采集上报策略,不做采样处理。

步骤5:接入验证

1. 检测 SDK 接入是否正常。
需要开启 QAPM 的日志等级为 Debug,启动 App,打开 Hilog,过滤 TAG 为 QAPM_,如出现以下日志代表接入成功。

img.png


如出现 launch QAPM error, please check environment! 的错误,请检查 AppKey 或者域名是否设置错误。

img.png


如出现 no monitor turned on! 则可能是抽样未命中,请前往 终端性能监控 > 应用管理 > 白名单管理页面加入用户或者设备白名单,日志中可搜索 user_id 或者 device_id 查看具体值。

img.png


2. 我们在 SDK 中内嵌了一些崩溃测试 API,如下:
调用 QAPM.getInstance().testJsCrash(),触发 Js 崩溃,下次启动时观察日志是否有[plugin::744]的上报。
调用 QAPM.getInstance().testCppCrash(),触发 Cpp 崩溃,下次启动时观察日志是否有[plugin::746]的上报。
调用 QAPM.getInstance().testAppFreeze(),触发 AppFreeze,下次启动时观察日志是否有[plugin::740]的上报。