1# @ohos.hiviewdfx.hiAppEvent (Application Event Logging) 2 3The **hiAppEvent** module provides application event-related functions, including flushing application events to a disk, querying and clearing application events, and customizing application event logging configuration. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9 10## Modules to Import 11 12```ts 13import hiAppEvent from '@ohos.hiviewdfx.hiAppEvent'; 14``` 15 16## hiAppEvent.addProcessor<sup>11+</sup> 17 18addProcessor(processor: Processor): number 19 20Adds a data processor for migrating events to the cloud. The implementation of data processors can be preset in the device. You can set attributes of the data processor based on its constraints. 21 22**System capability**: SystemCapability.HiviewDFX.HiAppEvent 23 24**Parameters** 25 26| Name | Type | Mandatory| Description | 27| --------- | ---------- | ---- | ------------- | 28| processor | [Processor](#processor11) | Yes | Data processor.| 29 30**Return value** 31 32| Type | Description | 33| ------ | ---------------------- | 34| number | ID of the data processor to be added. If the operation fails, **-1** is returned. If the operation is successful, a value greater than **0** is returned.| 35 36**Error codes** 37 38| ID| Error Message | 39| ------- | ----------------- | 40| 401 | Parameter error. | 41 42**Example** 43 44```ts 45import hilog from '@ohos.hilog'; 46 47try { 48 let processor: hiAppEvent.Processor = { 49 name: 'analytics_demo' 50 }; 51 let id: number = hiAppEvent.addProcessor(processor); 52 hilog.info(0x0000, 'hiAppEvent', `addProcessor event was successful, id=${id}`); 53} catch (error) { 54 hilog.error(0x0000, 'hiAppEvent', `failed to addProcessor event, code=${error.code}`); 55} 56``` 57 58## Processor<sup>11+</sup> 59 60Defines a data processor for reporting events. 61 62**System capability**: SystemCapability.HiviewDFX.HiAppEvent 63 64| Name | Type | Mandatory| Description | 65| ------------------- | ----------------------- | ---- | ---------------------------------------------------------------------------------------------------------- | 66| name | string | Yes | Name of a data processor. The value is string that contains a maximum of 256 characters, including digits (0 to 9), letters (a to z), underscore (_), and dollar sign ($). It must not start with a digit. | 67| debugMode | boolean | No | Whether to enable the debug mode. The default value is **false**. The value **true** means to enable the debugging mode, and the value **false** means the opposite. | 68| routeInfo | string | No | Server location information. It is left empty by default. The length of the input string cannot exceed 8 KB. If the length exceeds 8 KB, the default value is used. | 69| appId | string | No | Application ID. It is left empty by default. The length of the input string cannot exceed 8 KB. If the length exceeds 8 KB, the default value is used.| 70| onStartReport | boolean | No | Whether to report an event when the data processor starts. The default value is **false**. The value **true** means to report events, and the value **false** means the opposite. | 71| onBackgroundReport | boolean | No | Whether to report an event when an application switches to the background. The default value is **false**. The value **true** means to report events, and the value **false** means the opposite. | 72| periodReport | number | No | Interval for event reporting, in seconds. The input value must be greater than or equal to **0**. If the input value is less than **0**, the default value **0** is used and periodic reporting is not performed. | 73| batchReport | number | No | Event reporting threshold. When the number of events reaches the threshold, an event is reported. The value must be greater than **0** and less than **1000**. If the value is not within the range, the default value **0** is used and no events are reported. | 74| userIds | string[] | No | Name array of user IDs that can be reported by the data processor. **name** corresponds to the **name** parameter of the [setUserId](#hiappeventsetuserid11) API. | 75| userProperties | string[] | No | Name array of user properties that can be reported by the data processor. **name** corresponds to the **name** parameter of the [setUserProperty](#hiappeventsetuserproperty11) API. | 76| eventConfigs | [AppEventReportConfig](#appeventreportconfig11)[] | No | Array of events that can be reported by the data processor. | 77 78## AppEventReportConfig<sup>11+</sup> 79 80Description of events that can be reported by the data processor. 81 82**System capability**: SystemCapability.HiviewDFX.HiAppEvent 83 84| Name | Type | Mandatory| Description | 85| ----------- | ------- | ---- | ------------------------------------------------------------ | 86| domain | string | No | Event domain. The value is a string of up to 16 characters, including digits (0 to 9), letters (a to z), and underscores (\_). It must start with a lowercase letter and cannot end with an underscore (_).| 87| name | string | No | Event name. The value is string that contains a maximum of 48 characters, including digits (0 to 9), letters (a to z), underscore (_), and dollar sign ($). It must start with a letter or dollar sign ($) and end with a digit or letter.| 88| isRealTime | boolean | No | Whether to report events in real time. The value **true** means to report events, and the value **false** means the opposite.| 89 90## hiAppEvent.removeProcessor<sup>11+</sup> 91 92removeProcessor(id: number): void 93 94Removes a data processor. 95 96**System capability**: SystemCapability.HiviewDFX.HiAppEvent 97 98**Parameters** 99 100| Name| Type | Mandatory| Description | 101| ------| ------- | ---- | --------------------------- | 102| id | number | Yes | ID of a data processor. The value must be greater than **0**.| 103 104**Error codes** 105 106| ID| Error Message | 107| ------- | ----------------- | 108| 401 | Parameter error. | 109 110**Example** 111 112```ts 113import hilog from '@ohos.hilog'; 114 115try { 116 let processor: hiAppEvent.Processor = { 117 name: 'analytics_demo' 118 }; 119 let id: number = hiAppEvent.addProcessor(processor); 120 hiAppEvent.removeProcessor(id); 121} catch (error) { 122 hilog.error(0x0000, 'hiAppEvent', `failed to removeProcessor event, code=${error.code}`); 123} 124``` 125 126## hiAppEvent.write 127 128write(info: AppEventInfo, callback: AsyncCallback<void>): void 129 130Writes events to the event file of the current day through **AppEventInfo** objects. This API uses an asynchronous callback to return the result. 131 132**System capability**: SystemCapability.HiviewDFX.HiAppEvent 133 134**Parameters** 135 136| Name | Type | Mandatory| Description | 137| -------- | ------------------------------ | ---- | -------------- | 138| info | [AppEventInfo](#appeventinfo) | Yes | Application event object.| 139| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 140 141**Error codes** 142 143For details about the error codes, see [Application Event Logging Error Codes](../errorcodes/errorcode-hiappevent.md). 144 145| ID| Error Message | 146| -------- | --------------------------------------------- | 147| 11100001 | Function is disabled. | 148| 11101001 | Invalid event domain. | 149| 11101002 | Invalid event name. | 150| 11101003 | Invalid number of event parameters. | 151| 11101004 | Invalid string length of the event parameter. | 152| 11101005 | Invalid event parameter name. | 153| 11101006 | Invalid array length of the event parameter. | 154 155**Example** 156 157```ts 158import { BusinessError } from '@ohos.base'; 159import hilog from '@ohos.hilog'; 160 161let eventParams: Record<string, number | string> = { 162 "int_data": 100, 163 "str_data": "strValue", 164}; 165hiAppEvent.write({ 166 domain: "test_domain", 167 name: "test_event", 168 eventType: hiAppEvent.EventType.FAULT, 169 params: eventParams, 170}, (err: BusinessError) => { 171 if (err) { 172 hilog.error(0x0000, 'hiAppEvent', `code: ${err.code}, message: ${err.message}`); 173 return; 174 } 175 hilog.info(0x0000, 'hiAppEvent', `success to write event`); 176}); 177``` 178 179## hiAppEvent.write 180 181write(info: AppEventInfo): Promise<void> 182 183Writes events to the event file of the current day through **AppEventInfo** objects. This API uses a promise to return the result. 184 185**System capability**: SystemCapability.HiviewDFX.HiAppEvent 186 187**Parameters** 188 189| Name| Type | Mandatory| Description | 190| ------ | ------------------------------ | ---- | -------------- | 191| info | [AppEventInfo](#appeventinfo) | Yes | Application event object.| 192 193**Return value** 194 195| Type | Description | 196| ------------------- | ------------- | 197| Promise<void> | Promise used to return the result.| 198 199**Error codes** 200 201For details about the error codes, see [Application Event Logging Error Codes](../errorcodes/errorcode-hiappevent.md). 202 203| ID| Error Message | 204| -------- | --------------------------------------------- | 205| 11100001 | Function is disabled. | 206| 11101001 | Invalid event domain. | 207| 11101002 | Invalid event name. | 208| 11101003 | Invalid number of event parameters. | 209| 11101004 | Invalid string length of the event parameter. | 210| 11101005 | Invalid event parameter name. | 211| 11101006 | Invalid array length of the event parameter. | 212 213**Example** 214 215```ts 216import { BusinessError } from '@ohos.base'; 217import hilog from '@ohos.hilog'; 218 219let eventParams: Record<string, number | string> = { 220 "int_data": 100, 221 "str_data": "strValue", 222}; 223hiAppEvent.write({ 224 domain: "test_domain", 225 name: "test_event", 226 eventType: hiAppEvent.EventType.FAULT, 227 params: eventParams, 228}).then(() => { 229 hilog.info(0x0000, 'hiAppEvent', `success to write event`); 230}).catch((err: BusinessError) => { 231 hilog.error(0x0000, 'hiAppEvent', `code: ${err.code}, message: ${err.message}`); 232}); 233``` 234 235## AppEventInfo 236 237Defines parameters for an **AppEventInfo** object. 238 239**System capability**: SystemCapability.HiviewDFX.HiAppEvent 240 241| Name | Type | Mandatory| Description | 242| --------- | ----------------------- | ---- | ------------------------------------------------------------ | 243| domain | string | Yes | Event domain. The value is a string of up to 16 characters, including digits (0 to 9), letters (a to z), and underscores (\_). It must start with a lowercase letter and cannot end with an underscore (_).| 244| name | string | Yes | Event name. The value is string that contains a maximum of 48 characters, including digits (0 to 9), letters (a to z), underscore (_), and dollar sign ($). It must start with a letter or dollar sign ($) and end with a digit or letter.| 245| eventType | [EventType](#eventtype) | Yes | Event type. | 246| params | object | Yes | Event parameter object, which consists of a parameter name and a parameter value. The specifications are as follows:<br>- A parameter name is a string that contains a maximum of 16 characters, including digits (0 to 9), letters (a to z), underscore (_), and dollar sign ($). It must start with a letter or dollar sign ($) and end with a digit or letter.<br>- The parameter value can be a string, number, boolean, or array. If the parameter value is a string, its maximum length is 8*1024 characters. If this limit is exceeded, excess characters will be discarded. If the parameter value is a number, the value must be within the range of **Number.MIN_SAFE_INTEGER** to **Number.MAX_SAFE_INTEGER**. Otherwise, uncertain values may be generated. If the parameter value is an array, the elements in the array must be of the same type, which can only be string, number, or boolean. In addition, the number of elements must be less than 100. If this limit is exceeded, excess elements will be discarded.<br>- The maximum number of parameters is 32. If this limit is exceeded, excess parameters will be discarded.| 247 248## hiAppEvent.configure 249 250configure(config: ConfigOption): void 251 252Configures the application event logging function, such as setting the event logging switch and maximum size of the directory that stores the event logging files. 253 254**System capability**: SystemCapability.HiviewDFX.HiAppEvent 255 256**Parameters** 257 258| Name| Type | Mandatory| Description | 259| ------ | ----------------------------- | ---- | ------------------------ | 260| config | [ConfigOption](#configoption) | Yes | Configuration items for application event logging.| 261 262**Error codes** 263 264For details about the error codes, see [Application Event Logging Error Codes](../errorcodes/errorcode-hiappevent.md). 265 266| ID| Error Message | 267| -------- | -------------------------------- | 268| 11103001 | Invalid max storage quota value. | 269 270**Example** 271 272```ts 273// Disable the event logging function. 274let config1: hiAppEvent.ConfigOption = { 275 disable: true, 276}; 277hiAppEvent.configure(config1); 278 279// Set the maximum size of the file storage directory to 100 MB. 280let config2: hiAppEvent.ConfigOption = { 281 maxStorage: '100M', 282}; 283hiAppEvent.configure(config2); 284``` 285 286## ConfigOption 287 288Provides configuration options for application event logging. 289 290**System capability**: SystemCapability.HiviewDFX.HiAppEvent 291 292| Name | Type | Mandatory| Description | 293| ---------- | ------- | ---- | ------------------------------------------------------------ | 294| disable | boolean | No | Whether to enable the event logging function. The default value is **false**. The value **true** means to disable the event logging function, and the value **false** means the opposite.| 295| maxStorage | string | No | Quota for the directory that stores event logging files. The default value is **10M**.<br>If the directory size exceeds the specified quota when application event logging is performed, event logging files in the directory will be cleared one by one based on the generation time to ensure that directory size does not exceed the quota.<br>The quota value must meet the following requirements:<br>- The quota value consists of only digits and a unit (which can be one of [b\|k\|kb\|m\|mb\|g\|gb\|t\|tb], which are case insensitive.)<br>- The quota value must start with a digit. You can determine whether to pass the unit. If the unit is left empty, **b** (that is, byte) is used by default.| 296 297## hiAppEvent.setUserId<sup>11+</sup> 298 299setUserId(name: string, value: string): void 300 301Sets a user ID. 302 303**System capability**: SystemCapability.HiviewDFX.HiAppEvent 304 305**Parameters** 306 307| Name | Type | Mandatory| Description | 308| --------- | ------------------------- | ---- | ------------- | 309| name | string | Yes | Key of a user ID. The value is string that contains a maximum of 256 characters, including digits (0 to 9), letters (a to z), underscore (_), and dollar sign ($). It must not start with a digit. | 310| value | string | Yes | Value of a user ID. It can contain a maximum of 256 characters. If the value is **null** or left empty, the user ID is cleared.| 311 312**Error codes** 313 314| ID| Error Message | 315| ------- | ----------------- | 316| 401 | Parameter error. | 317 318**Example** 319 320```ts 321import hilog from '@ohos.hilog'; 322 323try { 324 hiAppEvent.setUserId('key', 'value'); 325} catch (error) { 326 hilog.error(0x0000, 'hiAppEvent', `failed to setUserId event, code=${error.code}`); 327} 328``` 329 330## hiAppEvent.getUserId<sup>11+</sup> 331 332getUserId(name: string): string 333 334Obtains the value set by **setUserId**. 335 336**System capability**: SystemCapability.HiviewDFX.HiAppEvent 337 338**Parameters** 339 340| Name | Type | Mandatory| Description | 341| --------- | ----------------------- | ---- | ---------- | 342| name | string | Yes | Key of a user ID. The value is string that contains a maximum of 256 characters, including digits (0 to 9), letters (a to z), underscore (_), and dollar sign ($). It must not start with a digit.| 343 344**Return value** 345 346| Type | Description | 347| ------ | ------------------------------- | 348| string | Value of a user ID. If no user ID is found, an empty string is returned.| 349 350**Error codes** 351 352| ID| Error Message | 353| ------- | ----------------- | 354| 401 | Parameter error. | 355 356**Example** 357 358```ts 359import hilog from '@ohos.hilog'; 360 361hiAppEvent.setUserId('key', 'value'); 362try { 363 let value: string = hiAppEvent.getUserId('key'); 364 hilog.info(0x0000, 'hiAppEvent', `getUserId event was successful, userId=${value}`); 365} catch (error) { 366 hilog.error(0x0000, 'hiAppEvent', `failed to getUserId event, code=${error.code}`); 367} 368``` 369 370## hiAppEvent.setUserProperty<sup>11+</sup> 371 372setUserProperty(name: string, value: string): void 373 374Sets user properties. 375 376**System capability**: SystemCapability.HiviewDFX.HiAppEvent 377 378**Parameters** 379 380| Name | Type | Mandatory| Description | 381| --------- | ------------------------- | ---- | -------------- | 382| name | string | Yes | Key of a user property. The value is string that contains a maximum of 256 characters, including digits (0 to 9), letters (a to z), underscore (_), and dollar sign ($). It must not start with a digit. | 383| value | string | Yes | Value of a user property. It is a string that contains a maximum of 1024 characters. If the value is **null**, **undefine**, or **empty**, the user property is cleared. | 384 385**Error codes** 386 387| ID| Error Message | 388| ------- | ----------------- | 389| 401 | Parameter error. | 390 391**Example** 392 393```ts 394import hilog from '@ohos.hilog'; 395 396try { 397 hiAppEvent.setUserProperty('key', 'value'); 398} catch (error) { 399 hilog.error(0x0000, 'hiAppEvent', `failed to setUserProperty event, code=${error.code}`); 400} 401``` 402 403## hiAppEvent.getUserProperty<sup>11+</sup> 404 405getUserProperty(name: string): string 406 407Obtains the value set by **setUserProperty**. 408 409**System capability**: SystemCapability.HiviewDFX.HiAppEvent 410 411**Parameters** 412 413| Name | Type | Mandatory| Description | 414| --------- | ----------------------- | ---- | ---------- | 415| name | string | Yes | Key of a user property. The value is string that contains a maximum of 256 characters, including digits (0 to 9), letters (a to z), underscore (_), and dollar sign ($). It must not start with a digit.| 416 417**Return value** 418 419| Type | Description | 420| ------ | -------------------------------- | 421| string | Value of a user property. If no user ID is found, an empty string is returned.| 422 423**Error codes** 424 425| ID| Error Message | 426| ------- | ----------------- | 427| 401 | Parameter error. | 428 429**Example** 430 431```ts 432import hilog from '@ohos.hilog'; 433 434hiAppEvent.setUserProperty('key', 'value'); 435try { 436 let value: string = hiAppEvent.getUserProperty('key'); 437 hilog.info(0x0000, 'hiAppEvent', `getUserProperty event was successful, userProperty=${value}`); 438} catch (error) { 439 hilog.error(0x0000, 'hiAppEvent', `failed to getUserProperty event, code=${error.code}`); 440} 441``` 442 443## hiAppEvent.addWatcher 444 445addWatcher(watcher: Watcher): AppEventPackageHolder 446 447Adds a watcher to subscribe to application events. 448 449**System capability**: SystemCapability.HiviewDFX.HiAppEvent 450 451**Parameters** 452 453| Name | Type | Mandatory| Description | 454| ------- | -------------------- | ---- | ---------------- | 455| watcher | [Watcher](#watcher) | Yes | Watcher for application events.| 456 457**Return value** 458 459| Type | Description | 460| ------------------------------------------------ | ------------------------------------ | 461| [AppEventPackageHolder](#appeventpackageholder) | Subscription data holder. If the subscription fails, **null** will be returned.| 462 463**Error codes** 464 465For details about the error codes, see [Application Event Logging Error Codes](../errorcodes/errorcode-hiappevent.md). 466 467| ID| Error Message | 468| -------- | ------------------------------- | 469| 11102001 | Invalid watcher name. | 470| 11102002 | Invalid filtering event domain. | 471| 11102003 | Invalid row value. | 472| 11102004 | Invalid size value. | 473| 11102005 | Invalid timeout value. | 474 475**Example** 476 477```ts 478import hilog from '@ohos.hilog'; 479 480// 1. If callback parameters are passed to the watcher, you can have subscription events processed in the callback that is automatically triggered. 481hiAppEvent.addWatcher({ 482 name: "watcher1", 483 appEventFilters: [ 484 { 485 domain: "test_domain", 486 eventTypes: [hiAppEvent.EventType.FAULT, hiAppEvent.EventType.BEHAVIOR] 487 } 488 ], 489 triggerCondition: { 490 row: 10, 491 size: 1000, 492 timeOut: 1 493 }, 494 onTrigger: (curRow: number, curSize: number, holder: hiAppEvent.AppEventPackageHolder) => { 495 if (holder == null) { 496 hilog.error(0x0000, 'hiAppEvent', "holder is null"); 497 return; 498 } 499 hilog.info(0x0000, 'hiAppEvent', `curRow=${curRow}, curSize=${curSize}`); 500 let eventPkg: hiAppEvent.AppEventPackage | null = null; 501 while ((eventPkg = holder.takeNext()) != null) { 502 hilog.info(0x0000, 'hiAppEvent', `eventPkg.packageId=${eventPkg.packageId}`); 503 hilog.info(0x0000, 'hiAppEvent', `eventPkg.row=${eventPkg.row}`); 504 hilog.info(0x0000, 'hiAppEvent', `eventPkg.size=${eventPkg.size}`); 505 for (const eventInfo of eventPkg.data) { 506 hilog.info(0x0000, 'hiAppEvent', `eventPkg.data=${eventInfo}`); 507 } 508 } 509 } 510}); 511 512// 2. If no callback parameters are passed to the watcher, you can have subscription events processed manually through the subscription data holder. 513let holder = hiAppEvent.addWatcher({ 514 name: "watcher2", 515}); 516if (holder != null) { 517 let eventPkg: hiAppEvent.AppEventPackage | null = null; 518 while ((eventPkg = holder.takeNext()) != null) { 519 hilog.info(0x0000, 'hiAppEvent', `eventPkg.packageId=${eventPkg.packageId}`); 520 hilog.info(0x0000, 'hiAppEvent', `eventPkg.row=${eventPkg.row}`); 521 hilog.info(0x0000, 'hiAppEvent', `eventPkg.size=${eventPkg.size}`); 522 for (const eventInfo of eventPkg.data) { 523 hilog.info(0x0000, 'hiAppEvent', `eventPkg.data=${eventInfo}`); 524 } 525 } 526} 527 528// 3. You can have the watcher processed the subscription event in the onReceive function. 529hiAppEvent.addWatcher({ 530 name: "watcher3", 531 appEventFilters: [ 532 { 533 domain: "test_domain", 534 eventTypes: [hiAppEvent.EventType.FAULT, hiAppEvent.EventType.BEHAVIOR] 535 } 536 ], 537 onReceive: (domain: string, appEventGroups: Array<hiAppEvent.AppEventGroup>) => { 538 hilog.info(0x0000, 'hiAppEvent', `domain=${domain}`); 539 for (const eventGroup of appEventGroups) { 540 hilog.info(0x0000, 'hiAppEvent', `eventName=${eventGroup.name}`); 541 for (const eventInfo of eventGroup.appEventInfos) { 542 hilog.info(0x0000, 'hiAppEvent', `event=${JSON.stringify(eventInfo)}`, ); 543 } 544 } 545 } 546}); 547``` 548 549## hiAppEvent.removeWatcher 550 551removeWatcher(watcher: Watcher): void 552 553Removes a watcher to unsubscribe from application events. 554 555**System capability**: SystemCapability.HiviewDFX.HiAppEvent 556 557**Parameters** 558 559| Name | Type | Mandatory| Description | 560| ------- | -------------------- | ---- | ---------------- | 561| watcher | [Watcher](#watcher) | Yes | Watcher for application events.| 562 563**Error codes** 564 565For details about the error codes, see [Application Event Logging Error Codes](../errorcodes/errorcode-hiappevent.md). 566 567| ID| Error Message | 568| -------- | --------------------- | 569| 11102001 | Invalid watcher name. | 570 571**Example** 572 573```ts 574// 1. Define a watcher for application events. 575let watcher: hiAppEvent.Watcher = { 576 name: "watcher1", 577} 578 579// 2. Add the watcher to subscribe to application events. 580hiAppEvent.addWatcher(watcher); 581 582// 3. Remove the watcher to unsubscribe from application events. 583hiAppEvent.removeWatcher(watcher); 584``` 585 586## Watcher 587 588Defines parameters for a **Watcher** object. 589 590**System capability**: SystemCapability.HiviewDFX.HiAppEvent 591 592| Name | Type | Mandatory| Description | 593| ---------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 594| name | string | Yes | Unique name of a watcher. | 595| triggerCondition | [TriggerCondition](#triggercondition) | No | Subscription callback triggering condition. This parameter takes effect only when it is passed together with **onTrigger**. | 596| appEventFilters | [AppEventFilter](#appeventfilter)[] | No | Subscription filtering condition. This parameter is passed only when subscription events need to be filtered. | 597| onTrigger | (curRow: number, curSize: number, holder: [AppEventPackageHolder](#appeventpackageholder)) => void | No | Subscription callback. This parameter takes effect only when it is passed together with **triggerCondition**. The input arguments are described as follows:<br>**curRow**: total number of subscription events when the callback is triggered.<br>**curSize**: total size of subscribed events when the callback is triggered, in bytes.<br>**holder**: subscription data holder, which can be used to process subscribed events.| 598| onReceive<sup>11+</sup> | (domain: string, appEventGroups: Array<[AppEventGroup](#appeventgroup11)>) => void | No| Real-time subscription callback. Only this callback function is triggered if it is passed together with **onTrigger**. The input arguments are described as follows:<br>domain: domain name.<br>appEventGroups: event group.| 599 600## TriggerCondition 601 602Defines callback triggering conditions. A callback is triggered when any specified condition is met. 603 604**System capability**: SystemCapability.HiviewDFX.HiAppEvent 605 606| Name | Type | Mandatory| Description | 607| ------- | ------ | ---- | -------------------------------------- | 608| row | number | No | Number of events. | 609| size | number | No | Event data size, in bytes.| 610| timeOut | number | No | Timeout interval, in unit of 30s. | 611 612## AppEventFilter 613 614Defines parameters for an **AppEventFilter** object. 615 616**System capability**: SystemCapability.HiviewDFX.HiAppEvent 617 618| Name | Type | Mandatory| Description | 619| ---------- | ------------------------- | ---- | ------------------------ | 620| domain | string | Yes | Event domain. | 621| eventTypes | [EventType](#eventtype)[] | No | Event types.| 622| names<sup>11+</sup> | string[] | No | Names of the events to be subscribed.| 623 624## AppEventPackageHolder 625 626Defines a subscription data holder for processing subscription events. 627 628### constructor 629 630constructor(watcherName: string) 631 632A constructor used to create a holder object for subscription data. It is associated with a **Watcher** object based on its name. 633 634**System capability**: SystemCapability.HiviewDFX.HiAppEvent 635 636**Parameters** 637 638| Name| Type | Mandatory| Description | 639| ------ | ----------------- | ---- | ------------------------ | 640| watcherName | string | Yes | Watcher name.| 641 642**Example** 643 644```ts 645let holder1: hiAppEvent.AppEventPackageHolder = new hiAppEvent.AppEventPackageHolder("watcher1"); 646``` 647 648### setSize 649 650setSize(size: number): void 651 652Sets the threshold for the data size of the application event package obtained each time. 653 654**System capability**: SystemCapability.HiviewDFX.HiAppEvent 655 656**Parameters** 657 658| Name| Type | Mandatory| Description | 659| ------ | ------ | ---- | -------------------------------------------- | 660| size | number | Yes | Data size threshold, in bytes. The default value is **512*1024**.| 661 662**Error codes** 663 664For details about the error codes, see [Application Event Logging Error Codes](../errorcodes/errorcode-hiappevent.md). 665 666| ID| Error Message | 667| -------- | ------------------- | 668| 11104001 | Invalid size value. | 669 670**Example** 671 672```ts 673let holder2: hiAppEvent.AppEventPackageHolder = new hiAppEvent.AppEventPackageHolder("watcher2"); 674holder2.setSize(1000); 675``` 676 677### takeNext 678 679takeNext(): AppEventPackage 680 681Extracts subscription event data based on the configured data size threshold. If all subscription event data has been extracted, **null** will be returned. 682 683**System capability**: SystemCapability.HiviewDFX.HiAppEvent 684 685**Return value** 686 687| Type | Description | 688| ----------------------------------- | ------------------------------------------------------ | 689| [AppEventPackage](#appeventpackage) | Event package object. If all subscription event data has been retrieved, **null** is returned.| 690 691**Example** 692 693```ts 694let holder3: hiAppEvent.AppEventPackageHolder = new hiAppEvent.AppEventPackageHolder("watcher3"); 695let eventPkg = holder3.takeNext(); 696``` 697 698## AppEventPackage 699 700Defines parameters for an **AppEventPackage** object. 701 702**System capability**: SystemCapability.HiviewDFX.HiAppEvent 703 704| Name | Type | Mandatory| Description | 705| --------- | -------- | ---- | ------------------------------ | 706| packageId | number | Yes | Event package ID, which is named from **0** in ascending order. | 707| row | number | Yes | Number of events in the event package. | 708| size | number | Yes | Event size of the event package, in bytes.| 709| data | string[] | Yes | Event data in the event package. | 710 711## AppEventGroup<sup>11+</sup> 712 713Defines the event group returned by a subscription. 714 715**System capability**: SystemCapability.HiviewDFX.HiAppEvent 716 717| Name | Type | Mandatory | Description | 718| ------------- | ------------------------------- | ---- | ------------- | 719| name | string | Yes | Event name. | 720| appEventInfos | Array<[AppEventInfo](#appeventinfo)> | Yes | Event object group.| 721 722## hiAppEvent.clearData 723 724clearData(): void 725 726Clears local application event logging data. 727 728**System capability**: SystemCapability.HiviewDFX.HiAppEvent 729 730**Example** 731 732```ts 733hiAppEvent.clearData(); 734``` 735 736 737## EventType 738 739Enumerates event types. 740 741**System capability**: SystemCapability.HiviewDFX.HiAppEvent 742 743| Name | Value | Description | 744| --------- | ---- | -------------- | 745| FAULT | 1 | Fault event.| 746| STATISTIC | 2 | Statistical event.| 747| SECURITY | 3 | Security event.| 748| BEHAVIOR | 4 | Behavior event.| 749 750 751## domain<sup>11+</sup> 752 753Defines the domain name of predefined events. 754 755**System capability**: SystemCapability.HiviewDFX.HiAppEvent 756 757| Name| Type | Description | 758| --- | ------ | ---------- | 759| OS | string | System domain.| 760 761 762## event 763 764Defines the names of predefined events. 765 766**System capability**: SystemCapability.HiviewDFX.HiAppEvent 767 768| Name | Type | Description | 769| ------------------------- | ------ | -------------------- | 770| USER_LOGIN | string | User login event. | 771| USER_LOGOUT | string | User logout event. | 772| DISTRIBUTED_SERVICE_START | string | Distributed service startup event.| 773| APP_CRASH<sup>11+</sup> | string | Application crash event. | 774| APP_FREEZE<sup>11+</sup> | string | Application freeze event. | 775 776 777## param 778 779Defines the names of predefined event parameters. 780 781**System capability**: SystemCapability.HiviewDFX.HiAppEvent 782 783| Name | Type | Description | 784| ------------------------------- | ------ | ------------------ | 785| USER_ID | string | Custom user ID. | 786| DISTRIBUTED_SERVICE_NAME | string | Distributed service name. | 787| DISTRIBUTED_SERVICE_INSTANCE_ID | string | Distributed service instance ID.| 788