环境 | 是否支持 | 备注 |
---|---|---|
SaaS-云原生 | 已支持 | 环境已完成适配,platform 以 openHarmony 上报。 |
SaaS-非云原生 | 不支持 | 环境不支持或未完成适配,如果想提早集成,SDK 的 platform 会以 Android 上报。 |
私有化 492 之前版本 |
注意
Finder HarmonyOS SDK 要求最低接入的鸿蒙版本为 API 12 以上。
获取 SDK 与接入方式:您需要联系火山引擎技术支持人员获取。
注意
OAID 是用户弹窗权限,如需采集相关数据时,您需要在应用逻辑中添加 OAID 权限申请代码。
配置在 enrty 下的 module.json5 中:
"requestPermissions": [ { // 网络权限,必要添加 "name": "ohos.permission.INTERNET" }, { // wifi 信息获取,必要添加 "name": "ohos.permission.GET_WIFI_INFO" }, { // 获取网络信息,必要添加 "name": "ohos.permission.GET_NETWORK_INFO" }, { // 资产持久化,建议添加,与 deviceId 生成相关,未声明会导致卸载重装 deviceId 变化 "name": "ohos.permission.STORE_PERSISTENT_DATA" }, { // oaid 权限(可选),建议添加 "name": "ohos.permission.APP_TRACKING_CONSENT", "reason": "$string:your_reason", "usedScene": { "abilities": [], "when": "inuse" } }, ],
鸿蒙将 init 与 start 完全分离。
说明
AbilityStage 相当于 Android 中的 Application。
import { AppLog, InitConfig } from '@volcengine/applog' // 创建新的 AppLog 实例 let appLog = new AppLog() // 鸿蒙 sdk channel 作为可选参数 let config = new InitConfig('yourAppId', 'yourChannel') // 是否打开日志 .setLogEnabled(true) // 设置SaaS-云原生上报地址 .setUri(createByDomain("https://gator.volces.com")) // init sdk 传入配置,init 之后可以 appLog.init(context, config) // 鸿蒙 SDK 需要手动调用 start 才开始采集敏感信息与发送请求 appLog.start()
import { AppLog, InitConfig } from '@volcengine/applog' // 创建新的 AppLog 实例 let appLog = new AppLog() // 鸿蒙 sdk channel 作为可选参数 let config = new InitConfig('yourAppId', 'yourChannel') // 是否打开日志 .setLogEnabled(true) // init sdk 传入配置,init 之后可以 appLog.init(context, config) // 鸿蒙 SDK 需要手动调用 start 才开始采集敏感信息与发送请求 appLog.start()
import { AppLog, InitConfig } from '@volcengine/applog' // 创建新的 AppLog 实例 let appLog = new AppLog() // 鸿蒙 sdk channel 作为可选参数 let config = new InitConfig('yourAppId', 'yourChannel') // 是否打开日志 .setLogEnabled(true) // 设置私有化部署数据上送地址 .setUri(createByDomain("your_REPORT_URL")) // init sdk 传入配置,init 之后可以 appLog.init(context, config) // 鸿蒙 SDK 需要手动调用 start 才开始采集敏感信息与发送请求 appLog.start()
当前版本每个实例都是新创建出来的,所以创建新的 AppLog 对应传入不同的应用实例即可。
import { AppLog, InitConfig } from '@volcengine/applog' // 创建新的 AppLog 实例 let appLog1 = new AppLog() // init sdk 传入配置,init 之后可以 appLog1.init(context, new InitConfig('yourAppId1', 'yourChannel') // 是否打开日志 .setLogEnabled(true)) // 鸿蒙 SDK 需要手动调用 start 才开始采集敏感信息与发送请求 appLog1.start() // 创建新的 AppLog 实例 let appLog2 = new AppLog() // init sdk 传入配置,init 之后可以 appLog2.init(context, new InitConfig('yourAppId2', 'yourChannel') // 是否打开日志 .setLogEnabled(true)) // 鸿蒙 SDK 需要手动调用 start 才开始采集敏感信息与发送请求 appLog2.start()
说明
鸿蒙 Oaid 为用户授权权限,需要应用侧主动申请权限,如果申请权限且用户同意,SDK 才能采集到 Oaid,也支持在用户同意的情况下关闭 Oaid 采集。
设备的 OAID 信息采集默认开启,如需关闭:
let config = new InitConfig('yourAppId', 'yourChannel') .setOaidEnabled(false)
设备的运营商信息默认采集,如需关闭:
let config = new InitConfig('yourAppId', 'yourChannel') .setOperatorInfoEnabled(false)
如需使用实时埋点检测,请配置 Scheme,否则可跳过此步骤。
该方式无需配置唤醒协议,
集成 Devtools 后点开,控制台 -> 扫一扫 按照流程操作即可。
现阶段鸿蒙系统浏览器已支持扫码跳转。
「应用列表」-> 接入应用的「详情」->「URL Scheme」中可查看您的 scheme,一般为rangersapplog.xxxxx
的形式。
// 在 entry 模块下的主 Ability 中配置 uris: "uris": [ { // rangersapplog.xxx 请替换为官方文档中展示的 scheme "scheme": "rangersapplog.xxx", "host": "rangersapplog", "path": "picker" } ] // 示例: "abilities": [ { "name": "EntryAbility", "srcEntry": "./ets/entryability/EntryAbility.ets", "description": "$string:EntryAbility_desc", "icon": "$media:icon", "label": "$string:EntryAbility_label", "startWindowIcon": "$media:startIcon", "startWindowBackground": "$color:start_window_background", "exported": true, "skills": [ { // 也需要配置 "actions": [ "ohos.want.action.viewData" ], "uris": [ { // rangersapplog.xxx 请替换为官方文档中展示的 scheme "scheme": "rangersapplog.xxx", "host": "rangersapplog", "path": "picker" } ] }, ] } ]
import { InitConfig } from '@volcengine/applog' // 在配置跳转协议的 Ability 中添加以下代码: // 在示例中的 EntryAbility 中添加: // onNewWant 是在启动后又有启动调用回调 onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void { // 传入协议 uri 即可 appLog.simulate()?.start(want.uri) } // 如果还没有启动 App 就想要扫码实时埋点 onCreate(want: Want, _: AbilityConstant.LaunchParam): void { // 注意,需要在 SDK init 之后调用才可以 // 传入协议 uri 即可 appLog.simulate()?.start(want.uri) }
说明
SDK 在 init 之前不接受任何方法调用,想要调用 SDK 内部方法,需要先进行 init,且 init 方法已做合规处理,init 不会自动采集敏感信息与发送请求。
可以考虑在 AbilityStage 的 onCreate 中 sdk init,在隐私同意后进行 sdk start。
appLog.init(context, config)
说明
请不要在 init 之前调用 start,调用 start 后,SDK 真正开始做敏感信息采集与请求上报。
appLog.start()
import { InitConfig } from '@volcengine/applog' let config = new InitConfig('yourAppId', 'yourChannel') // 开启 SDK 日志 .setLogEnabled(true)
import { InitConfig } from '@volcengine/applog' let config = new InitConfig('yourAppId', 'yourChannel') // 也需要先开启 SDK 日志 .setLogEnabled(true) // 实现日志接管方法 .setLogger({ log: (_: hilog.LogLevel, __: string, msg: string, err?: Error) => { hilog.debug(0x0100, 'AppLogH_test', `${msg} ${err ? JSON.stringify(err) : ""}`) } })
import { InitConfig } from '@volcengine/applog' import { createByDomain } from '@volcengine/applog/src/main/ets/core/base/url/UriConfig' let config = new InitConfig('yourAppId', 'yourChannel') .setUri(createByDomain("your_REPORT_URL"))
SDK 默认开启加密,且内置的默认加密方式与 Android 一致。
如果需要修改 SDK 加密方式,建议在 init 和 start 之间插入对应代码,这样可以确保启动后请求应用加密方式。
无需额外设置。
import { AppLog, InitConfig } from '@volcengine/applog' let appLog = new AppLog() let config = new InitConfig('yourAppId', 'yourChannel') appLog.init(context, config) // 默认无需添加,默认开启加密 appLog.encrypt()?.enablePlugin() // 切换至默认加密方式,建议在 start 之前调用,因为 start 就开始请求 appLog.encrypt()?.useDefaultEncrypt() appLog.start()
注意
该加密方式目前仅私有化版本支持。
import { AppLog, InitConfig } from '@volcengine/applog' let appLog = new AppLog() let config = new InitConfig('yourAppId', 'yourChannel') appLog.init(context, config) // 默认无需添加,默认开启加密 appLog.encrypt()?.enablePlugin() // 切换至国密 SM2 非对称加密,需要手动传入公钥 appLog.encrypt()?.useSm2Encrypt("your_public_key") appLog.start()
对于调试阶段,可以关闭 SDK 加密,方便抓包查看数据是否正常。
import { AppLog, InitConfig } from '@volcengine/applog' let appLog = new AppLog() let config = new InitConfig('yourAppId', 'yourChannel') appLog.init(context, config) // 关闭加密 appLog.encrypt()?.disablePlugin() appLog.start()
如果您的应用同时集成 Web/JS SDK 以及 Harmony SDK,默认情况下,所有 H5 事件会通过 Web/JS SDK 上报,如果您希望 H5 事件由 Harmony SDK 接管上报,可以使用打通内嵌 H5 功能,此时 H5 页上产生的事件将通过 Harmony SDK 上报,而不在 Web/JS SDK 上报,这种接管上报场景下会复用 Harmony 端设置的user_unique_id
和公共属性,但是也支持打通时 web 侧设置 / 更新端上的 uuid / 公共属性,请在打通时注意采用哪边数据,如果完全以端上为准可以去掉 web sdk 侧的 uuid / 公共属性操作。
注意
打通功能需要 Web/JS SDK 与 Harmony SDK 同时集成并彼此配合,且当前版本 Web/JS SDK 打通后默认屏蔽 H5 全埋点功能,因为此时上报都由 Harmony SDK 接管,如果还想采集 H5 全埋点,需要查看 5.7 小节:原生端采集 H5 全埋点 。 Web/JS SDK 集成请参考《Web/JS SDK 集成》 以及 3.4 小节。
import { AppLog, InitConfig } from '@volcengine/applog' let appLog = new AppLog() let config = new InitConfig('yourAppId', 'yourChannel') appLog.init(context, config) // ... appLog.start() export { appLog }
import web_webview from '@ohos.web.webview' import { appLog } from './applog' @Component export struct Webview { controller: web_webview.WebviewController = new web_webview.WebviewController() bridgeProxyInfo = appLog.bridge()!.injectJsBridgeByJsProxy() build() { Web({ src: $rawfile('webview.html'), controller: this.controller }) .javaScriptAccess(true) .javaScriptProxy({ object: this.bridgeProxyInfo.object, name: this.bridgeProxyInfo.name, methodList: this.bridgeProxyInfo.methodList, controller: this.controller, }) } }
当前 SDK 支持通过 errorManager 采集 JS crash,SDK 内部默认关闭。
let appLog = new AppLog() let config = new InitConfig('yourAppId', 'yourChannel') appLog.init(context, config) // 主动开启 JS Crash 采集 appLog.crash()?.enablePlugin() appLog.start()
AB 实验默认关闭(与 Android 一致),如果需要使用 AB 实验需要先手动开启。
import { AppLog, InitConfig } from '@volcengine/applog' let appLog = new AppLog() let config = new InitConfig('yourAppId', 'yourChannel') appLog.init(context, config) // 开启 AB 实验,建议在 init 与 start 之间调用 appLog.abTest()?.enablePlugin() appLog.start()
appLog.abTest()?.getAllAbTestConfigs()
appLog.abTest()?.getAbConfig("ab_key", defaultValue)
appLog.abTest()?.getAbSdkVersion()
appLog.topicReceiver()?.on(Topic.ABTestConfigReady, (abTestConfig) => { hilog.info(0x0000, 'AppLogH', `AppLog abtest config ready: ${JSON.stringify(abTestConfig)}`) }) abTestConfig 格式: 就是具体的实验配置 { "ab": { "val": "访问页面 A", "vid": "1" }, "ba": { "val": "对照版", "vid": "2" }, "tt": { "val": true, "vid": "3" } }
appLog.topicReceiver()?.on(Topic.ABTestVidChanged, (vids) => { hilog.info(0x0000, 'AppLogH', `AppLog abtest vids: ${JSON.stringify(vids)}`) }) vids 格式: { // 最新曝光的 vid "new_vid":"1", // 已曝光的 vid 集合(包含最新的) "vids":"1" }
说明
SDK 提供了 DevTools 工具,支持在开发时方便观察 SDK 的一些运行信息。
初始化 SDK 和注册 DevTools 插件(初始化方式新老版本一致)
import { AppLog, InitConfig } from '@volcengine/applog' import { DevTools } from '@volcengine/applog_devtools' let appLog = new AppLog() let config = new InitConfig('yourAppId', 'yourChannel') appLog.init(context, config) // 注册 DevTools 插件 DevTools.applyDevTools(appLog) appLog.start() export { appLog }
说明
新版使用方式:1.2.0 及以上版本
新版本 Devtools 实现了和 Android 一样的全局悬浮能力(使用子窗口功能),所以无需额外挂载,直接使用即可。
如果是老版本升级上来,需要移除之前的使用方式。
新版版监听 onWindowStageActive,如果 SDK 初始化比较晚可能错过监听,前后台切换一下即可,显示出来,正常情况无需手动调用显示。
// 如果需要手动打开 可以手动调用: Devtools.show(windowStage: window.WindowStage) // 支持手动关闭: Devtools.close()
说明
老版本 Devtools 并非像 Android 那样的全局悬浮窗,需要在哪个页面使用,需要在对应页面挂载。
在需要的页面挂载 DevTools 组件,推荐在根组件上挂载
import DevToolsPage from '@volcengine/applog_devtools' @Entry @Component struct Index { // ... build() { Column() { // ... DevToolsPage() } } }
默认是一分钟上报一次,但是没有具体上报条数,SDK 策略为新的按体积查询事件的上报策略(Android / iOS 为按条数查询), 每次上报查询 1M 左右数据进行上报,不再以 200 条为准(可以尽量多的上报)。