You need to enable JavaScript to run this app.
导航
增长分析 DataFinder
  • 文档首页
    • /增长分析 DataFinder/开发者指南/数据接入/客户端SDK/HarmonyOS Next SDK/参考：HarmonyOS Next SDK 集成 FAQ
参考：HarmonyOS Next SDK 集成 FAQ
最近更新时间：2025.06.30 18:49:45首次发布时间：2025.06.30 18:49:45
我的收藏
有用
有用
无用
无用

支持环境

答：且对应环境需要集成特定 SDK，否则会有问题。

环境

是否支持

备注

火山云 / 私有化 4.9.2 及之后版本

已支持

环境已完成适配，platform 以 openHarmony 上报。
如果私有化升级到 4.9.2 的话需要重新替换 sdk 才能把 platform 改成鸿蒙

字节云

不支持

环境未完成适配，如果想提早集成，SDK 的 platform 会以 Android 上报。

私有化 4.9.2 之前版本

不支持

鸿蒙 SDK 的集成的最低所需版本

答：API12（Developer Beta3）以上

是否支持 AB？

答：支持

文档中的 Pako 是用来干啥的？

答：鸿蒙官方推荐的 gzip 工具，目前系统没有现成的 gzip 接口，推荐使用 pako 依赖。SDK 内部有请求加密，加密伴随着 gzip，所以是必要依赖

我们公司内部搭建了私有仓库，想要个 pako 的 har 可以提供吗？

答：可以，找我要就行，在类比 pako 是需要在线依赖的，如果客户环境无法在线依赖，可以提供离线包。

这个问题是啥意思：ERROR: ArkTS:ERROR Failed to resolve OhmUrl.

Error Message: Failed to get a resolved OhmUrl for "pako" imported by "/Users/bytedance/Downloads/package/HarmonyAppLogTest/oh_modules/.ohpm/@volcengine+applog@dtz2fnlu+kogyshzrapysfd0wcm=/oh_modules/@volcengine/applog/src/main/ets/core/network/interceptor/CompressAndEncryptInterceptor.js".
答：pako 没有依赖。

Devtools 为什么不能和 Android 那样简单使用？

答：已支持子窗口模式的全局悬浮窗

都支持哪些功能

答：以对外文档为主，文档上写的就都支持。

  • 自定义埋点 / 请求加密（默认加密 / 国密 sm2）/ 用户标识与用户属性 / AB 分流实验 / 事件黑名单 / web 打通 / 崩溃采集（JS 层）/ 实时埋点验证 / custom header 设置等
  • Devtools 调试工具
    • 查看事件信息 / 查看网络请求 / 查看接入状态 / 调试日志 / 配置信息模块 / 内置扫一扫等功能

全埋点 / 曝光什么时候支持

答：1.2.0 以上版本已支持，但是产品定位为付费版内容。

鸿蒙 SDK 为什么没有 SSID 获取方式？

答：鸿蒙 SDK 考虑逐步去掉端上维护 SSID 逻辑，端上后续也没有 SSID，事件的 SSID 上报由数据流补充。
补充：1.3.1 提供通过当前 uuid 请求 ssid 逻辑，请求 SSID

鸿蒙上报策略是什么?

答：默认也是一分钟上报一次，但是没有具体上报条数，SDK 策略为新的按体积查询事件的上报策略（Android / iOS 为按条数查询）， 每次上报查询 1M 左右数据进行上报，不再以 200 条为准（可以尽量多的上报）。

是否提供了 OAID / 运营商信息的采集开关?

答：1.3.0 提供了对应开关。

是否支持多线程 / 多进程?

答：暂不支持多线程 / 多进程，鸿蒙系统比较特殊，采取线程间进程隔离，需额外适配方案。

集成 devtool 报错

1 ERROR: ArkTS:ERROR Failed to resolve OhmUrl.
Error Message: Failed to get a resolved OhmUrl for "@volcengine/applog" imported by "/Users/bytedance/DevecostudioProjects/SDK50/oh_modules/.ohpm/@volcengine+applog_devtools@7hba3+yrkmv76lfmmoxyslxamstpksemeh++r+9qtz8=/oh_modules/@volcengine/applog_devtools/src/main/ets/plugin/DevTools.js".
情况一：AppLog 引入名称错误
答：遇到该问题，主要原因是依赖组件时，前面组件名字其实是可以任意写的，但是 applog 和 devtools 之间的协议是特定的，就是写成 @volcengine/applog 的方式引入，请检测 AppLog 依赖时的名称是否写对了，请严格按照文档集成。
// 严格按照该名称引入 AppLog
"@volcengine/applog": "file:../applogx/applogx.har",
"@volcengine/applog_devtools": "file:../applogx/applogx_devtools.har"
情况二：子模块中依赖 AppLog 同时子模块也被其他模块依赖后发现报错
答：由于鸿蒙不支持依赖传递，所以你在子模块中依赖的 SDK，无法被其他模块引用，请在对应模块添加依赖。
实例：子模块依赖 applog，entry 依赖子模块，请也在 entry 模块中添加 applog 完整依赖。
Image

Cannot read property eventHub of undefined

答：是初始化 SDK 的 context 不对。

集成 SDK 后卡顿

答：可以去掉 Devtools 再试试 1.1.0-beta2 ～1.1.0-beta3 会有该问题，请后续升级到 1.3.0-xxx 的版本。

找不到 @volcengine/applog

答：可能是老客户升级上来导致的，之前文档说明导入是 @ohos/applog，需要把导入名称调整下，参考最新文档。
Image

