1. 产品说明

HarmonyOS Analytics SDK 全埋点（简称：HarmonyOS 全埋点）依赖于代码埋点，支持自动采集元素点击（$AppClick）、页面浏览（$AppViewScreen）、应用启动（$AppStart）、应用退出（$AppEnd）四种类型事件。

前置要求

HarmonyOS 全埋点最低要求 HarmonyOS API 12，且仅支持 Stage 应用模型。关于鸿蒙应用模型的介绍，可以参照鸿蒙官方文档。
HarmonyOS 操作系统要求：3.0.0.22 及以上，具体见「设置」->「关于手机」→「软件版本」
DevStudio IDE 版本要求：5.0.3.300 及以上

2. 功能清单

	事件类型	功能点	说明	备注
1	元素点击	元素点击自动采集	元素点击自动触发	支持组件类型： Text Button Radio Toggle TextInput TextArea List Grid 不支持组件类型： ToolbarItem 受限支持组件类型（无法采集 $element_content）： Dialog Menu/Option TabBar
2		指定元素自定义参数	针对指定元素自定义属性	作用于任意已支持组件类型
3		忽略指定元素点击	通过配置，禁止自动采集指定元素点击行为	作用于任意已支持组件类型
4	页面浏览	页面浏览自动采集	打开新 Page 自动触发	支持页面类型： Router Navigation
5		指定页面自定义参数	针对指定页面自定义属性	支持 Router / Navigation
6		忽略指定页面浏览	通过配置，禁止自动采集指定页面浏览行为	支持 Router / Navigation
7	应用启动	应用启动自动采集	应用启动后自动触发	应用启动后采集
8	应用退出	应用退出自动采集	应用整体退出时自动触发	若存在多 Ability 则所有 Ability 全部销毁则自动采集

3. 集成文档

3.1. 集成

HarmonyOS 全埋点采用插件化设计思路，在 初始化之前 调用 use 方法注册全埋点插件：

import sensors from '@sensorsdata/analytics'; 
import { SAAutoTrack, SAAutoTrackType } from '@sensorsdata/analytics'  // 在初始化之前集成 HarmonyOS 全埋点插件
sensors.use(SAAutoTrack({
    auto_track_types: new Set<SAAutoTrackType>([
        SAAutoTrackType.APP_START,
        SAAutoTrackType.APP_END,
        SAAutoTrackType.APP_CLICK,
        SAAutoTrackType.APP_VIEW_SCREEN
    ]),
    auto_track_ignore_page: new Set<string>([
        'pages/BridgeTest' // Route Page 名称
    ])
}))

// 代码埋点初始化
sensors.init({
    server_url: '${数据接收地址}',
    context: this.context,
    show_log: true,
    app_js_bridge: true
 });

CODE

前置要求

务必在初始化方法（init）之前集成注册 HarmonyOS 全埋点插件，否则不生效！

配置项参数如下：

参数名称

示例

说明

1

auto_track_types

auto_track_types: new Set<SAAutoTrackType>([
SAAutoTrackType.APP_START,
SAAutoTrackType.APP_END,
SAAutoTrackType.APP_CLICK,
SAAutoTrackType.APP_VIEW_SCREEN
])

Set 枚举类型，添加后则开启相应事件自动采集。

SAAutoTrackType.APP_START 应用启动
SAAutoTrackType.APP_END 应用退出
SAAutoTrackType.APP_CLICK 元素点击
SAAutoTrackType.APP_VIEW_SCREEN 页面浏览

2

auto_track_ignore_page

auto_track_ignore_page: new Set<string>([
'pages/BridgeTest', // Route Page 名称
])

Set string 类型，PageName 不包含文件名后缀。

配置后该页面将被忽略自动采集页面浏览事件。

3.2. 验证

打开埋点日志开关 show_log 后，通过观察日志，快速验证是否集成成功。以 $AppClick 事件举例，在日志搜索栏输入 sa_sdk 后，在 App 上点击任意支持的组件，观察日志是否触发「$AppClick」事件。

4. 基本使用

4.1. 元素点击

元素点击事件的示例数据如下：

{
    "identities": {
        "$identity_harmony_uuid": "0d390ba8-e1fa-47fe-889b-9aff399ee44b",
        "$identity_anonymous_id": "0d390ba8-e1fa-47fe-889b-9aff399ee44b"
    },
    "distinct_id": "0d390ba8-e1fa-47fe-889b-9aff399ee44b",
    "lib": {
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "0.1.0",
        "$app_version": "0.0.4"
    },
    "properties": {
        "$timezone_offset": -480,
        "$screen_height": 2720,
        "$screen_width": 1260,
        "$app_id": "com.sensorsdata.sensorsdatasdk",
        "$app_name": "神策分析 SDK",
        "$app_version": "0.0.4",
        "$manufacturer": "HUAWEI",
        "$brand": "HUAWEI",
        "$model": "ALN-AL00",
        "$os_version": "3.0.0.25(Canary4)",
        "$screen_name": "pages/Index",
        "$screen_orientation": "PORTRAIT",
        "$network_type": "WIFI",
        "$lib": "HarmonyOS",
        "$lib_method": "autoTrack",
        "$lib_version": "0.1.0",
        "$data_ingestion_source": [
            "HarmonyOS"
        ],
        "$os": "HarmonyOS",
        "$element_type": "Button",
        "$element_content": "track",
        "$is_first_day": false
    },
    "anonymous_id": "0d390ba8-e1fa-47fe-889b-9aff399ee44b",
    "type": "track",
    "event": "$AppClick",
    "time": 1719384635448,
    "_track_id": 842715460
}

