:::warning
HarmonyOS Next SDK集成文档已改版，请查看新版文档：HarmonyOS Next SDK 集成
:::

注意事项

• 支持的环境：

  | | | | \

  环境	是否支持	备注
  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

:::warning
Finder HarmonyOS SDK 要求最低接入的鸿蒙版本为 API 12 以上。
具体接入方式请参考随离线包附带的离线接入文档，每个版本会有略微差异。
:::

获取 SDK 与接入方式

SDK 下载与选择

| | | \

环境	SDK 选择
SaaS-云原生	\
私有化 492 及以上版本	请选择 platform=openHarmony 对应的 SDK
SaaS-非云原生、	\
私有化 492 之前版本	请选择 platform=Android 对应的 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",
}

获取数据上送地址

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

• 请在上报数据前，务必确认您当前使用的环境类型，根据环境类型配置上报地址。查看当前的环境类型请参见SaaS云原生/非云原生&私有化环境。
• 如果您使用的是SaaS-云原生环境，您也需确认您的服务所在的地域，根据所在地域配置上报地址（通常您的服务会在华北2-北京地域，部分用户可能会使用其他地域）。SaaS-云原生用户查看服务所在地域请参见支持的地域。
  :::
  

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

| | | | | |
|端类型 |SaaS-云原生环境 |
| |（国内：华北2-北京&华南1-广州） |SaaS-云原生环境 |
| | |（海外：亚太东南-柔佛） |SaaS-非云原生环境 国内环境 |SaaS-非云原生 海外BytePlus环境 |\

				（以下 SG 指新加坡）
HarmonyOS	* SaaS-云原生（华北）：https://gator.volces.com	\
	* SaaS-云原生（华南）：	\
	https://gator.uba.cn-guangzhou.volces.com	* https://gator.uba.ap-southeast-1.volces.com	无需配置，使用默认的数据上报地址	暂不支持

私有化环境

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

权限声明

:::warning
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"
    }
  },
],

初始化增长营销套件 SDK

鸿蒙将 init 与 start 完全分离。

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

敏感信息采集

:::warning
自1.3.0版本开始支持通过以下开关的配置来关闭 Oaid、运营商信息采集。
:::

关闭 Oaid 采集

:::tip
鸿蒙 Oaid 为用户授权权限，需要应用侧主动申请权限，如果申请权限且用户同意，SDK 才能采集到 Oaid，也支持在用户同意的情况下关闭 Oaid 采集。
:::
设备的 OAID 信息采集默认开启，如需关闭：

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

关闭运营商信息采集

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

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

配置 Scheme(可选)

如需使用实时埋点检测，请配置 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

:::tip
SDK 在 init 之前不接受任何方法调用，想要调用 SDK 内部方法，需要先进行 init，且 init 方法已做合规处理，init 不会自动采集敏感信息与发送请求。
可以考虑在 AbilityStage 的 onCreate 中 sdk init，在隐私同意后进行 sdk start。
:::

appLog.init(context, config)

SDK start

:::tip
请不要在 init 之前调用 start，调用 start 后，SDK 真正开始做敏感信息采集与请求上报。
:::

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

:::warning
该加密方式目前仅私有化版本支持。
:::

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 / 公共属性操作。
:::warning
打通功能需要 Web/JS SDK 与 Harmony SDK 同时集成并彼此配合，且当前版本 Web/JS SDK 打通后默认屏蔽 H5 全埋点功能，因为此时上报都由 Harmony SDK 接管，如果还想采集 H5 全埋点，需要查看 5.7 小节：原生端采集 H5 全埋点 。 Web/JS SDK 集成请参考《Web/JS SDK 集成》 以及 3.4 小节。
:::

• 初始化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 实验

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 工具

:::tip
SDK 提供了 DevTools 工具，支持在开发时方便观察 SDK 的一些运行信息。
:::

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 及以上版本

:::tip
新版使用方式：1.2.0 及以上版本
新版本 Devtools 实现了和 Android 一样的全局悬浮能力（使用子窗口功能），所以无需额外挂载，直接使用即可。
如果是老版本升级上来，需要移除之前的使用方式。
新版版监听 onWindowStageActive，如果 SDK 初始化比较晚可能错过监听，前后台切换一下即可，显示出来，正常情况无需手动调用显示。
:::

//  如果需要手动打开 可以手动调用：
Devtools.show(windowStage: window.WindowStage)

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

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

:::tip
老版本 Devtools 并非像 Android 那样的全局悬浮窗，需要在哪个页面使用，需要在对应页面挂载。
:::
在需要的页面挂载 DevTools 组件，推荐在根组件上挂载

import DevToolsPage from '@volcengine/applog_devtools'

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

参考：数据上报流程与机制

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