You need to enable JavaScript to run this app.
导航
HarmonyOS Next SDK 集成
最近更新时间:2024.11.08 15:57:10首次发布时间:2024.11.06 16:40:46

注意事项
  • 支持的环境

环境

是否支持

备注

SaaS-云原生
私有化 492 版本

已支持

环境已完成适配,platform 以 openHarmony 上报。
如果是老的私有化版本升级上来的,需要联系火山引擎技术支持人员获取 HarmonyOS Next SDK 新版适配包。

SaaS-非云原生

不支持

环境不支持或未完成适配,如果想提早集成,SDK 的 platform 会以 Android 上报。

私有化 492 之前版本

  • 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

注意

Finder HarmonyOS SDK 要求最低接入的鸿蒙版本为 API 12 以上。

获取 SDK 与接入方式

获取 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"
    }
  },
],

初始化增长营销套件 SDK

鸿蒙将 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-云原生上报地址
  .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 为用户授权权限,需要应用侧主动申请权限,如果申请权限且用户同意,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的形式。
Image

配置 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

说明

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

appLog.init(context, config)

SDK start

说明

请不要在 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

注意

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

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 / 公共属性操作。

注意

打通功能需要 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 实验服务端配置

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

DevTools 工具

说明

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

说明

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

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

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

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

说明

老版本 Devtools 并非像 Android 那样的全局悬浮窗,需要在哪个页面使用,需要在对应页面挂载。

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

import DevToolsPage from '@volcengine/applog_devtools'

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

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

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