1# @ohos.hiviewdfx.hiAppEvent (应用事件打点) 2 3本模块提供了应用事件打点能力，包括应用事件落盘、应用事件订阅、应用事件清理、打点功能配置等功能。 4 5> **说明：** 6> 7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9 10## 导入模块 11 12```ts 13import hiAppEvent from '@ohos.hiviewdfx.hiAppEvent'; 14``` 15 16## hiAppEvent.write 17 18write(info: [AppEventInfo](#appeventinfo), callback: AsyncCallback<void>): void 19 20应用事件打点方法，将事件写入到当天的事件文件中，可接收[AppEventInfo](#appeventinfo)类型的事件对象，使用callback方式作为异步回调。 21 22**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 23 24**参数：** 25 26| 参数名 | 类型 | 必填 | 说明 | 27| -------- | ------------------------------ | ---- | -------------- | 28| info | [AppEventInfo](#appeventinfo) | 是 | 应用事件对象。 | 29| callback | AsyncCallback<void> | 是 | 打点回调函数。 | 30 31**错误码：** 32 33以下错误码的详细介绍请参见[应用事件打点错误码](../errorcodes/errorcode-hiappevent.md)。 34 35| 错误码ID | 错误信息 | 36| -------- | --------------------------------------------- | 37| 11100001 | Function is disabled. | 38| 11101001 | Invalid event domain. | 39| 11101002 | Invalid event name. | 40| 11101003 | Invalid number of event parameters. | 41| 11101004 | Invalid string length of the event parameter. | 42| 11101005 | Invalid event parameter name. | 43| 11101006 | Invalid array length of the event parameter. | 44 45**示例：** 46 47```ts 48import { BusinessError } from '@ohos.base'; 49 50let eventParams: Record<string, number | string> = { 51 "int_data": 100, 52 "str_data": "strValue", 53}; 54hiAppEvent.write({ 55 domain: "test_domain", 56 name: "test_event", 57 eventType: hiAppEvent.EventType.FAULT, 58 params: eventParams, 59}, (err: BusinessError) => { 60 if (err) { 61 console.error(`code: ${err.code}, message: ${err.message}`); 62 return; 63 } 64 console.log(`success to write event`); 65}); 66``` 67 68## hiAppEvent.write 69 70write(info: [AppEventInfo](#appeventinfo)): Promise<void> 71 72应用事件打点方法，将事件写入到当天的事件文件中，可接收[AppEventInfo](#appeventinfo)类型的事件对象，使用Promise方式作为异步回调。 73 74**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 75 76**参数：** 77 78| 参数名 | 类型 | 必填 | 说明 | 79| ------ | ------------------------------ | ---- | -------------- | 80| info | [AppEventInfo](#appeventinfo) | 是 | 应用事件对象。 | 81 82**返回值：** 83 84| 类型 | 说明 | 85| ------------------- | ------------- | 86| Promise<void> | Promise对象。 | 87 88**错误码：** 89 90以下错误码的详细介绍请参见[应用事件打点错误码](../errorcodes/errorcode-hiappevent.md)。 91 92| 错误码ID | 错误信息 | 93| -------- | --------------------------------------------- | 94| 11100001 | Function is disabled. | 95| 11101001 | Invalid event domain. | 96| 11101002 | Invalid event name. | 97| 11101003 | Invalid number of event parameters. | 98| 11101004 | Invalid string length of the event parameter. | 99| 11101005 | Invalid event parameter name. | 100| 11101006 | Invalid array length of the event parameter. | 101 102**示例：** 103 104```ts 105import { BusinessError } from '@ohos.base'; 106 107let eventParams: Record<string, number | string> = { 108 "int_data": 100, 109 "str_data": "strValue", 110}; 111hiAppEvent.write({ 112 domain: "test_domain", 113 name: "test_event", 114 eventType: hiAppEvent.EventType.FAULT, 115 params: eventParams, 116}).then(() => { 117 console.log(`success to write event`); 118}).catch((err: BusinessError) => { 119 console.error(`code: ${err.code}, message: ${err.message}`); 120}); 121``` 122 123## AppEventInfo 124 125此接口提供了应用事件信息的参数选项。 126 127**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 128 129| 名称 | 类型 | 必填 | 说明 | 130| --------- | ----------------------- | ---- | ------------------------------------------------------------ | 131| domain | string | 是 | 事件领域。事件领域名称支持数字、小写字母、下划线字符，需要以小写字母开头且不能以下划线结尾，长度非空且不超过16个字符。 | 132| name | string | 是 | 事件名称。事件名称支持数字字符、字母字符、下划线字符，需要以字母字符或$字符开头且不能以下划线字符结尾，长度非空且不超过48个字符。 | 133| eventType | [EventType](#eventtype) | 是 | 事件类型。 | 134| params | object | 是 | 事件参数对象，每个事件参数包括参数名和参数值，其规格定义如下：<br>- 参数名为string类型，只支持数字字符、字母字符、下划线字符，需要以字母字符或$字符开头且不能以下划线字符结尾，长度非空且不超过16个字符。<br>- 参数值支持string、number、boolean、数组类型，string类型参数长度需在8*1024个字符以内，超出会做丢弃处理；number类型参数取值需在Number.MIN_SAFE_INTEGER~Number.MAX_SAFE_INTEGER范围内，超出可能会产生不确定值；数组类型参数中的元素类型只能全为string、number、boolean中的一种，且元素个数需在100以内，超出会做丢弃处理。<br>- 参数个数需在32个以内，超出的参数会做丢弃处理。 | 135 136## hiAppEvent.configure 137 138configure(config: [ConfigOption](configoption)): void 139 140应用事件打点配置方法，可用于配置打点开关、目录存储配额大小等功能。 141 142**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 143 144**参数：** 145 146| 参数名 | 类型 | 必填 | 说明 | 147| ------ | ----------------------------- | ---- | ------------------------ | 148| config | [ConfigOption](#configoption) | 是 | 应用事件打点配置项对象。 | 149 150**错误码：** 151 152以下错误码的详细介绍请参见[应用事件打点错误码](../errorcodes/errorcode-hiappevent.md)。 153 154| 错误码ID | 错误信息 | 155| -------- | -------------------------------- | 156| 11103001 | Invalid max storage quota value. | 157 158**示例：** 159 160```ts 161// 配置打点开关为关闭状态 162let config1: hiAppEvent.ConfigOption = { 163 disable: true, 164}; 165hiAppEvent.configure(config1); 166 167// 配置文件目录存储配额为100M 168let config2: hiAppEvent.ConfigOption = { 169 maxStorage: '100M', 170}; 171hiAppEvent.configure(config2); 172``` 173 174## ConfigOption 175 176此接口提供了对应用事件打点功能的配置选项。 177 178**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 179 180| 名称 | 类型 | 必填 | 说明 | 181| ---------- | ------- | ---- | ------------------------------------------------------------ | 182| disable | boolean | 否 | 打点功能开关，默认值为false。true：关闭打点功能，false：不关闭打点功能。 | 183| maxStorage | string | 否 | 打点数据存放目录的配额大小，默认值为“10M”。<br>在目录大小超出配额后，下次打点会触发对目录的清理操作：按从旧到新的顺序逐个删除打点数据文件，直到目录大小不超出配额时结束。 | 184 185## hiAppEvent.addWatcher 186 187addWatcher(watcher: [Watcher](#watcher)): [AppEventPackageHolder](#appeventpackageholder) 188 189添加应用事件观察者方法，可用于订阅应用事件。 190 191**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 192 193**参数：** 194 195| 参数名 | 类型 | 必填 | 说明 | 196| ------- | -------------------- | ---- | ---------------- | 197| watcher | [Watcher](#watcher) | 是 | 应用事件观察者。 | 198 199**返回值：** 200 201| 类型 | 说明 | 202| ------------------------------------------------ | ------------------------------------ | 203| [AppEventPackageHolder](#appeventpackageholder) | 订阅数据持有者，订阅失败时返回null。 | 204 205**错误码：** 206 207以下错误码的详细介绍请参见[应用事件打点错误码](../errorcodes/errorcode-hiappevent.md)。 208 209| 错误码ID | 错误信息 | 210| -------- | ------------------------------- | 211| 11102001 | Invalid watcher name. | 212| 11102002 | Invalid filtering event domain. | 213| 11102003 | Invalid row value. | 214| 11102004 | Invalid size value. | 215| 11102005 | Invalid timeout value. | 216 217**示例：** 218 219```ts 220// 1. 如果观察者传入了回调的相关参数，则可以选择在自动触发的回调函数中对订阅事件进行处理 221hiAppEvent.addWatcher({ 222 name: "watcher1", 223 appEventFilters: [ 224 { 225 domain: "test_domain", 226 eventTypes: [hiAppEvent.EventType.FAULT, hiAppEvent.EventType.BEHAVIOR] 227 } 228 ], 229 triggerCondition: { 230 row: 10, 231 size: 1000, 232 timeOut: 1 233 }, 234 onTrigger: (curRow: number, curSize: number, holder: hiAppEvent.AppEventPackageHolder) => { 235 if (holder == null) { 236 console.error("holder is null"); 237 return; 238 } 239 console.info(`curRow=${curRow}, curSize=${curSize}`); 240 let eventPkg: hiAppEvent.AppEventPackage | null = null; 241 while ((eventPkg = holder.takeNext()) != null) { 242 console.info(`eventPkg.packageId=${eventPkg.packageId}`); 243 console.info(`eventPkg.row=${eventPkg.row}`); 244 console.info(`eventPkg.size=${eventPkg.size}`); 245 for (const eventInfo of eventPkg.data) { 246 console.info(`eventPkg.data=${eventInfo}`); 247 } 248 } 249 } 250}); 251 252// 2. 如果观察者未传入回调的相关参数，则可以选择使用返回的holder对象手动去处理订阅事件 253let holder = hiAppEvent.addWatcher({ 254 name: "watcher2", 255}); 256if (holder != null) { 257 let eventPkg: hiAppEvent.AppEventPackage | null = null; 258 while ((eventPkg = holder.takeNext()) != null) { 259 console.info(`eventPkg.packageId=${eventPkg.packageId}`); 260 console.info(`eventPkg.row=${eventPkg.row}`); 261 console.info(`eventPkg.size=${eventPkg.size}`); 262 for (const eventInfo of eventPkg.data) { 263 console.info(`eventPkg.data=${eventInfo}`); 264 } 265 } 266} 267``` 268 269## hiAppEvent.removeWatcher 270 271removeWatcher(watcher: [Watcher](#watcher)): void 272 273移除应用事件观察者方法，可用于取消订阅应用事件。 274 275**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 276 277**参数：** 278 279| 参数名 | 类型 | 必填 | 说明 | 280| ------- | -------------------- | ---- | ---------------- | 281| watcher | [Watcher](#watcher) | 是 | 应用事件观察者。 | 282 283**错误码：** 284 285以下错误码的详细介绍请参见[应用事件打点错误码](../errorcodes/errorcode-hiappevent.md)。 286 287| 错误码ID | 错误信息 | 288| -------- | --------------------- | 289| 11102001 | Invalid watcher name. | 290 291**示例：** 292 293```ts 294// 1. 定义一个应用事件观察者 295let watcher: hiAppEvent.Watcher = { 296 name: "watcher1", 297} 298 299// 2. 添加一个应用事件观察者来订阅事件 300hiAppEvent.addWatcher(watcher); 301 302// 3. 移除该应用事件观察者以取消订阅事件 303hiAppEvent.removeWatcher(watcher); 304``` 305 306## Watcher 307 308此接口提供了应用事件观察者的参数选项。 309 310**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 311 312| 名称 | 类型 | 必填 | 说明 | 313| ---------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 314| name | string | 是 | 观察者名称，用于唯一标识观察者。 | 315| triggerCondition | [TriggerCondition](#triggercondition) | 否 | 订阅回调触发条件，需要与回调函数一同传入才会生效。 | 316| appEventFilters | [AppEventFilter](#appeventfilter)[] | 否 | 订阅过滤条件，在需要对订阅事件进行过滤时传入。 | 317| onTrigger | (curRow: number, curSize: number, holder: [AppEventPackageHolder](#appeventpackageholder)) => void | 否 | 订阅回调函数，需要与回调触发条件一同传入才会生效，函数入参说明如下：<br>curRow：在本次回调触发时的订阅事件总数量； <br>curSize：在本次回调触发时的订阅事件总大小，单位为byte； <br/>holder：订阅数据持有者对象，可以通过其对订阅事件进行处理。 | 318 319## TriggerCondition 320 321此接口提供了回调触发条件的参数选项，只要满足任一条件就会触发订阅回调。 322 323**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 324 325| 名称 | 类型 | 必填 | 说明 | 326| ------- | ------ | ---- | -------------------------------------- | 327| row | number | 否 | 满足触发回调的事件总数量。 | 328| size | number | 否 | 满足触发回调的事件总大小，单位为byte。 | 329| timeOut | number | 否 | 满足触发回调的超时时长，单位为30s。 | 330 331## AppEventFilter 332 333此接口提供了过滤应用事件的参数选项。 334 335**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 336 337| 名称 | 类型 | 必填 | 说明 | 338| ---------- | ------------------------- | ---- | ------------------------ | 339| domain | string | 是 | 需要订阅的事件领域。 | 340| eventTypes | [EventType](#eventtype)[] | 否 | 需要订阅的事件类型集合。 | 341 342## AppEventPackageHolder 343 344订阅数据持有者类，用于对订阅事件进行处理。 345 346**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 347 348### constructor 349 350constructor(watcherName: string) 351 352类构造函数，在添加应用事件观察者时，会由系统自动调用来创建一个该观察者对应的订阅数据持有者对象，并返回给开发者。 353 354**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 355 356**参数：** 357 358| 参数名 | 类型 | 必填 | 说明 | 359| ------ | ----------------- | ---- | ------------------------ | 360| watcherName | string | 是 | 观察者名称。 | 361 362**示例：** 363 364```ts 365let holder1 = hiAppEvent.addWatcher({ 366 name: "watcher1", 367}); 368``` 369 370### setSize 371 372setSize(size: number): void 373 374设置每次取出的应用事件包的数据大小阈值。 375 376**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 377 378**参数：** 379 380| 参数名 | 类型 | 必填 | 说明 | 381| ------ | ------ | ---- | -------------------------------------------- | 382| size | number | 是 | 数据大小阈值，单位为byte，默认值为512*1024。 | 383 384**错误码：** 385 386以下错误码的详细介绍请参见[应用事件打点错误码](../errorcodes/errorcode-hiappevent.md)。 387 388| 错误码ID | 错误信息 | 389| -------- | ------------------- | 390| 11104001 | Invalid size value. | 391 392**示例：** 393 394```ts 395let holder2 = hiAppEvent.addWatcher({ 396 name: "watcher2", 397}); 398holder2.setSize(1000); 399``` 400 401### takeNext 402 403takeNext(): [AppEventPackage](#appeventpackage) 404 405根据设置的数据大小阈值来取出订阅事件数据，当订阅事件数据全部被取出时返回null作为标识。 406 407**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 408 409**示例：** 410 411```ts 412let holder3 = hiAppEvent.addWatcher({ 413 name: "watcher3", 414}); 415let eventPkg = holder3.takeNext(); 416``` 417 418## AppEventPackage 419 420此接口提供了订阅返回的应用事件包的参数定义。 421 422**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 423 424| 名称 | 类型 | 必填 | 说明 | 425| --------- | -------- | ---- | ------------------------------ | 426| packageId | number | 是 | 事件包ID，从0开始自动递增。 | 427| row | number | 是 | 事件包的事件数量。 | 428| size | number | 是 | 事件包的事件大小，单位为byte。 | 429| data | string[] | 是 | 事件包的事件信息。 | 430 431## hiAppEvent.clearData 432 433clearData(): void 434 435应用事件打点数据清理方法，将应用存储在本地的打点数据进行清除。 436 437**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 438 439**示例：** 440 441```ts 442hiAppEvent.clearData(); 443``` 444 445 446## EventType 447 448事件类型枚举。 449 450**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 451 452| 名称 | 值 | 说明 | 453| --------- | ---- | -------------- | 454| FAULT | 1 | 故障类型事件。 | 455| STATISTIC | 2 | 统计类型事件。 | 456| SECURITY | 3 | 安全类型事件。 | 457| BEHAVIOR | 4 | 行为类型事件。 | 458 459 460## event 461 462此接口提供了所有预定义事件的事件名称常量。 463 464**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 465 466| 名称 | 类型 | 说明 | 467| ------------------------- | ------ | -------------------- | 468| USER_LOGIN | string | 用户登录事件。 | 469| USER_LOGOUT | string | 用户登出事件。 | 470| DISTRIBUTED_SERVICE_START | string | 分布式服务启动事件。 | 471 472 473## param 474 475此接口提供了所有预定义参数的参数名称常量。 476 477**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 478 479| 名称 | 类型 | 说明 | 480| ------------------------------- | ------ | ------------------ | 481| USER_ID | string | 用户自定义ID。 | 482| DISTRIBUTED_SERVICE_NAME | string | 分布式服务名称。 | 483| DISTRIBUTED_SERVICE_INSTANCE_ID | string | 分布式服务实例ID。 |