操作场景
本文指导您使用鸿蒙 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合规使用指南》 }// 启动QAPMstartQAPM(): void {// 启动SDKQAPM.getInstance().start(QAPM.ModeAll) // 开启所有功能,当前功能包含JsCrash、CppCrash、AppFreeze}
步骤5:接入验证
1. 检测 SDK 接入是否正常。
需要开启 QAPM 的日志等级为 Debug,启动 App,打开 Hilog,过滤 TAG 为 QAPM_,如出现以下日志代表接入成功。


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

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

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