• 支持的环境：

• SDK版本说明：当前 HarmonyOS SDK 为 Bate 版，鸿蒙系统暂无正式版推出，本 SDK 基于鸿蒙 Developer Beta 版本开发，后续会随华为系统的更新与正式版发布持续迭代，当前功能适配非完整版本。
  • 当前支持最新版的 HarmonyOS SDK 已支持的功能包括：
    • 自定义埋点 / 请求加密（默认加密 / 国密 sm2）/ 用户标识与用户属性 / AB 分流实验 / 事件黑名单 / web 打通 / 崩溃采集（JS 层）/ 实时埋点验证 / custom header 设置
    • Devtools 调试工具
      • 查看事件信息 / 查看网络请求 / 查看接入状态 / 调试日志 / 配置信息模块 / 内置扫一扫功能
  • 暂不支持多线程 / 多进程，鸿蒙系统比较特殊，采取线程间进程隔离，需额外适配方案。

获取SDK

获取 HarmonyOS SDK 与 Devtools SDK 离线包：您需要联系火山引擎技术支持人员获取 HarmonyOS SDK 包、Devetools SDK 包。

引入SDK和调试工具

先在项目根目录添加 applogx 目录（可以放到任意目录，后续再 entry 模块中配置正确即可），并在该目录下添加两个SDK：

在 entry 中添加依赖

最后在 enrty 节点的 oh-package.json5 文件中添加：

"dependencies": {
  // sdk 强依赖 pako 用于 gzip 压缩
  "pako": "^2.1.0",
  "@volcengine/applog": "file:../applogx/applogx.har",
  "@volcengine/applog_devtools": "file:../applogx/applogx_devtools.har"
}

权限声明

"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 完全分离。

• init 之后才可以调用 SDK 的各种方法，SDK 不支持 init 之前进行埋点，但 init 之后就可以开始埋点落库了。
• start 之后才开始采集诸如 oaid 等敏感 header 信息，并且此时才进行数据请求。
• 如果创建了 AbilityStage，可以将 init 放在 AbilityStage 的 oncreate 中，可以在这里初始化 SDK，然后在隐私弹窗后再调用 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)
  // 设置上报地址
  .setUri(createByDomain("https://gator.volces.com"))
// 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()

SDK init

appLog.init(context, config)

SDK start

appLog.start()

更新 / 移除 custom header

// 添加新的 custom header
appLog.setHeaderInfo("key", "value")

// 移除已有的 cutsom header
appLog.removeHeaderInfo("key")

运行时更新 UriConfig

import { createByDomain } from '@volcengine/applog/src/main/ets/core/base/url/UriConfig'

appLog.setUriRuntime(createByDomain("your_REPORT_URL"))

用户信息模块

// 获取用户信息模块
appLog.user()

设置 UserUniqueID

// 单独设置 UUID
appLog.user()?.setUserUniqueID("your_uuid")

// 设置 UUID + UUIDType
appLog.user()?.setUserUniqueID("your_uuid", "your_uuid_type")

获取 UserUniqueID

// 获取 UUID
appLog.user()?.getUserUniqueID()

加密模块

// 获取加密模块
appLog.encrypt()

订阅 SDK 特定消息

// 示例：监听 SDK init 消息
appLog.topicReceiver()?.stickyOn(Topic.SDKInit, () => {
  hilog.info(0x0000, 'AppLogH', "AppLog SDK init call")
  // 如果订阅后涉及到耗时操作建议异步处理
})

订阅

可用于重复订阅。

appLog.topicReceiver()?.on(Topic.XXX, () => {
  hilog.info(0x0000, 'AppLogH', "AppLog xxx receive")
  // 如果订阅后涉及到耗时操作建议异步处理
})

单次订阅

可用于单次订阅。

appLog.topicReceiver()?.once(Topic.XXX, () => {
  hilog.info(0x0000, 'AppLogH', "AppLog xxx receive once")
  // 如果订阅后涉及到耗时操作建议异步处理
})

粘性订阅

可用于粘性重复订阅，粘性订阅主要用于避免因为注册订阅监听较晚导致错过某些消息。

appLog.topicReceiver()?.stickyOn(Topic.XXX, () => {
  hilog.info(0x0000, 'AppLogH', "AppLog xxx sticky receive")
  // 如果订阅后涉及到耗时操作建议异步处理
})

粘性单次订阅

可用于粘性单次订阅，粘性订阅主要用于避免因为注册订阅监听较晚导致错过某些消息。

