• 支持的环境：

  环境	是否支持	备注
  SaaS-云原生 私有化 492 版本	已支持	环境已完成适配，platform 以 openHarmony 上报。 如果是老的私有化版本升级上来的，需要联系火山引擎技术支持人员获取 HarmonyOS Next SDK 新版适配包。
  SaaS-非云原生、 私有化 492 之前版本	不支持	环境不支持或未完成适配，如果想提早集成，SDK 的 platform 会以 Android 上报。

• SDK版本说明：
  当前 HarmonyOS Next SDK 为 Bate / RC 版，鸿蒙系统目前已正式版推出，本 SDK 基于鸿蒙 HarmonyOS 5.0.0 Release 版本编译打包，后续会随华为系统的更新持续迭代，当前功能适配非完整版本。

  • 当前支持最新版的 HarmonyOS Next SDK 已支持的功能包括：
    • 自定义埋点 / 请求加密（默认加密 / 国密 sm2）/ 用户标识与用户属性 / AB 分流实验 / 事件黑名单 / web 打通 / 崩溃采集（JS 层）/ 实时埋点验证 / custom header 设置 / 全埋点（beta）/ 组件曝光 / 多 ID 口径
    • Devtools 调试工具
      • 查看事件信息 / 查看网络请求 / 查看接入状态 / 配置信息模块 / 内置扫一扫功能
  • SDK发布日志详情请参见SDK更新日志。
  • 暂不支持多线程 / 多进程，鸿蒙系统比较特殊，采取线程间进程隔离，需额外适配方案。

获取 SDK 与接入方式 #

SDK 下载与选择 #

接入 #

在项目中添加依赖添加：

// 如 entry 或者 model，其实可以考虑添加到根目录中（这样项目中所有模块都可以访问）
"dependencies": {
  // sdk 强依赖 用于 gzip 压缩
  "pako": "^2.1.0",
  // 引入 AppLog 组件时，请确保组件名称是这个
  "@volcengine/applog": "file:../applogx/applogx.har",
  // 调试工具（可选）
  "@volcengine/applog_devtools": "file:../applogx/applogx_devtools.har"
}

// overrides 仅在根结点的 oh-package.json5 有效
"overrides": {
  // 重写
  "@volcengine/applog": "file:../applogx/applogx.har",
}

获取数据上送地址 #

进行数据接入上报时，您需要根据当前的环境类型和端类型确认您的数据上报地址，如果上报地址设置错误，后续会导致您无法查询到上报的数据。

SaaS-云原生 & SaaS-非云原生 #

私有化环境 #

私有化部署场景下，您需要获取部署私有化环境时，自行规划配置的数据上送地址。如您不清楚此地址，请联系您的项目经理或客户成功经理。

权限声明 #

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

SaaS-云原生 #

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

// 创建新的 AppLog 实例
let appLog = new AppLog()
// 鸿蒙 sdk channel 作为可选参数
let config = new InitConfig('yourAppId', 'yourChannel')
  // 是否打开日志
  .setLogEnabled(true)
  // 设置SaaS-云原生上报地址，您需根据使用的DataFinder服务所在地域配置上送地址，详情见上文 获取数据上送地址 章节
  .setUri(createByDomain("https://gator.volces.com"))
// init sdk 传入配置，init 之后可以
appLog.init(context, config)

// 鸿蒙 SDK 需要手动调用 start 才开始采集敏感信息与发送请求
appLog.start()

SaaS-非云原生 #

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 采集 #

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

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

关闭运营商信息采集 #

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

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

如需使用实时埋点检测，请配置 Scheme，否则可跳过此步骤。

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

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

方式二 传统扫码跳转 #

现阶段鸿蒙系统浏览器已支持扫码跳转。

获取 URL Scheme #

「应用列表」-> 接入应用的「详情」->「URL Scheme」中可查看您的 scheme，一般为rangersapplog.xxxxx的形式。

配置 URL Scheme #

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

// 在 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 #

appLog.init(context, config)

SDK start #

appLog.start()

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

加密设置 #

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

打通内嵌 H5 页 #

如果您的应用同时集成 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 / 公共属性操作。

• 初始化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()

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 实验服务端配置 #

// 建议每次在获取最新 AB 后获取所有实验结果
appLog.topicReceiver().on(Topic.ABTestConfigReady, (_) => {
    appLog.abTest()?.getAllAbTestConfigs()
})

进行 AB 实验曝光 #

// 建议每次在获取最新 AB 后触发实验
appLog.topicReceiver().on(Topic.ABTestConfigReady, (_) => {
    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"
}

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

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