1# @ohos.hiviewdfx.hiAppEvent (应用事件打点) 2 3<!--Kit: Performance Analysis Kit--> 4<!--Subsystem: HiviewDFX--> 5<!--Owner: @liujiaxing2024--> 6<!--Designer: @junjie_shi--> 7<!--Tester: @gcw_KuLfPSbe--> 8<!--Adviser: @foryourself--> 9 10本模块提供应用打点和事件订阅能力，包括事件存储、事件订阅、事件清理、打点配置等功能。HiAppEvent将应用运行过程中触发的事件信息统一归纳到[AppEventInfo](#appeventinfo)中，并将事件分为系统事件和应用事件两类。 11 12系统事件来源于系统服务，是系统预先定义的事件，这类事件信息中的事件参数对象params包含的字段已由各系统事件定义，具体字段含义在各系统事件指南的介绍中，例如[崩溃事件介绍](../../dfx/hiappevent-watcher-crash-events.md)。 13 14应用事件来源于应用，是应用开发者自己定义的事件，这类事件信息支持自定义后通过[Write](#hiappeventwrite-1)打点接口进行配置设定，具体字段含义可结合开发者需求展开。 15 16> **说明：** 17> 18> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 19 20 21## 导入模块 22 23```ts 24import { hiAppEvent } from '@kit.PerformanceAnalysisKit'; 25``` 26 27 28## hiAppEvent.addWatcher 29 30addWatcher(watcher: Watcher): AppEventPackageHolder 31 32添加事件观察者。可通过事件观察者的回调函数监听事件。 33 34**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 35 36**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 37 38**参数：** 39 40| 参数名 | 类型 | 必填 | 说明 | 41| ------- | -------------------- | ---- | ---------------- | 42| watcher | [Watcher](#watcher) | 是 | 事件观察者。 | 43 44**返回值：** 45 46| 类型 | 说明 | 47| ------------------------------------------------ | ------------------------------------ | 48| [AppEventPackageHolder](#appeventpackageholder) | 订阅数据持有者。订阅失败时返回null。 | 49 50**错误码：** 51 52以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[应用事件打点错误码](errorcode-hiappevent.md)。 53 54| 错误码ID | 错误信息 | 55| -------- | ------------------------------- | 56| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 57| 11102001 | Invalid watcher name. Possible causes: 1. Contain invalid characters; 2. Length is invalid. | 58| 11102002 | Invalid filtering event domain. Possible causes: 1. Contain invalid characters; 2. Length is invalid. | 59| 11102003 | Invalid row value. Possible caused by the row value is less than zero. | 60| 11102004 | Invalid size value. Possible caused by the size value is less than zero. | 61| 11102005 | Invalid timeout value. Possible caused by the timeout value is less than zero. | 62 63> **注意：** 64> 65> addWatcher接口涉及I/O操作。在对性能敏感的业务场景中，开发者应根据实际需要确定该接口是在主线程还是在子线程中调用。 66> 67> 如果选择在子线程中调用addWatcher，需要确保该子线程在整个接口使用周期内不会被销毁，以免影响接口的正常工作。 68> 69> 可参考[多线程并发概述](../../arkts-utils/multi-thread-concurrency-overview.md)，以实现在子线程中调用接口。 70> 71> 订阅接口addWatcher传入的名称name是唯一的，相同的name，后一次调用会覆盖前一次的订阅。 72 73**示例：** 74 75根据添加的事件观察者类型，目前有如下三种使用方法： 76 77方法一：设置回调条件triggerCondition，实现onTrigger()回调。当满足回调条件时，系统将自动触发回调。 78```ts 79import { hilog } from '@kit.PerformanceAnalysisKit'; 80 81hiAppEvent.addWatcher({ 82 name: "watcher1", 83 // 订阅过滤条件，这里是订阅了系统事件领域的应用崩溃事件 84 appEventFilters: [ 85 { 86 domain: hiAppEvent.domain.OS, 87 names: [hiAppEvent.event.APP_CRASH] 88 } 89 ], 90 // 设置触发onTrigger回调的条件，这里是当满足事件总数量达到10个或事件总大小达到1000byte或事件发生超过30s时会触发回调 91 triggerCondition: { 92 row: 10, 93 size: 1000, 94 timeOut: 1 95 }, 96 // 实现onTrigger回调，结合triggerCondition使用，满足回调条件触发回调，接收到回调通知后，使用takeNext()查询订阅的事件 97 onTrigger: (curRow: number, curSize: number, holder: hiAppEvent.AppEventPackageHolder) => { 98 if (holder == null) { 99 hilog.error(0x0000, 'hiAppEvent', "holder is null"); 100 return; 101 } 102 hilog.info(0x0000, 'hiAppEvent', `curRow=${curRow}, curSize=${curSize}`); 103 let eventPkg: hiAppEvent.AppEventPackage | null = null; 104 while ((eventPkg = holder.takeNext()) != null) { 105 hilog.info(0x0000, 'hiAppEvent', `eventPkg.packageId=${eventPkg.packageId}`); 106 hilog.info(0x0000, 'hiAppEvent', `eventPkg.row=${eventPkg.row}`); 107 hilog.info(0x0000, 'hiAppEvent', `eventPkg.size=${eventPkg.size}`); 108 for (const eventInfo of eventPkg.data) { 109 hilog.info(0x0000, 'hiAppEvent', `eventPkg.data=${eventInfo}`); 110 } 111 } 112 } 113}); 114``` 115 116方法二：未设置回调条件参数，使用事件订阅返回的holder对象主动获取监听的事件。 117<br>针对异常退出时产生的崩溃事件（hiAppEvent.event.APP_CRASH）和应用冻屏事件（hiAppEvent.event.APP_FREEZE），系统捕获维测日志有一定耗时，典型情况下30s内完成，极端情况下2min左右完成。 118<br>在手动处理订阅事件的方法中，由于事件可能未生成或日志信息未抓取完成，建议在进程启动后延时重试调用takeNext()获取此类事件。 119 120```ts 121import { hilog } from '@kit.PerformanceAnalysisKit'; 122 123let holder: hiAppEvent.AppEventPackageHolder = hiAppEvent.addWatcher({ 124 name: "watcher2", 125 // 订阅过滤条件，这里是订阅了系统事件领域的应用崩溃事件 126 appEventFilters: [ 127 { 128 domain: hiAppEvent.domain.OS, 129 names: [hiAppEvent.event.APP_CRASH] 130 } 131 ], 132}); 133// 通过订阅数据持有者holder，主动获取崩溃事件 134if (holder != null) { 135 let eventPkg: hiAppEvent.AppEventPackage | null = null; 136 while ((eventPkg = holder.takeNext()) != null) { 137 hilog.info(0x0000, 'hiAppEvent', `eventPkg.packageId=${eventPkg.packageId}`); 138 hilog.info(0x0000, 'hiAppEvent', `eventPkg.row=${eventPkg.row}`); 139 hilog.info(0x0000, 'hiAppEvent', `eventPkg.size=${eventPkg.size}`); 140 for (const eventInfo of eventPkg.data) { 141 hilog.info(0x0000, 'hiAppEvent', `eventPkg.data=${eventInfo}`); 142 } 143 } 144} 145``` 146 147方法三：实现onReceive()回调，当监听的事件发生后实时触发回调。 148 149```ts 150import { hilog } from '@kit.PerformanceAnalysisKit'; 151 152hiAppEvent.addWatcher({ 153 name: "watcher3", 154 // 订阅过滤条件，这里是订阅了系统事件领域的应用崩溃事件 155 appEventFilters: [ 156 { 157 domain: hiAppEvent.domain.OS, 158 names: [hiAppEvent.event.APP_CRASH] 159 } 160 ], 161 // 实现onReceive回调，监听到事件后实时回调 162 onReceive: (domain: string, appEventGroups: Array<hiAppEvent.AppEventGroup>) => { 163 hilog.info(0x0000, 'hiAppEvent', `domain=${domain}`); 164 for (const eventGroup of appEventGroups) { 165 hilog.info(0x0000, 'hiAppEvent', `eventName=${eventGroup.name}`); 166 for (const eventInfo of eventGroup.appEventInfos) { 167 hilog.info(0x0000, 'hiAppEvent', `event=${JSON.stringify(eventInfo)}`, ); 168 } 169 } 170 } 171}); 172``` 173 174 175## hiAppEvent.removeWatcher 176 177removeWatcher(watcher: Watcher): void 178 179移除事件观察者。 180 181**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 182 183**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 184 185**参数：** 186 187| 参数名 | 类型 | 必填 | 说明 | 188| ------- | -------------------- | ---- | ---------------- | 189| watcher | [Watcher](#watcher) | 是 | 事件观察者。 | 190 191**错误码：** 192 193以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[应用事件打点错误码](errorcode-hiappevent.md)。 194 195| 错误码ID | 错误信息 | 196| -------- | --------------------- | 197| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 198| 11102001 | Invalid watcher name. Possible causes: 1. Contain invalid characters; 2. Length is invalid. | 199 200**示例：** 201 202```ts 203// 1. 定义一个事件观察者 204let watcher: hiAppEvent.Watcher = { 205 name: "watcher1", 206} 207 208// 2. 添加一个事件观察者来订阅事件 209hiAppEvent.addWatcher(watcher); 210 211// 3. 移除该事件观察者以取消订阅事件 212hiAppEvent.removeWatcher(watcher); 213``` 214 215 216## hiAppEvent.setEventParam<sup>12+</sup> 217 218setEventParam(params: Record<string, ParamType>, domain: string, name?: string): Promise<void> 219 220事件自定义参数设置方法，使用Promise方式作为异步回调。在同一生命周期中，可以通过事件领域和事件名称关联系统事件和应用事件。 221 222**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 223 224**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 225 226**参数：** 227 228| 参数名 | 类型 | 必填 | 说明 | 229| ------ | ------------------------------ | ---- | -------------- | 230| params | Record<string, [ParamType](#paramtype12)> | 是 | 事件自定义参数对象。参数名和参数值规格定义如下：<br>- 参数名为string类型，首字符必须为字母字符或$字符。中间字符必须为数字字符、字母字符或下划线字符。结尾字符必须为数字字符或字母字符。长度非空且不超过32个字符。<br>- 参数值为[ParamType](#paramtype12)类型，参数值长度需在1024个字符以内。<br>- 参数个数需在64个以内。 | 231| domain | string | 是 | 事件领域。事件领域可支持关联应用事件和系统事件（hiAppEvent.domain.OS）。 | 232| name | string | 否 | 事件名称。默认为空字符串，空字符串表示关联事件领域下的所有事件名称。事件名称可支持关联应用事件和系统事件，其中系统事件仅支持关联：<br>- [崩溃事件](../../dfx/hiappevent-watcher-crash-events.md)（hiAppEvent.event.APP_CRASH）<br>- [应用冻屏事件](../../dfx/hiappevent-watcher-freeze-events.md)（hiAppEvent.event.APP_FREEZE）<br>- [资源泄漏事件](../../dfx/hiappevent-watcher-resourceleak-events.md)（hiAppEvent.event.RESOURCE_OVERLIMIT）。<br>**注意**：从API version 20开始，支持[资源泄漏事件](../../dfx/hiappevent-watcher-resourceleak-events.md)。 | 233 234**返回值：** 235 236| 类型 | 说明 | 237| ------------------- | ------------- | 238| Promise<void> | Promise对象。无返回结果的Promise对象。 | 239 240**错误码：** 241 242以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[应用事件打点错误码](errorcode-hiappevent.md)。 243 244| 错误码ID | 错误信息 | 245| -------- | --------------------------------------------- | 246| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 247| 11100001 | Function disabled. Possible caused by the param disable in ConfigOption is true. | 248| 11101001 | Invalid event domain. Possible causes: 1. Contain invalid characters; 2. Length is invalid. | 249| 11101002 | Invalid event name. Possible causes: 1. Contain invalid characters; 2. Length is invalid. | 250| 11101004 | Invalid string length of the event parameter. | 251| 11101005 | Invalid event parameter name. Possible causes: 1. Contain invalid characters; 2. Length is invalid. | 252| 11101007 | The number of parameter keys exceeds the limit. | 253 254**示例：** 255 256```ts 257import { BusinessError } from '@kit.BasicServicesKit'; 258import { hilog } from '@kit.PerformanceAnalysisKit'; 259 260let params: Record<string, hiAppEvent.ParamType> = { 261 "int_data": 100, 262 "str_data": "strValue", 263}; 264 265// 给应用事件追加自定义参数 266hiAppEvent.setEventParam(params, "test_domain", "test_event").then(() => { 267 hilog.info(0x0000, 'hiAppEvent', `success to set event param`); 268}).catch((err: BusinessError) => { 269 hilog.error(0x0000, 'hiAppEvent', `code: ${err.code}, message: ${err.message}`); 270}); 271``` 272 273 274## hiAppEvent.setEventConfig<sup>15+</sup> 275 276setEventConfig(name: string, config: Record<string, ParamType>): Promise<void> 277 278事件相关的配置参数设置方法，使用Promise方式作为异步回调。在同一生命周期中，可以通过事件名称，设置事件相关的配置参数。<br />不同的事件有不同的配置项，目前仅支持以下事件： 279- MAIN_THREAD_JANK（参数配置详见[主线程超时事件检测](../../dfx/hiappevent-watcher-mainthreadjank-events.md#自定义参数)） 280- APP_CRASH（参数配置详见[崩溃日志配置参数设置介绍](../../dfx/hiappevent-watcher-crash-events.md#崩溃日志规格自定义参数设置)） 281- RESOURCE_OVERLIMIT（参数配置详见[资源泄漏事件检测](../../dfx/hiappevent-watcher-resourceleak-events.md#自定义规格设置)） 282 283**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 284 285**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 286 287**参数：** 288 289| 参数名 | 类型 | 必填 | 说明 | 290| ------ | ------------------------------ | ---- | -------------- | 291| name | string | 是 | 事件名称。 | 292| config | Record<string, [ParamType](#paramtype12)> | 是 | 事件自定义参数对象。参数名和参数值规格定义如下：<br>- 参数名为string类型，要求非空，且参数名长度需在1024个字符以内。<br>- 参数值为ParamType类型，参数值长度需在1024个字符以内。 | 293 294**返回值：** 295 296| 类型 | 说明 | 297| ------------------- | ------------- | 298| Promise<void> | Promise对象。 | 299 300**错误码：** 301 302以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 303 304| 错误码ID | 错误信息 | 305| -------- | --------------------------------------------- | 306| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3.Parameter verification failed. | 307 308**示例：** 309 310以下示例用于模拟配置MAIN_THREAD_JANK事件的采集堆栈自定义参数： 311 312```ts 313import { BusinessError } from '@kit.BasicServicesKit'; 314import { hilog } from '@kit.PerformanceAnalysisKit'; 315 316let params: Record<string, hiAppEvent.ParamType> = { 317 "log_type": "1", 318 "sample_interval": "100", 319 "ignore_startup_time": "11", 320 "sample_count": "21", 321 "report_times_per_app": "3" 322}; 323hiAppEvent.setEventConfig(hiAppEvent.event.MAIN_THREAD_JANK, params).then(() => { 324 hilog.info(0x0000, 'hiAppEvent', `Successfully set sampling stack parameters.`); 325}).catch((err: BusinessError) => { 326hilog.error(0x0000, 'hiAppEvent', `Failed to set sample stack value. Code: ${err.code}, message: ${err.message}`); 327}); 328``` 329 330## Watcher 331 332提供事件观察者的参数选项。用于配置和管理事件的观察者，实现对特定事件的监听和处理。 333 334**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 335 336**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 337 338| 名称 | 类型 | 只读 | 可选 | 说明 | 339| ---------------- | ----------------------------------------------------|------ | ---- | ------------------------------------------------------------ | 340| name | string | 否 | 否 | 观察者名称，用于唯一标识观察者。首字符必须为字母字符，中间字符必须为数字字符、字母字符或下划线字符，结尾字符必须为数字字符或字母字符，长度非空且不超过32个字符。如testName1、crash_Watcher等。 | 341| triggerCondition | [TriggerCondition](#triggercondition) | 否 | 是 | 订阅回调触发条件，需要与回调函数onTrigger一同传入才会生效。默认不触发。 | 342| appEventFilters | [AppEventFilter](#appeventfilter)[] | 否 | 是 | 订阅过滤条件，在需要对订阅事件进行过滤时传入。默认不过滤事件。 | 343| onTrigger | (curRow: number, curSize: number, holder: [AppEventPackageHolder](#appeventpackageholder)) => void | 否 | 是 | 订阅回调函数，需要与回调触发条件triggerCondition一同传入才会生效，函数入参说明如下：<br>curRow：在本次回调触发时的订阅事件总数量； <br>curSize：在本次回调触发时的订阅事件总大小，单位为byte； <br/>holder：订阅数据持有者对象，可以通过其对订阅事件进行处理。 | 344| onReceive<sup>11+</sup> | (domain: string, appEventGroups: Array<[AppEventGroup](#appeventgroup11)>) => void | 否 | 是 | 订阅实时回调函数，与回调函数onTrigger同时存在时，只触发此回调，函数入参说明如下：<br>domain：回调事件的领域名称； <br>appEventGroups：回调事件集合。 | 345 346 347## TriggerCondition 348 349提供设置[Watcher](#watcher)的onTrigger回调触发条件的参数选项。 350 351**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 352 353**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 354 355| 名称 | 类型 | 只读 | 可选 | 说明 | 356| ------- | ------ | ---- | ---- | -------------------------------------- | 357| row | number | 否 | 是 | 满足触发回调的事件总数量，正整数。默认值0，不触发回调。传入负值时，会被置为默认值。 | 358| size | number | 否 | 是 | 满足触发回调的事件总大小，正整数，单位为byte。默认值0，不触发回调。传入负值时，会被置为默认值。 | 359| timeOut | number | 否 | 是 | 满足触发回调的超时时长，正整数，单位为30s。默认值0，不触发回调。传入负值时，会被置为默认值。 | 360 361 362## AppEventFilter 363 364提供设置[Watcher](#watcher)的订阅过滤条件的参数选项。用于在事件观察者中设置事件过滤条件，确保只有满足过滤条件的事件才会被监听处理。 365 366**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 367 368**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 369 370| 名称 | 类型 | 只读 | 可选 | 说明 | 371| ---------- | ------------------------- | ---- | ---- | ------------------------ | 372| domain | string | 否 | 否 | 需要订阅的事件领域。可以是系统事件领域（hiAppEvent.domain.OS）或开发者在使用[Write](#hiappeventwrite-1)接口时传入的自定义事件信息（[AppEventInfo](#appeventinfo)）中的事件领域。 | 373| eventTypes | [EventType](#eventtype)[] | 否 | 是 | 需要订阅的事件类型集合。默认不进行过滤。 | 374| names<sup>11+</sup> | string[] | 否 | 是 | 需要订阅的事件名称集合。默认不进行过滤。 | 375 376> **说明：** 377> 378> 系统事件中：地址越界事件和任务执行超时事件不支持在元服务中订阅。启动耗时事件、滑动丢帧事件、CPU高负载事件和24h功耗器件分解统计事件均不支持在元服务和分身应用中订阅。 379 380## AppEventPackageHolder 381 382订阅数据持有者类，用于对事件信息进行处理。 383 384### constructor 385 386constructor(watcherName: string) 387 388类构造函数，用于创建订阅数据持有者实例。先通过[addWatcher](#hiappeventaddwatcher)添加事件观察者，再通过观察者名称关联到应用内已添加的观察者对象。 389 390**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 391 392**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 393 394**参数：** 395 396| 参数名 | 类型 | 必填 | 说明 | 397| ------ | ----------------- | ---- | ------------------------ | 398| watcherName | string | 是 | 已通过[addWatcher](#hiappeventaddwatcher)添加的事件观察者名称。若未通过addWatcher添加，则默认无数据。 | 399 400**示例：** 401 402```ts 403// 添加数据观察者“Watcher1”，订阅监听系统事件 404hiAppEvent.addWatcher({ 405 name: "Watcher1", 406 appEventFilters: [ 407 { 408 domain: hiAppEvent.domain.OS, 409 } 410 ], 411 }); 412 413// 创建订阅数据持有者实例，holder1持有的数据为上述addWatcher中添加的观察者“Watcher1”监听到的事件 414let holder1: hiAppEvent.AppEventPackageHolder = new hiAppEvent.AppEventPackageHolder("Watcher1"); 415``` 416 417### setSize 418 419setSize(size: number): void 420 421设置每次取出的事件包的数据大小阈值。 422 423**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 424 425**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 426 427**参数：** 428 429| 参数名 | 类型 | 必填 | 说明 | 430| ------ | ------ | ---- | -------------------------------------------- | 431| size | number | 是 | 数据大小阈值，单位为byte。取值范围[0, 2^31-1]，超出范围会抛异常。 | 432 433**错误码：** 434 435以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[应用事件打点错误码](errorcode-hiappevent.md)。 436 437| 错误码ID | 错误信息 | 438| -------- | ------------------- | 439| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 440| 11104001 | Invalid size value. Possible caused by the size value is less than or equal to zero. | 441 442**示例：** 443 444```ts 445// 创建订阅数据持有者实例，holder2持有的数据为已通过addWatcher添加的观察者“Watcher1”监听到的事件 446let holder2: hiAppEvent.AppEventPackageHolder = new hiAppEvent.AppEventPackageHolder("Watcher1"); 447// 设置每次取出事件包的数据大小阈值为1000byte 448holder2.setSize(1000); 449``` 450 451### setRow<sup>12+</sup> 452 453setRow(size: number): void 454 455设置每次取出的事件包的数据条数，优先级高于setSize，和setSize同时调用时仅setRow生效。 456 457**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 458 459**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 460 461**参数：** 462 463| 参数名 | 类型 | 必填 | 说明 | 464| ------ | ------ | ---- | -------------------------------------------- | 465| size | number | 是 | 事件条数，单位为条。取值范围(0, 2^31-1]，超出范围会抛异常。 | 466 467**错误码：** 468 469以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[应用事件打点错误码](errorcode-hiappevent.md)。 470 471| 错误码ID | 错误信息 | 472| -------- | ------------------- | 473| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 474| 11104001 | Invalid size value. Possible caused by the size value is less than or equal to zero. | 475 476**示例：** 477 478```ts 479// 创建订阅数据持有者实例，holder3持有的数据为已通过addWatcher添加的观察者“Watcher1”监听到的事件 480let holder3: hiAppEvent.AppEventPackageHolder = new hiAppEvent.AppEventPackageHolder("Watcher1"); 481// 设置每次取出的事件包的数据条数为1000条 482holder3.setRow(1000); 483``` 484 485### takeNext 486 487takeNext(): AppEventPackage 488 489获取订阅事件。 490 491系统根据setSize设置的数据大小阈值或setRow设置的条数来取出订阅事件数据，默认取1条订阅事件。当订阅事件数据全部被取出时返回null。 492 493当setRow和setSize同时调用时仅setRow生效。 494 495**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 496 497**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 498 499**返回值：** 500 501| 类型 | 说明 | 502| ----------------------------------- | ------------------------------------------------------ | 503| [AppEventPackage](#appeventpackage) | 取出的事件包对象，订阅事件数据被全部取出后会返回null。 | 504 505**示例：** 506 507```ts 508// 创建订阅数据持有者实例，holder4持有的数据为已通过addWatcher添加的观察者“Watcher1”监听到的事件 509let holder4: hiAppEvent.AppEventPackageHolder = new hiAppEvent.AppEventPackageHolder("Watcher1"); 510// 获取订阅事件 511let eventPkg: hiAppEvent.AppEventPackage | null = holder4.takeNext(); 512``` 513 514 515## AppEventInfo 516 517提供事件信息的参数选项。 518 519**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 520 521**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 522 523| 名称 | 类型 | 只读 | 可选 | 说明 | 524| --------- | ----------------------- | ---- | ---- | ------------------------------------------------------------ | 525| domain | string | 否 | 否 | 事件领域。事件领域名称支持数字、字母、下划线字符，需要以字母开头且不能以下划线结尾，长度非空且不超过32个字符。 | 526| name | string | 否 | 否 | 事件名称。首字符必须为字母字符或$字符，中间字符必须为数字字符、字母字符或下划线字符，结尾字符必须为数字字符或字母字符，长度非空且不超过48个字符。 | 527| eventType | [EventType](#eventtype) | 否 | 否 | 事件类型。 | 528| params | object | 否 | 否 | 事件参数对象，包含每个事件参数的参数名和参数值。**系统事件中params包含的字段已由各系统事件定义，具体字段含义在各类系统事件指南的介绍中，例如[崩溃事件介绍](../../dfx/hiappevent-watcher-crash-events.md)。** 针对应用事件，[Write](#hiappeventwrite-1)打点写入的参数由开发者定义，其规格如下：<br>- 参数名为string类型，首字符必须为字母字符或`$`字符，中间字符必须为数字字符、字母字符或下划线字符，结尾字符必须为数字字符或字母字符，长度非空且不超过32个字符。如testName、\$123_name等。<br>- 参数值支持string、number、boolean、数组类型。string类型参数长度需在8*1024个字符以内，超出后会和对应的参数名一同被丢弃；number类型参数取值需在Number.MIN_SAFE_INTEGER~Number.MAX_SAFE_INTEGER范围内，超出可能会产生不确定值；数组类型参数中的元素类型只能全为string、number、boolean中的一种，且元素个数需在100以内，超出部分即从第101个元素开始会被丢弃。<br>- 参数个数需在32个以内，超出的参数会做丢弃处理。 | 529 530 531## AppEventPackage 532 533提供订阅返回的事件包的参数定义。可用于获取事件包的详细信息，事件包由[takeNext](#takenext)接口获得。 534 535**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 536 537| 名称 | 类型 | 只读 | 可选 | 说明 | 538| --------- | -------- | ---- | ---- | ------------------------------ | 539| packageId | number | 否 | 否 | 事件包ID，从0开始自动递增。<br>**原子化服务API：** 从API version 11开始，该参数支持在原子化服务中使用。 | 540| row | number | 否 | 否 | 事件包的事件数量。<br>**原子化服务API：** 从API version 11开始，该参数支持在原子化服务中使用。 | 541| size | number | 否 | 否 | 事件包的事件大小，单位为byte。<br>**原子化服务API：** 从API version 11开始，该参数支持在原子化服务中使用。 | 542| data | string[] | 否 | 否 | 事件包的事件信息。<br>**原子化服务API：** 从API version 11开始，该参数支持在原子化服务中使用。 | 543| appEventInfos<sup>12+</sup> | Array<[AppEventInfo](#appeventinfo)> | 否 | 否 | 事件对象集合。<br>**原子化服务API：** 从API version 12开始，该参数支持在原子化服务中使用。 | 544 545 546## AppEventGroup<sup>11+</sup> 547 548提供订阅返回的事件组的参数定义。可用于获取事件组的详细信息，事件组常在[Watcher](#watcher)的onReceive回调中使用。 549 550**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 551 552**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 553 554| 名称 | 类型 | 只读 | 可选 | 说明 | 555| ------------- | ------------------------------- | ---- | ---- | ------------- | 556| name | string | 否 | 否 | 事件名称。 | 557| appEventInfos | Array<[AppEventInfo](#appeventinfo)> | 否 | 否 | 事件对象集合。 | 558 559 560## hiAppEvent.write 561 562write(info: AppEventInfo, callback: AsyncCallback<void>): void 563 564应用事件打点方法，将AppEventInfo类型的事件进行存储，使用callback方式作为异步回调。通过此接口写入的事件对象是开发者自定义的对象，为了避免与系统事件产生冲突混淆，不建议写入系统事件（[Event](#hiappeventevent)中定义的系统事件名称常量）。此接口写入的事件可通过订阅事件观察者（[addWatcher](#hiappeventaddwatcher)）进行订阅。 565 566**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 567 568**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 569 570**参数：** 571 572| 参数名 | 类型 | 必填 | 说明 | 573| -------- | ------------------------------ | ---- | -------------- | 574| info | [AppEventInfo](#appeventinfo) | 是 | 应用事件对象。其内部定义的事件名称建议避免与[Event](#hiappeventevent)中定义的系统事件名称常量产生冲突。 | 575| callback | AsyncCallback<void> | 是 | 打点回调函数。 | 576 577**错误码：** 578 579以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[应用事件打点错误码](errorcode-hiappevent.md)。 580 581| 错误码ID | 错误信息 | 582| -------- | --------------------------------------------- | 583| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 584| 11100001 | Function disabled. Possible caused by the param disable in ConfigOption is true. | 585| 11101001 | Invalid event domain. Possible causes: 1. Contain invalid characters; 2. Length is invalid. | 586| 11101002 | Invalid event name. Possible causes: 1. Contain invalid characters; 2. Length is invalid. | 587| 11101003 | Invalid number of event parameters. Possible caused by the number of parameters is over 32. | 588| 11101004 | Invalid string length of the event parameter. | 589| 11101005 | Invalid event parameter name. Possible causes: 1. Contain invalid characters; 2. Length is invalid. | 590| 11101006 | Invalid array length of the event parameter. | 591 592> **说明：** 593> 594> write接口涉及I/O操作，执行时间通常在毫秒级别。因此，开发者应根据实际业务需求，确定该接口是在主线程还是在子线程中调用。 595> 596> 可参考[多线程并发概述](../../arkts-utils/multi-thread-concurrency-overview.md)，以实现在子线程中调用接口。 597 598**示例：** 599 600```ts 601import { BusinessError } from '@kit.BasicServicesKit'; 602import { hilog } from '@kit.PerformanceAnalysisKit'; 603 604let eventParams: Record<string, number | string> = { 605 "int_data": 100, 606 "str_data": "strValue", 607}; 608 609// 应用事件打点，使用callback方式作为异步回调 610hiAppEvent.write({ 611 domain: "test_domain", 612 name: "test_event", 613 eventType: hiAppEvent.EventType.FAULT, 614 params: eventParams, 615}, (err: BusinessError) => { 616 if (err) { 617 hilog.error(0x0000, 'hiAppEvent', `code: ${err.code}, message: ${err.message}`); 618 return; 619 } 620 hilog.info(0x0000, 'hiAppEvent', `success to write event`); 621}); 622``` 623 624 625## hiAppEvent.write 626 627write(info: AppEventInfo): Promise<void> 628 629应用事件打点方法，将AppEventInfo类型的事件进行存储，使用Promise方式作为异步回调。通过此接口写入的事件对象是开发者自定义的对象，为了避免与系统事件产生冲突混淆，不建议写入系统事件（[Event](#hiappeventevent)中定义的系统事件名称常量）。此接口写入的事件可通过订阅事件观察者（[addWatcher](#hiappeventaddwatcher)）进行处理。 630 631**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 632 633**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 634 635**参数：** 636 637| 参数名 | 类型 | 必填 | 说明 | 638| ------ | ------------------------------ | ---- | -------------- | 639| info | [AppEventInfo](#appeventinfo) | 是 | 应用事件对象。其中的事件名称建议避免与[Event](#hiappeventevent)中定义的系统事件名称常量冲突混淆。 | 640 641**返回值：** 642 643| 类型 | 说明 | 644| ------------------- | ------------- | 645| Promise<void> | Promise对象。无返回结果的Promise对象。 | 646 647**错误码：** 648 649以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[应用事件打点错误码](errorcode-hiappevent.md)。 650 651| 错误码ID | 错误信息 | 652| -------- | --------------------------------------------- | 653| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 654| 11100001 | Function disabled. Possible caused by the param disable in ConfigOption is true. | 655| 11101001 | Invalid event domain. Possible causes: 1. Contain invalid characters; 2. Length is invalid. | 656| 11101002 | Invalid event name. Possible causes: 1. Contain invalid characters; 2. Length is invalid. | 657| 11101003 | Invalid number of event parameters. Possible caused by the number of parameters is over 32. | 658| 11101004 | Invalid string length of the event parameter. | 659| 11101005 | Invalid event parameter name. Possible causes: 1. Contain invalid characters; 2. Length is invalid. | 660| 11101006 | Invalid array length of the event parameter. | 661 662> **说明：** 663> 664> write接口涉及I/O操作，执行时间通常在毫秒级别。因此，开发者应根据实际业务需求，确定该接口是在主线程还是在子线程中调用。 665> 666> 可参考[多线程并发概述](../../arkts-utils/multi-thread-concurrency-overview.md)，以实现在子线程中调用接口。 667 668**示例：** 669 670```ts 671import { BusinessError } from '@kit.BasicServicesKit'; 672import { hilog } from '@kit.PerformanceAnalysisKit'; 673 674let eventParams: Record<string, number | string> = { 675 "int_data": 100, 676 "str_data": "strValue", 677}; 678 679// 应用事件打点，使用Promise方式作为异步回调 680hiAppEvent.write({ 681 domain: "test_domain", 682 name: "test_event", 683 eventType: hiAppEvent.EventType.FAULT, 684 params: eventParams, 685}).then(() => { 686 hilog.info(0x0000, 'hiAppEvent', `success to write event`); 687}).catch((err: BusinessError) => { 688 hilog.error(0x0000, 'hiAppEvent', `code: ${err.code}, message: ${err.message}`); 689}); 690``` 691 692 693## hiAppEvent.addProcessor<sup>11+</sup> 694 695addProcessor(processor: Processor): number 696 697添加数据处理者配置信息，用于配置处理者接收的事件名等信息。事件发生后处理者可以接收事件。 698 699该接口为同步接口，包含耗时操作。为了确保性能，建议使用[addProcessorFromConfig](#hiappeventaddprocessorfromconfig20)异步接口或者交由子线程执行。 700 701**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 702 703**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 704 705**参数：** 706 707| 参数名 | 类型 | 必填 | 说明 | 708| --------- | ---------- | ---- | ------------- | 709| processor | [Processor](#processor11) | 是 | 上报事件的数据处理者。| 710 711**返回值：** 712 713| 类型 | 说明 | 714| ------ | ---------------------- | 715| number | 所添加上报事件数据处理者的ID，标识唯一数据处理者，可用于移除数据处理者。 添加失败返回-1，添加成功返回大于0的值。 | 716 717**错误码：** 718 719以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 720 721| 错误码ID | 错误信息 | 722| ------- | ----------------- | 723| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 724 725**示例：** 726 727```ts 728import { hilog } from '@kit.PerformanceAnalysisKit'; 729 730try { 731 let processor: hiAppEvent.Processor = { 732 name: 'analytics_demo' 733 }; 734 let id: number = hiAppEvent.addProcessor(processor); 735 hilog.info(0x0000, 'hiAppEvent', `addProcessor event was successful, id=${id}`); 736} catch (error) { 737 hilog.error(0x0000, 'hiAppEvent', `failed to addProcessor event, code=${error.code}`); 738} 739``` 740 741 742## hiAppEvent.addProcessorFromConfig<sup>20+</sup> 743 744addProcessorFromConfig(processorName: string, configName?: string): Promise<number> 745 746<!--RP1--> 747 748添加数据处理者配置信息，通过配置文件配置处理者接收的事件名等信息，事件发生后处理者可以接收事件，使用Promise异步回调。 749<!--RP1End--> 750 751**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 752 753**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 754 755**参数：** 756 757| 参数名 | 类型 | 必填 | 说明 | 758| --------- | ---------- | ---- | ------------- | 759| processorName | string | 是 | <!--RP2-->数据处理者的名称。名称只能包含大小写字母、数字、下划线和$，不能以数字开头，长度非空且不超过256个字符。<!--RP2End-->| 760| configName | string | 否 | <!--RP3-->数据处理者的配置名称，支持从配置文件中加载对应配置，默认为“SDK_OCG”。只能包含大小写字母、数字、下划线和$，不能以数字开头，长度非空且不超过256个字符。<!--RP3End-->| 761 762**返回值：** 763 764| 类型 | 说明 | 765| ------ | ---------------------- | 766| Promise<number> | Promise对象。返回添加的事件数据处理者的唯一ID，可用于移除该数据处理者。 添加失败返回11105001错误码。 | 767 768**错误码：** 769 770以下错误码的详细介绍请参见[应用事件打点错误码](errorcode-hiappevent.md)。 771 772| 错误码ID | 错误信息 | 773| ------- | ----------------- | 774| 11105001 | Invalid parameter value. Possible causes: 1. Incorrect parameter length; 2. Incorrect parameter format. | 775 776**示例：** 777 778```ts 779import { BusinessError } from '@kit.BasicServicesKit'; 780import { hilog } from '@kit.PerformanceAnalysisKit'; 781 782hiAppEvent.addProcessorFromConfig("test_name").then((processorId) => { 783 hilog.info(0x0000, 'hiAppEvent', `Succeeded in adding processor from config, processorId=${processorId}`); 784}).catch((err: BusinessError) => { 785 hilog.error(0x0000, 'hiAppEvent', `Failed to add processor from config, code: ${err.code}, message: ${err.message}`); 786}); 787``` 788 789 790## hiAppEvent.removeProcessor<sup>11+</sup> 791 792removeProcessor(id: number): void 793 794移除上报事件的数据处理者。 795 796**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 797 798**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 799 800**参数：** 801 802| 参数名 | 类型 | 必填 | 说明 | 803| ------| ------- | ---- | --------------------------- | 804| id | number | 是 | 上报事件数据处理者ID。值大于0。由调用[addProcessor](#hiappeventaddprocessor11)或[addProcessorFromConfig](#hiappeventaddprocessorfromconfig20)接口返回值所得。| 805 806**错误码：** 807 808以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 809 810| 错误码ID | 错误信息 | 811| ------- | ----------------- | 812| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 813 814**示例：** 815 816```ts 817import { hilog } from '@kit.PerformanceAnalysisKit'; 818 819try { 820 let processor: hiAppEvent.Processor = { 821 name: 'analytics_demo' 822 }; 823 let id: number = hiAppEvent.addProcessor(processor); 824 // 根据添加数据处理者返回的标识id移除特定数据处理者 825 hiAppEvent.removeProcessor(id); 826} catch (error) { 827 hilog.error(0x0000, 'hiAppEvent', `failed to removeProcessor event, code=${error.code}`); 828} 829``` 830 831 832## hiAppEvent.setUserId<sup>11+</sup> 833 834setUserId(name: string, value: string): void 835 836设置用户ID值。用于在配置[Processor](#processor11)数据处理者时进行关联。 837 838**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 839 840**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 841 842**参数：** 843 844| 参数名 | 类型 | 必填 | 说明 | 845| --------- | ------------------------- | ---- | ------------- | 846| name | string | 是 | 用户ID的key。只能包含大小写字母、数字、下划线和 $，不能以数字开头，长度非空且不超过256个字符。 | 847| value | string | 是 | 用户ID的值。长度不超过256，当值为null或空字符串时，则清除用户ID。 | 848 849**错误码：** 850 851以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 852 853| 错误码ID | 错误信息 | 854| ------- | ----------------- | 855| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 856 857**示例：** 858 859```ts 860import { hilog } from '@kit.PerformanceAnalysisKit'; 861 862try { 863 hiAppEvent.setUserId('key', 'value'); 864} catch (error) { 865 hilog.error(0x0000, 'hiAppEvent', `failed to setUserId event, code=${error.code}`); 866} 867``` 868 869 870## hiAppEvent.getUserId<sup>11+</sup> 871 872getUserId(name: string): string 873 874获取通过setUserId接口设置的value值。 875 876**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 877 878**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 879 880**参数：** 881 882| 参数名 | 类型 | 必填 | 说明 | 883| --------- | ----------------------- | ---- | ---------- | 884| name | string | 是 | 用户ID的key。只能包含大小写字母、数字、下划线和 $，不能以数字开头，长度非空且不超过256个字符。| 885 886**返回值：** 887 888| 类型 | 说明 | 889| ------ | ------------------------------- | 890| string | 用户ID的值。没有查到返回空字符串。 | 891 892**错误码：** 893 894以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 895 896| 错误码ID | 错误信息 | 897| ------- | ----------------- | 898| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 899 900**示例：** 901 902```ts 903import { hilog } from '@kit.PerformanceAnalysisKit'; 904 905hiAppEvent.setUserId('key', 'value'); 906try { 907 let value: string = hiAppEvent.getUserId('key'); 908 hilog.info(0x0000, 'hiAppEvent', `getUserId event was successful, userId=${value}`); 909} catch (error) { 910 hilog.error(0x0000, 'hiAppEvent', `failed to getUserId event, code=${error.code}`); 911} 912``` 913 914 915## hiAppEvent.setUserProperty<sup>11+</sup> 916 917setUserProperty(name: string, value: string): void 918 919设置用户属性值。用于在配置[Processor](#processor11)数据处理者时进行关联。 920 921**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 922 923**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 924 925**参数：** 926 927| 参数名 | 类型 | 必填 | 说明 | 928| --------- | ------------------------- | ---- | -------------- | 929| name | string | 是 | 用户属性的key。只能包含大小写字母、数字、下划线和 $，不能以数字开头，长度非空且不超过256个字符。 | 930| value | string | 是 | 用户属性的值。长度不超过1024，当值为null或空字符串时，则清除用户属性。 | 931 932**错误码：** 933 934以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 935 936| 错误码ID | 错误信息 | 937| ------- | ----------------- | 938| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 939 940**示例：** 941 942```ts 943import { hilog } from '@kit.PerformanceAnalysisKit'; 944 945try { 946 hiAppEvent.setUserProperty('key', 'value'); 947} catch (error) { 948 hilog.error(0x0000, 'hiAppEvent', `failed to setUserProperty event, code=${error.code}`); 949} 950``` 951 952 953## hiAppEvent.getUserProperty<sup>11+</sup> 954 955getUserProperty(name: string): string 956 957获取通过setUserProperty接口设置的value值。 958 959**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 960 961**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 962 963**参数：** 964 965| 参数名 | 类型 | 必填 | 说明 | 966| --------- | ----------------------- | ---- | ---------- | 967| name | string | 是 | 用户属性的key。只能包含大小写字母、数字、下划线和 $，不能以数字开头，长度非空且不超过256个字符。| 968 969**返回值：** 970 971| 类型 | 说明 | 972| ------ | -------------------------------- | 973| string | 用户属性的值。没有查到返回空字符串。 | 974 975**错误码：** 976 977以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 978 979| 错误码ID | 错误信息 | 980| ------- | ----------------- | 981| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 982 983**示例：** 984 985```ts 986import { hilog } from '@kit.PerformanceAnalysisKit'; 987 988hiAppEvent.setUserProperty('key', 'value'); 989try { 990 let value: string = hiAppEvent.getUserProperty('key'); 991 hilog.info(0x0000, 'hiAppEvent', `getUserProperty event was successful, userProperty=${value}`); 992} catch (error) { 993 hilog.error(0x0000, 'hiAppEvent', `failed to getUserProperty event, code=${error.code}`); 994} 995``` 996 997 998## hiAppEvent.clearData 999 1000clearData(): void 1001 1002应用事件打点数据清理方法，将当前应用存储在本地的打点数据进行清除。 1003 1004**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1005 1006**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 1007 1008**示例：** 1009 1010```ts 1011hiAppEvent.clearData(); 1012``` 1013 1014 1015## hiAppEvent.configure 1016 1017configure(config: ConfigOption): void 1018 1019应用事件打点配置方法，支持配置打点开关和目录存储配额大小。 1020 1021**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1022 1023**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 1024 1025**参数：** 1026 1027| 参数名 | 类型 | 必填 | 说明 | 1028| ------ | ----------------------------- | ---- | ------------------------ | 1029| config | [ConfigOption](#configoption) | 是 | 应用事件打点配置项对象。 | 1030 1031**错误码：** 1032 1033以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[应用事件打点错误码](errorcode-hiappevent.md)。 1034 1035| 错误码ID | 错误信息 | 1036| -------- | -------------------------------- | 1037| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1038| 11103001 | Invalid max storage quota value. Possible caused by incorrectly formatted. | 1039 1040**示例：** 1041 1042```ts 1043// 配置打点开关为关闭状态 1044let config1: hiAppEvent.ConfigOption = { 1045 disable: true, 1046}; 1047hiAppEvent.configure(config1); 1048 1049// 配置文件目录存储配额为100M 1050let config2: hiAppEvent.ConfigOption = { 1051 maxStorage: '100M', 1052}; 1053hiAppEvent.configure(config2); 1054``` 1055 1056 1057## ConfigOption 1058 1059提供对应用事件打点功能的配置选项。 1060 1061**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1062 1063**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 1064 1065| 名称 | 类型 | 只读 | 可选 | 说明 | 1066| ---------- | ------- | ---- | ---- | ------------------------------------------------------------ | 1067| disable | boolean | 否 | 是 | 打点功能开关，默认值为false。true：关闭打点功能，false：开启打点功能。 | 1068| maxStorage | string | 否 | 是 | 打点数据存放目录的配额大小，默认值为“10M”。建议配额大小不超过10M，配额过大可能会影响接口效率。<br>在目录大小超出配额后，下次打点会触发对目录的清理操作：按从旧到新的顺序逐个删除打点数据文件，直到目录大小不超出配额时结束。<br>配额值字符串规格如下：<br>- 配额值字符串只由数字字符和大小单位字符（单位字符支持[b\|k\|kb\|m\|mb\|g\|gb\|t\|tb]，不区分大小写）构成。<br>- 配额值字符串必须以数字开头，后面可以选择不传单位字符（默认使用byte作为单位），或者以单位字符结尾。 | 1069 1070 1071## Processor<sup>11+</sup> 1072 1073可以上报事件的数据处理者对象。用于事件的上报和管理，开发者可自定义数据处理配置，满足不同的数据处理需求。 1074 1075**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 1076 1077| 名称 | 类型 | 只读 | 可选 | 说明 | 1078| ------------------- | ----------------------- | ---- | ---- | ---------------------------------------------------------------------------------------------------------- | 1079| name | string | 否 | 否 | 数据处理者的名称。名称只能包含大小写字母、数字、下划线和 $，不能以数字开头，长度非空且不超过256个字符。<br>**原子化服务API：** 从API version 11开始，该参数支持在原子化服务中使用。 | 1080| debugMode | boolean | 否 | 是 | 是否开启debug模式，默认值为false。配置值为true表示开启debug模式，false表示不开启debug模式。<br>**原子化服务API：** 从API version 11开始，该参数支持在原子化服务中使用。 | 1081| routeInfo | string | 否 | 是 | 服务器位置信息，默认为空字符串。传入字符串长度不能超过8KB，超过时会被置为默认值。<br>**原子化服务API：** 从API version 11开始，该参数支持在原子化服务中使用。 | 1082| appId | string | 否 | 是 | 应用id，默认为空字符串。传入字符串长度不能超过8KB，超过时会被置为默认值。<br>**原子化服务API：** 从API version 11开始，该参数支持在原子化服务中使用。 | 1083| onStartReport | boolean | 否 | 是 | 数据处理者在启动时是否上报事件，默认值为false。配置值为true表示上报事件，false表示不上报事件。<br>**原子化服务API：** 从API version 11开始，该参数支持在原子化服务中使用。 | 1084| onBackgroundReport | boolean | 否 | 是 | 当应用程序进入后台时是否上报事件，默认值为false。配置值为true表示上报事件，false表示不上报事件。<br>**原子化服务API：** 从API version 11开始，该参数支持在原子化服务中使用。 | 1085| periodReport | number | 否 | 是 | 事件定时上报时间周期，单位为秒。传入数值必须大于或等于0，小于0时会被置为默认值0，不进行定时上报。<br>**原子化服务API：** 从API version 11开始，该参数支持在原子化服务中使用。 | 1086| batchReport | number | 否 | 是 | 事件上报阈值，当事件条数达到阈值时上报事件。传入数值必须大于0且小于1000，不在数值范围内会被置为默认值0，不进行上报。<br>**原子化服务API：** 从API version 11开始，该参数支持在原子化服务中使用。 | 1087| userIds | string[] | 否 | 是 | 数据处理者可以上报的用户ID的name数组。name对应[setUserId](#hiappeventsetuserid11)接口的name参数。默认为空数组。<br>**原子化服务API：** 从API version 11开始，该参数支持在原子化服务中使用。 | 1088| userProperties | string[] | 否 | 是 | 数据处理者可以上报的用户属性的name数组。name对应[setUserProperty](#hiappeventsetuserproperty11)接口的name参数。默认为空数组。<br>**原子化服务API：** 从API version 11开始，该参数支持在原子化服务中使用。 | 1089| eventConfigs | [AppEventReportConfig](#appeventreportconfig11)[] | 否 | 是 | 数据处理者可以上报的事件描述配置数组。默认为空数组。<br>**原子化服务API：** 从API version 11开始，该参数支持在原子化服务中使用。 | 1090| configId<sup>12+</sup> | number | 否 | 是 | 数据处理者配置id。传入数值必须大于或等于0，小于0时会被置为默认值0。传入的值大于0时，与数据处理者的名称name共同唯一标识数据处理者。<br>**原子化服务API：** 从API version 12开始，该参数支持在原子化服务中使用。 | 1091| customConfigs<sup>12+</sup> | Record\<string, string> | 否 | 是 | 自定义扩展参数。传入参数名和参数值不符合规格会默认不配置扩展参数，其规格定义如下：<br>- 参数名为string类型，首字符必须为字母字符或$字符，中间字符必须为数字字符、字母字符或下划线字符，结尾字符必须为数字字符或字母字符，长度非空且不超过32个字符。<br>- 参数值为string类型，参数值长度需在1024个字符以内。<br>- 参数个数需在32个以内。<br>**原子化服务API：** 从API version 12开始，该参数支持在原子化服务中使用。 | 1092| configName<sup>20+</sup> | string | 否 | 是 | <!--RP4-->数据处理者的配置名称，支持从配置文件中加载对应配置，默认为空。只能包含大小写字母、数字、下划线和$，不能以数字开头，长度非空且不超过256个字符。<br>**原子化服务API：** 从API version 20开始，该参数支持在原子化服务中使用。<!--RP4End-->| 1093 1094 1095## AppEventReportConfig<sup>11+</sup> 1096 1097数据处理者可以上报事件的描述配置。 1098 1099**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1100 1101**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 1102 1103| 名称 | 类型 | 只读 | 可选 | 说明 | 1104| ----------- | ------- | ---- | ---- | ------------------------------------------------------------ | 1105| domain | string | 否 | 是 | 事件领域。默认为空字符串，事件领域名称支持数字、字母、下划线字符，需要以字母开头且不能以下划线结尾，长度非空且不超过32个字符。 | 1106| name | string | 否 | 是 | 事件名称。默认为空字符串，首字符必须为字母字符或$字符，中间字符必须为数字字符、字母字符或下划线字符，结尾字符必须为数字字符或字母字符，长度非空且不超过48个字符。 | 1107| isRealTime | boolean | 否 | 是 | 是否实时上报事件。默认值为false，配置值为true表示实时上报事件，false表示不实时上报事件。 | 1108 1109 1110## ParamType<sup>12+</sup> 1111 1112type ParamType = number | string | boolean | Array<string> 1113 1114事件自定义参数值的类型。 1115 1116**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1117 1118**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 1119 1120| 类型 | 说明 | 1121|--------------------------|-------------------| 1122| number | 表示值类型为数字。 | 1123| string | 表示值类型为字符串。 | 1124| boolean | 表示值类型为布尔值。 | 1125| Array<string> | 表示值类型为字符串类型的数组。 | 1126 1127 1128## EventType 1129 1130事件类型枚举。 1131 1132**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1133 1134**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 1135 1136| 名称 | 值 | 说明 | 1137| --------- | ---- | -------------- | 1138| FAULT | 1 | 故障类型事件。 | 1139| STATISTIC | 2 | 统计类型事件。 | 1140| SECURITY | 3 | 安全类型事件。 | 1141| BEHAVIOR | 4 | 行为类型事件。 | 1142 1143 1144## hiAppEvent.domain<sup>11+</sup> 1145 1146提供领域名称常量。 1147 1148**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1149 1150**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 1151 1152| 名称 | 类型 | 只读 | 说明 | 1153| --- | ------ | ------ | ---------- | 1154| OS | string | 是 | 系统领域。 | 1155 1156 1157## hiAppEvent.event 1158 1159提供事件名称常量。包含系统事件名称常量和应用事件名称常量，其中应用事件名称常量是为开发者在调用[Write](#hiappeventwrite-1)接口进行应用事件打点时预留的可选自定义事件名称。 1160 1161**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 1162 1163| 名称 | 类型 | 只读 | 说明 | 1164| ------------------------- | ------ | ------ | -------------------- | 1165| USER_LOGIN | string | 是 | 用户登录事件。预留的应用事件名称常量。<br>**原子化服务API：** 从API version 11开始，该参数支持在原子化服务中使用。 | 1166| USER_LOGOUT | string | 是 | 用户登出事件。预留的应用事件名称常量。<br>**原子化服务API：** 从API version 11开始，该参数支持在原子化服务中使用。 | 1167| DISTRIBUTED_SERVICE_START | string | 是 | 分布式服务启动事件。预留的应用事件名称常量。<br>**原子化服务API：** 从API version 11开始，该参数支持在原子化服务中使用。 | 1168| APP_CRASH<sup>11+</sup> | string | 是 | 应用崩溃事件。系统事件名称常量。<br>**原子化服务API：** 从API version 11开始，该参数支持在原子化服务中使用。 | 1169| APP_FREEZE<sup>11+</sup> | string | 是 | 应用冻屏事件。系统事件名称常量。<br>**原子化服务API：** 从API version 11开始，该参数支持在原子化服务中使用。 | 1170| APP_LAUNCH<sup>12+</sup> | string | 是 | 应用启动耗时事件。系统事件名称常量。<br>**原子化服务API：** 从API version 12开始，该参数支持在原子化服务中使用。 | 1171| SCROLL_JANK<sup>12+</sup> | string | 是 | 应用滑动丢帧事件。系统事件名称常量。<br>**原子化服务API：** 从API version 12开始，该参数支持在原子化服务中使用。 | 1172| CPU_USAGE_HIGH<sup>12+</sup> | string | 是 | 应用CPU高负载事件。系统事件名称常量。<br>**原子化服务API：** 从API version 12开始，该参数支持在原子化服务中使用。 | 1173| BATTERY_USAGE<sup>12+</sup> | string | 是 | 应用24h功耗器件分解统计事件。系统事件名称常量。<br>**原子化服务API：** 从API version 12开始，该参数支持在原子化服务中使用。 | 1174| RESOURCE_OVERLIMIT<sup>12+</sup> | string | 是 | 应用资源泄漏事件。系统事件名称常量。<br>**原子化服务API：** 从API version 12开始，该参数支持在原子化服务中使用。 | 1175| ADDRESS_SANITIZER<sup>12+</sup> | string | 是 | 应用地址越界事件。系统事件名称常量。<br>**原子化服务API：** 从API version 12开始，该参数支持在原子化服务中使用。 | 1176| MAIN_THREAD_JANK<sup>12+</sup> | string | 是 | 应用主线程超时事件。系统事件名称常量。<br>**原子化服务API：** 从API version 12开始，该参数支持在原子化服务中使用。 | 1177| APP_KILLED<sup>20+</sup> | string | 是 | 应用查杀事件。系统事件名称常量。<br>**原子化服务API：** 从API version 20开始，该参数支持在原子化服务中使用。 | 1178 1179 1180## hiAppEvent.param 1181 1182提供参数名称常量。 1183 1184**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1185 1186**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 1187 1188| 名称 | 类型 | 只读 | 说明 | 1189| ------------------------------- | ------ | ------ | ------------------ | 1190| USER_ID | string | 是 | 用户自定义ID。 | 1191| DISTRIBUTED_SERVICE_NAME | string | 是 | 分布式服务名称。 | 1192| DISTRIBUTED_SERVICE_INSTANCE_ID | string | 是 | 分布式服务实例ID。 | 1193