菜单

全埋点（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.APP_START,
        SAAutoTrackType.APP_END,
        SAAutoTrackType.APP_CLICK,
        SAAutoTrackType.APP_VIEW_SCREEN
    ]),
    auto_track_ignore_page: new Set([
        'pages/BridgeTest' // Route Page 名称
    ])
}))

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

前置要求

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



配置项参数如下：


参数名称示例说明
1auto_track_types    auto_track_types: new Set([
        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 页面浏览
2auto_track_ignore_page    auto_track_ignore_page: new Set([
        '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.APP_START,
        SAAutoTrackType.APP_END,
        SAAutoTrackType.APP_CLICK,
        SAAutoTrackType.APP_VIEW_SCREEN
    ]),
    auto_track_ignore_page: new Set([
        'pages/BridgeTest' // Route Page 名称
    ])
}))

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

上一个
HarmonyOS SDK
下一个
基础 API 介绍（HarmonyOS）
最近修改: 2024-12-27