仅升级 Devtools 提示找不到 BavEvent?

答：由于适配了新功能，需要将 AppLog 与 devtools 都升级到 1.2.0-xx 版本，仅升级 Devtools 不行。

import { DevTools } from '@volcengine/applog_devtools' 报错找不到

答：1.2.0 的新版本做了方案调整，无需手动在每个页面额外挂载，改成了 Android 的全局弹窗模式，所以去掉了老的集成方案，基本上新方案不用额外挂载并且打开 App 就能有悬浮窗，如果一进入没有看到切换到后台再进来就可以看到了（监听窗口活跃打开 Devtools 所以一开始进入没看到可能是初始化时机比较晚）。

针对客户已有 Bridge 的情况文档中打通的方案一无法满足客户时如何处理？

答：原本最早文档是有两个方案的，另一个方案支持额外注入 Bridge，但是方案实施上可能会依赖客户自己决定。
方式一是华为官方提供的，能把特定一个对象注入进去，但也支持注入多个对象，也就是原本的方案二， registerJavaScriptProxy 确实可以注入多个，我们也提供了 API，但是给客户自己找时机注入了，我们目前并没有合适的时机推荐了。
Image
Image
官方介绍如果想要用第二种注入多个对象的方式就需要触发 refresh 才能生效，之前方案二在老版本验证是可行的，5.0 之后 refresh 后导致再次回调 onPageBegin 就会陷入死循环，
Image
官方自己的 demo 是通过按钮注入 按钮刷新，所以这个时机给客户自己控制了，不要放在 onPageBegin 里调用我们的 registerJsBridge
Image
所以结论是针对客户本身没有 Bridge 的推荐方式一直接注入即可，如果客户有自己的 Bridge 就需要自己找合适的时机做注入了，我们目前没有合适的时机推荐，我们也询问过华为的人，也没有合适的时机，如果实在没有合适的时机，就只能参考官网文档了：https://developer.huawei.com/consumer/cn/doc/harmonyos-references-V5/js-apis-webview-V5#registerjavascriptproxy
方案二下掉的原因： 原本方案二为啥下掉上面也解释了 注入多个对象的 registerJavaScriptProxy 一定要 refresh 才能生效，refresh 会导致 onPageBegin 重新回调，从而陷入死循环，但是目前也没有其他合适的已有的生命周期合适处理。
比较 low 的方案（通过标识位判断是否加载过）：
可能存在的副作用：当然了 如果实在是客户也不好处理 我只能推荐这个比较 low 的方案了 但是可能会由于 refresh 导致 web 的 pageview 多采集一次，之前的版本有遇到过，新版本好像又没有了
Image

x86 模拟器是否支持

答：25.3 月已支持，对应版本 1.3.1。

客户在集成 Devtools 的时候自己的弹窗显示出错，弹窗内容显示到 Devtools 中

答：可能是客户获取 window 对象出问题了，lastWindow 不区分主窗口子窗口，建议把 window.getLastWindow 改为 context.windowStage.getMainWindowSync()。

SDK 打包版本

答：只记录了最新的两个包

  • 1.2.0 基于 810 打包，由于 9.30 发布，所以基于 810，因为 900 是 10.8 发布的
  • 1.3.0 基于 910 打包
  • 1.1.0 基于 910 打包
  • 1.3.1 基于 5.0.9.300 打包

升级到 1.3.0 提示报错：ERROR: Bytecode HARs: [@volcengine/applog, @volcengine/applog_devtools, @volcengine/applog] not supported when useNormalizedOHMUrl is not true.* Try the following:> Please check useNormalizedOHMUrl in the project-level build-profile.json5 file.

Image
答：在根目录添加这个配置，并 compatibleSdkVersion 调整至 12。
Image
添加该配置的原因（https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/ide-hvigor-build-har-V5#section179161312181613）：

  1. 编译后的产物提前编译好了字节码，所以能提升应用侧编译效率
  2. Ide 800 后的工程，默认开启，是华为这边的趋势

Image

是否支持元服务

答：25.3 月后已支持

1.3.0 版本离线集成 pako 发现报错

答：添加下 overrides 配置，强制指定为离线版或者特定版本（比如民生的私仓版本）。
Image

事件上报都接收什么类型？

答：事件自定义属性为 EventRecord 类型，为自定义类型，不支持其他类型，因为 SDK 需要做类型校验，避免接收到不能解析的类型，所以 SDK 限制了接收类型。
1.1.0 EventRecord = Record<string, number | string | boolean>
1.2.0 EventRecord = Record<string, number | string | boolean | string[]>

应用内容错误展示到 Devtools 该如何解决？

答：

方案一：

查看一下具体内容挂载到哪个 Window 上了，比如系统 window.getLastWindow 不区分子窗口主窗口，如果需要正确将内容挂载到主窗口建议直接获取主窗口。
Image
如果需要挂载到某个特定子窗口，建议通过窗口名称获取。
Image

方案二：

如果方案一不好解决可以升级到 130-rc1 版本，关闭子窗口模式，使用页面挂载方式。

为什么升级了 SDK 发现没变化？需要的功能怎么没看到？

答：请 sync 一下。

DevEco Studio 5.0.1 Release 5.0.5.300 集成 devtools 启动崩溃报错

Image
答：新版本编译产物变了，需要提供基于新版本编译的产物。

新版 IDE 即成 Devtools 报错

Image
答：记得 override applog，并且 override 要写到根结点的 oh-package.json5。

更多FAQ

更多关于数据接入的FAQ请参见SDK集成&数据上报。