菜单

全埋点（HarmonyOS）

产品说明

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

前置要求

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

功能清单

  事件类型 功能点 说明 备注
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 全部销毁则自动采集

集成文档

集成

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

前置要求

务必在初始化方法（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 不包含文件名后缀。

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

验证

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

基本使用

元素点击

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

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

设置自定义属性

当元素被点击时，期望在全埋点 $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'
        })

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

忽略元素点击

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

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

	Button('按钮')
        .backgroundColor('#2a5a1c')
        .height(35)
        .width('80%')
        .margin({ top: 10 })   
		.customProperty('sensors_data_tag', {
  			'ignore': true
		})
添加配置后，点击该元素进行验证即可。

页面浏览

页面浏览事件数据如下：

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

设置自定义属性

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

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

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

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 })
上述示例中目标页面打开时，则会添加自定义属性。

忽略页面浏览

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

// 在初始化之前集成 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 名称
    ])
}))

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

上一个
HarmonyOS SDK
下一个
基础 API 介绍（HarmonyOS）
最近修改: 2025-01-02