1# 应用事件打点开发指导 2 3## 简介 4 5传统的日志系统里汇聚了整个设备上所有程序运行的过程流水日志，难以识别其中的关键信息。因此，应用开发者需要一种数据打点机制，用来评估如访问数、日活、用户操作习惯以及影响用户使用的关键因素等关键信息。 6 7HiAppEvent是在系统层面为应用开发者提供的一种事件打点机制，用于帮助应用记录在运行过程中发生的故障信息、统计信息、安全信息、用户行为信息，以支撑开发者分析应用的运行情况。 8 9## 基本概念 10 11- **打点** 12 13 记录由用户操作引起的变化，提供业务数据信息，以供开发、产品、运维分析。 14 15## 事件设计规范 16 17- 事件领域：用于标识事件的领域，建议设置为业务模块名称，以便于区分不同的业务模块。 18- 事件名称：用于指定事件的名称，建议设置为具体的业务名称，以便于描述实际的业务意义。 19- 事件类型：用于指定事件的类型，支持以下四种类型事件： 20 - 行为事件：用于记录用户日常操作行为的事件，例如按钮点击、界面跳转等行为。 21 - 故障事件：用于定位和分析应用故障的事件，例如界面卡顿、掉网掉话等异常。 22 - 统计事件：用于统计和度量应用关键行为的事件，例如对使用时长、访问数等的统计。 23 - 安全事件：用于记录涉及应用安全行为的事件，例如密码修改、用户授权等行为。 24- 事件参数：用于指定事件的参数，每个事件可以包含一组参数，建议设置为事件属性或事件发生上下文信息，以便于描述事件的详细信息。 25 26## 接口说明 27 28应用事件打点接口由hiAppEvent模块提供，API接口的具体使用说明（参数使用限制、具体取值范围等）请参考[应用事件打点API文档](../reference/apis/js-apis-hiviewdfx-hiappevent.md)。 29 30**打点接口功能介绍：** 31 32| 接口名 | 描述 | 33| ------------------------------------------------------------ | ---------------------------------------------------- | 34| write(AppEventInfo info, AsyncCallback\<void> callback): void | 应用事件异步打点方法，使用callback方式作为异步回调。 | 35| write(AppEventInfo info): Promise\<void> | 应用事件异步打点方法，使用Promise方式作为异步回调。 | 36 37**订阅接口功能介绍：** 38 39| 接口名 | 描述 | 40| -------------------------------------------------- | -------------------------------------------- | 41| addWatcher(Watcher watcher): AppEventPackageHolder | 添加应用事件观察者，以添加对应用事件的订阅。 | 42| removeWatcher(Watcher watcher): void | 移除应用事件观察者，以移除对应用事件的订阅。 | 43 44## 开发步骤 45 46以实现对用户点击按钮行为的事件打点及订阅为例，说明开发步骤。 47 481. 新建一个ArkTS应用工程，编辑工程中的“entry > src > main > ets > entryability > EntryAbility.ts” 文件，在onCreate函数中添加对用户点击按钮事件的订阅，完整示例代码如下： 49 50 ```ts 51 import AbilityConstant from '@ohos.app.ability.AbilityConstant'; 52 import hiAppEvent from '@ohos.hiviewdfx.hiAppEvent'; 53 import hilog from '@ohos.hilog'; 54 import UIAbility from '@ohos.app.ability.UIAbility'; 55 import Want from '@ohos.app.ability.Want'; 56 import window from '@ohos.window'; 57 58 export default class EntryAbility extends UIAbility { 59 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 60 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate'); 61 62 hiAppEvent.addWatcher({ 63 // 开发者可以自定义观察者名称，系统会使用名称来标识不同的观察者 64 name: "watcher1", 65 // 开发者可以订阅感兴趣的应用事件，此处是订阅了按钮事件 66 appEventFilters: [{ domain: "button" }], 67 // 开发者可以设置订阅回调触发的条件，此处是设置为事件打点数量满足1个 68 triggerCondition: { row: 1 }, 69 // 开发者可以自行实现订阅回调函数，以便对订阅获取到的事件打点数据进行自定义处理 70 onTrigger: (curRow: number, curSize: number, holder: hiAppEvent.AppEventPackageHolder) => { 71 // 返回的holder对象为null，表示订阅过程发生异常，因此在记录错误日志后直接返回 72 if (holder == null) { 73 hilog.error(0x0000, 'testTag', "HiAppEvent holder is null"); 74 return; 75 } 76 hilog.info(0x0000, 'testTag', `HiAppEvent onTrigger: curRow=%{public}d, curSize=%{public}d`, curRow, curSize); 77 let eventPkg: hiAppEvent.AppEventPackage | null = null; 78 // 根据设置阈值大小（默认为512KB）去获取订阅事件包，直到将订阅数据全部取出 79 // 返回的事件包对象为null，表示当前订阅数据已被全部取出，此次订阅回调触发结束 80 while ((eventPkg = holder.takeNext()) != null) { 81 // 开发者可以对事件包中的事件打点数据进行自定义处理，此处是将事件打点数据打印在日志中 82 hilog.info(0x0000, 'testTag', `HiAppEvent eventPkg.packageId=%{public}d`, eventPkg.packageId); 83 hilog.info(0x0000, 'testTag', `HiAppEvent eventPkg.row=%{public}d`, eventPkg.row); 84 hilog.info(0x0000, 'testTag', `HiAppEvent eventPkg.size=%{public}d`, eventPkg.size); 85 for (const eventInfo of eventPkg.data) { 86 hilog.info(0x0000, 'testTag', `HiAppEvent eventPkg.info=%{public}s`, eventInfo); 87 } 88 } 89 } 90 }); 91 } 92 } 93 942. 编辑工程中的“entry > src > main > ets > pages > Index.ets” 文件，添加一个按钮并在其onClick函数中进行事件打点，以记录按钮点击事件，完整示例代码如下： 95 96 ```ts 97 import { BusinessError } from '@ohos.base' 98 import hiAppEvent from '@ohos.hiviewdfx.hiAppEvent' 99 import hilog from '@ohos.hilog' 100 101 @Entry 102 @Component 103 struct Index { 104 @State message: string = 'Hello World' 105 106 build() { 107 Row() { 108 Column() { 109 Text(this.message) 110 .fontSize(50) 111 .fontWeight(FontWeight.Bold) 112 113 Button("writeTest").onClick(()=>{ 114 // 在按钮点击函数中进行事件打点，以记录按钮点击事件 115 let eventParams: Record<string, number> = { 'click_time': 100 }; 116 let eventInfo: hiAppEvent.AppEventInfo = { 117 // 事件领域定义 118 domain: "button", 119 // 事件名称定义 120 name: "click", 121 // 事件类型定义 122 eventType: hiAppEvent.EventType.BEHAVIOR, 123 // 事件参数定义 124 params: eventParams, 125 }; 126 hiAppEvent.write(eventInfo).then(() => { 127 hilog.info(0x0000, 'testTag', `HiAppEvent success to write event`) 128 }).catch((err: BusinessError) => { 129 hilog.error(0x0000, 'testTag', `HiAppEvent err.code: ${err.code}, err.message: ${err.message}`) 130 }); 131 }) 132 } 133 .width('100%') 134 } 135 .height('100%') 136 } 137 } 138 ``` 139 1403. 点击IDE界面中的运行按钮，运行应用工程，然后在应用界面中点击按钮“writeTest”，触发一次按钮点击事件打点。 141 1424. 最终，可以在Log窗口看到按钮点击事件打点成功的日志，以及触发订阅回调后对打点事件数据的处理日志： 143> HiAppEvent success to write event 144> HiAppEvent eventPkg.packageId=0 145> HiAppEvent eventPkg.row=1 146> HiAppEvent eventPkg.size=124 147> HiAppEvent eventPkg.info={"domain\_":"button","name\_":"click","type\_":4,"time\_":1670268234523,"tz\_":"+0800","pid\_":3295,"tid\_":3309,"click_time":100} 148 149## 相关实例 150 151针对应用事件开发，有以下相关实例可供参考： 152 153- [测试打点（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/OpenHarmony-4.0-Release/code/BasicFeature/DFX/DotTest) 154 155- [日志打印（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/OpenHarmony-4.0-Release/code/BasicFeature/DFX/Logger)