appLog.topicReceiver()?.stickyOnce(Topic.XXX, () => {
  hilog.info(0x0000, 'AppLogH', "AppLog xxx sticky receive once")
  // 如果订阅后涉及到耗时操作建议异步处理
})

取消订阅

取消某条消息订阅。

appLog.topicReceiver()?.off(Topic.XXX)

订阅 Did Ready

appLog.topicReceiver()?.on(Topic.DidReady, (didInfo) => {
  setTimeout(() => {
    hilog.info(0x0000, 'AppLogH', `AppLog did ready:  ${didInfo["bd_did"]}`)
  })
})

didInfo 格式：
// device_info_from 表示该信息来自本地还是服务端请求返回
// device_info_from: did_from_remote 表示数据来自服务端返回
// device_info_from: did_from_local 表示数据来自本地缓存
{
    "bd_did": "xxxx",
    "install_id": xxxx,
    "ssid": "xxxxx",
    "device_info_from": "did_from_remote"
}

// 使用示例：
import { InitConfig } from '@volcengine/applog'

let config = new InitConfig('yourAppId', 'yourChannel')
  .setLogEnabled(true)

设置 Channel

鸿蒙 SDK channel 为可选参数，并不强制设置。

import { InitConfig } from '@volcengine/applog'

let config = new InitConfig('yourAppId', "yourChannel")

开启 SDK 日志

SDK 内部数据输出日志

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"))

敏感信息采集

关闭 Oaid 采集

设备的 OAID 信息采集默认开启，如需关闭：

let config = new InitConfig('yourAppId', 'yourChannel')
  .setOaidEnabled(false)

关闭运营商信息采集

设备的运营商信息默认采集，如需关闭：

let config = new InitConfig('yourAppId', 'yourChannel')
  .setOperatorInfoEnabled(false)

用户自定义事件

// 不带自定义属性的事件
appLog.event("test")

// 带自定义属性的事件
appLog.event("test1", {
  "key": "value"
})

火山实时埋点验证

用来做埋点属性验证，实际上报结果请以 Finder 数据查询为准。可以考虑优先使用 devtools 内置的扫一扫做埋点验证。

方式一 使用 Devtools 内置扫一扫：

该方式无需配置唤醒协议，
集成 Devtools 后点开，控制台 -> 扫一扫 按照流程操作即可。

方式二 传统扫码跳转：

现阶段（24.8 beta5 版本）鸿蒙系统浏览器已支持扫码跳转。

配置跳转协议（方式二添加）

// 在 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 默认开启加密，且内置的默认加密方式与 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()

国密 SM2

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 加密

对于调试阶段，可以关闭 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()

ProfileSet

appLog.profile()?.set({
  "set1": "value",
  "set2": "value"
})

ProfileSetOnce

appLog.profile()?.setOnce({
  "setOnce": "value"
})

ProfileIncrement

appLog.profile()?.setOnce({
  "increment": 1
})

ProfileAppend

appLog.profile()?.append({
  "appendStr": "1",
  "appendNum": 1
})

ProfileUnset

appLog.profile()?.unset("set2")

AB 实验默认关闭（与 Android 一致），如果需要使用 AB 实验需要先手动开启。

开启 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()

获取 AB 实验服务端配置

appLog.abTest()?.getAllAbTestConfigs()

进行 AB 实验曝光

appLog.abTest()?.getAbConfig("ab_key", defaultValue)

获取已曝光实验 Vid 列表

appLog.abTest()?.getAbSdkVersion()

订阅 AB 服务端分流配置获取

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"
    }
}

订阅新曝光 Vid 记录

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 提供了 bridge 插件，方便注入到 Web 组件中，让 JS SDK 的事情可以通过 App 侧进行上报。

• 初始化SDK

import { AppLog, InitConfig } from '@volcengine/applog'

let appLog = new AppLog()
let config = new InitConfig('yourAppId', 'yourChannel')
appLog.init(context, config)
// ...
appLog.start()

export {
    appLog
}

• 在Web组件上使用

方式一：使用 javaScriptProxy 注入

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()

Devtools 集成

初始化 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.show(windowStage: window.WindowStage)

//  支持手动关闭：
Devtools.close()

老版使用方式：1.0.0 / 1.1.0 版本

在需要的页面挂载 DevTools 组件，推荐在根组件上挂载

import DevToolsPage from '@volcengine/applog_devtools'

@Entry
@Component
struct Index {
  // ...
  
  build() {
    Column() {
      // ...
      
      DevToolsPage()
    }
  }
}

Devtools FAQ

ArkTS:ERROR Failed to resolve OhmUrl.

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 完整依赖。