CODE

4.1.1. 设置自定义属性

当元素被点击时，期望在全埋点 $AppClick 事件基础上追加/替换自定义参数，可以通过设置自定义属性满足该需求。

在组件上调用 customProperty API 传入 sensors_data_tag ，并将相应的属性传入。

	Button('按钮')
        .backgroundColor('#2a5a1c')
        .height(35)
        .width('80%')
        .margin({ top: 10 })
		.customProperty('sensors_data_tag', {
          'number': 10,
          'string': 'this is a string'
        })

CODE

sensors_data_tag 务必不要拼错，否则无法生效！customProperty 可以调用多次，具体用法可参照官网。

4.1.2. 忽略元素点击

全埋点元素点击默认采集所有元素，可以通过如下方式忽略指定元素点击行为。

在组件上调用 customProperty API 传入 sensors_data_tag ，并将 'ignore': true 参数传入，示例代码如下：

	Button('按钮')
        .backgroundColor('#2a5a1c')
        .height(35)
        .width('80%')
        .margin({ top: 10 })   
		.customProperty('sensors_data_tag', {
  			'ignore': true
		})

CODE

添加配置后，点击该元素进行验证即可。

4.2. 页面浏览

页面浏览事件数据如下：

{
    "identities": {
        "$identity_harmony_uuid": "0d390ba8-e1fa-47fe-889b-9aff399ee44b",
        "$identity_anonymous_id": "0d390ba8-e1fa-47fe-889b-9aff399ee44b"
    },
    "distinct_id": "0d390ba8-e1fa-47fe-889b-9aff399ee44b",
    "lib": {
        "$lib": "HarmonyOS",
        "$lib_method": "code",
        "$lib_version": "0.1.0",
        "$app_version": "0.0.4"
    },
    "properties": {
        "$timezone_offset": -480,
        "$screen_height": 2720,
        "$screen_width": 1260,
        "$app_id": "com.sensorsdata.sensorsdatasdk",
        "$app_name": "神策分析 SDK",
        "$app_version": "0.0.4",
        "$manufacturer": "HUAWEI",
        "$brand": "HUAWEI",
        "$model": "ALN-AL00",
        "$os_version": "3.0.0.25(Canary4)",
        "$screen_name": "pages/TimeTrack",
        "$screen_orientation": "PORTRAIT",
        "$network_type": "WIFI",
        "$lib": "HarmonyOS",
        "$lib_method": "autoTrack",
        "$lib_version": "0.1.0",
        "$data_ingestion_source": [
            "HarmonyOS"
        ],
        "$os": "HarmonyOS",
        "$referrer": "pages/Index",
        "$is_first_day": false,
        "out_registered": 1234
    },
    "anonymous_id": "0d390ba8-e1fa-47fe-889b-9aff399ee44b",
    "type": "track",
    "event": "$AppViewScreen",
    "time": 1719384748560,
    "_track_id": 622858571
}

CODE

4.2.1. 设置自定义属性

针对鸿蒙页面浏览事件，可以通过以下两种方式，将自定义属性传入到页面浏览事件中。

4.2.1.1. Router

通过 Router 的 Push API 传递 sensors_data_tag ，并将自定义属性作为值传入。示例代码如下：

router.pushUrl({
	url: 'pages/NavigationTest', params: {
	  'sensors_data_tag': {
	    "title": "订单页",
	    "is_login": false,
	    'number': 20
	  }
	}
}).then(() => {
	console.info('Succeeded in jumping to the NavigationTest page.')
}).catch((err: CodeError) => {
	console.error(`Failed to jump to the NavigationTest page.Code is ${err.code}, message is ${err.message}`)
})

CODE

上述示例中 pages/NavigationTest 页面触发页面浏览事件时，则会额外添加自定义属性。

4.2.1.2. NavPathStack

前提条件

NavPathStack 自定义传参，要求神策 HarmonyOS SDK v0.0.8 及以上版本

如 App 中通过 NavPathStack 实现路由，则可以通过 NavPathStack 的 Push 相关 API 将 params 传入。示例代码如下(以 ets 为例)：

传入 sensors_data_tag

let func = () => {
  hilog.info(0x0000, 'sa_sdk', '%{public}s', '=========test');
}

interface UserLoginParam {
  // 业务自定义参数
  customParams?: () => void
  // 神策目标页面的浏览事件追加的自定义参数
  sensors_data_tag?: SensorsDataPageParams
}

interface SensorsDataPageParams {
  name: string
  age: number
}
// 通过 sensors_data_tag 进行传值
let paramData: UserLoginParam = { customParams: func, sensors_data_tag: { name: 'xxx', age: 18 } }
this.pageStack.pushPath({ name: pageName, param: paramData })

CODE

上述示例中目标页面打开时，则会添加自定义属性。

4.2.2. 忽略页面浏览

在初始化全埋点插件时，通过配置页面名称，忽略指定页面的浏览事件，示例代码如下：

// 在初始化之前集成 HarmonyOS 全埋点插件
sensors.use(SAAutoTrack({
    auto_track_types: new Set<SAAutoTrackType>([
        SAAutoTrackType.APP_START,
        SAAutoTrackType.APP_END,
        SAAutoTrackType.APP_CLICK,
        SAAutoTrackType.APP_VIEW_SCREEN
    ]),
    auto_track_ignore_page: new Set<string>([
        'pages/BridgeTest' // Route Page 名称
    ])
}))

CODE

上述示例中 pages/BridgeTest 页面打开时，将不会采集页面浏览事件。