1# @ohos.hiviewdfx.hiAppEvent (应用事件打点) 2 3本模块提供了应用事件打点能力，包括应用事件落盘、应用事件订阅、应用事件清理、打点功能配置等功能。 4 5> **说明：** 6> 7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9 10## 导入模块 11 12```ts 13import { hiAppEvent } from '@kit.PerformanceAnalysisKit'; 14``` 15 16## hiAppEvent.addProcessor<sup>11+</sup> 17 18addProcessor(processor: Processor): number 19 20开发者可添加数据处理者，该数据处理者用于提供事件上云功能，数据处理者的实现可预置在设备中，开发者可根据数据处理者的约束设置属性。 21 22Processor的配置信息需要由数据处理者提供，目前设备内暂未预置可供交互的数据处理者，因此当前事件上云功能不可用。 23 24**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 25 26**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 27 28**参数：** 29 30| 参数名 | 类型 | 必填 | 说明 | 31| --------- | ---------- | ---- | ------------- | 32| processor | [Processor](#processor11) | 是 | 上报事件的数据处理者。| 33 34**返回值：** 35 36| 类型 | 说明 | 37| ------ | ---------------------- | 38| number | 所添加上报事件数据处理者的ID。 添加失败返回-1，添加成功返回大于0的值。 | 39 40**错误码：** 41 42| 错误码ID | 错误信息 | 43| ------- | ----------------- | 44| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 45 46**示例：** 47 48```ts 49import { hilog } from '@kit.PerformanceAnalysisKit'; 50 51try { 52 let processor: hiAppEvent.Processor = { 53 name: 'analytics_demo' 54 }; 55 let id: number = hiAppEvent.addProcessor(processor); 56 hilog.info(0x0000, 'hiAppEvent', `addProcessor event was successful, id=${id}`); 57} catch (error) { 58 hilog.error(0x0000, 'hiAppEvent', `failed to addProcessor event, code=${error.code}`); 59} 60``` 61 62## Processor<sup>11+</sup> 63 64可以上报事件的数据处理者对象。 65 66**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 67 68| 名称 | 类型 | 必填 | 说明 | 69| ------------------- | ----------------------- | ---- | ---------------------------------------------------------------------------------------------------------- | 70| name | string | 是 | 数据处理者的名称。名称只能包含大小写字母、数字、下划线和 $，不能以数字开头，长度非空且不超过256个字符。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 71| debugMode | boolean | 否 | 是否开启debug模式，默认值为false。配置值为true表示开启debug模式，false表示不开启debug模式。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 72| routeInfo | string | 否 | 服务器位置信息，默认为空字符串。传入字符串长度不能超过8KB，超过时会被置为默认值。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 73| appId | string | 否 | 应用id，默认为空字符串。传入字符串长度不能超过8KB，超过时会被置为默认值。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 74| onStartReport | boolean | 否 | 数据处理者在启动时是否上报事件，默认值为false。配置值为true表示上报事件，false表示不上报事件。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 75| onBackgroundReport | boolean | 否 | 当应用程序进入后台时是否上报事件，默认值为false。配置值为true表示上报事件，false表示不上报事件。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 76| periodReport | number | 否 | 事件定时上报时间周期，单位为秒。传入数值必须大于或等于0，小于0时会被置为默认值0，不进行定时上报。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 77| batchReport | number | 否 | 事件上报阈值，当事件条数达到阈值时上报事件。传入数值必须大于0且小于1000，不在数值范围内会被置为默认值0，不进行上报。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 78| userIds | string[] | 否 | 数据处理者可以上报的用户ID的name数组。name对应[setUserId](#hiappeventsetuserid11)接口的name参数。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 79| userProperties | string[] | 否 | 数据处理者可以上报的用户属性的name数组。name对应[setUserProperty](#hiappeventsetuserproperty11)接口的name参数。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 80| eventConfigs | [AppEventReportConfig](#appeventreportconfig11)[] | 否 | 数据处理者可以上报的事件数组。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 81| configId<sup>12+</sup> | number | 否 | 数据处理者配置id。传入数值必须大于或等于0，小于0时会被置为默认值0。传入的值大于0时，与数据处理者的名称name共同唯一标识数据处理者。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 82| customConfigs<sup>12+</sup> | Record\<string, string> | 否 | 自定义扩展参数。传入参数名和参数值不符合规格会默认不配置扩展参数，其规格定义如下：<br>- 参数名为string类型，首字符必须为字母字符或$字符，中间字符必须为数字字符、字母字符或下划线字符，结尾字符必须为数字字符或字母字符，长度非空且不超过32个字符。<br>- 参数值为string类型，参数值长度需在1024个字符以内。<br>- 参数个数需在32个以内。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 83 84## AppEventReportConfig<sup>11+</sup> 85 86数据处理者可以上报事件的描述配置。 87 88**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 89 90**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 91 92| 名称 | 类型 | 必填 | 说明 | 93| ----------- | ------- | ---- | ------------------------------------------------------------ | 94| domain | string | 否 | 事件领域。事件领域名称支持数字、字母、下划线字符，需要以字母开头且不能以下划线结尾，长度非空且不超过32个字符。 | 95| name | string | 否 | 事件名称。首字符必须为字母字符或$字符，中间字符必须为数字字符、字母字符或下划线字符，结尾字符必须为数字字符或字母字符，长度非空且不超过48个字符。 | 96| isRealTime | boolean | 否 | 是否实时上报事件。配置值为true表示实时上报事件，false表示不实时上报事件。 | 97 98## hiAppEvent.removeProcessor<sup>11+</sup> 99 100removeProcessor(id: number): void 101 102删除上报事件的数据处理者。 103 104**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 105 106**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 107 108**参数：** 109 110| 参数名 | 类型 | 必填 | 说明 | 111| ------| ------- | ---- | --------------------------- | 112| id | number | 是 | 上报事件数据处理者ID。值大于0。| 113 114**错误码：** 115 116| 错误码ID | 错误信息 | 117| ------- | ----------------- | 118| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 119 120**示例：** 121 122```ts 123import { hilog } from '@kit.PerformanceAnalysisKit'; 124 125try { 126 let processor: hiAppEvent.Processor = { 127 name: 'analytics_demo' 128 }; 129 let id: number = hiAppEvent.addProcessor(processor); 130 hiAppEvent.removeProcessor(id); 131} catch (error) { 132 hilog.error(0x0000, 'hiAppEvent', `failed to removeProcessor event, code=${error.code}`); 133} 134``` 135 136## hiAppEvent.write 137 138write(info: AppEventInfo, callback: AsyncCallback<void>): void 139 140应用事件打点方法，将事件写入到当天的事件文件中，可接收AppEventInfo类型的事件对象，使用callback方式作为异步回调。 141 142**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 143 144**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 145 146**参数：** 147 148| 参数名 | 类型 | 必填 | 说明 | 149| -------- | ------------------------------ | ---- | -------------- | 150| info | [AppEventInfo](#appeventinfo) | 是 | 应用事件对象。 | 151| callback | AsyncCallback<void> | 是 | 打点回调函数。 | 152 153**错误码：** 154 155以下错误码的详细介绍请参见[应用事件打点错误码](errorcode-hiappevent.md)。 156 157| 错误码ID | 错误信息 | 158| -------- | --------------------------------------------- | 159| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 160| 11100001 | Function disabled. | 161| 11101001 | Invalid event domain. | 162| 11101002 | Invalid event name. | 163| 11101003 | Invalid number of event parameters. | 164| 11101004 | Invalid string length of the event parameter. | 165| 11101005 | Invalid event parameter name. | 166| 11101006 | Invalid array length of the event parameter. | 167 168**示例：** 169 170```ts 171import { BusinessError } from '@kit.BasicServicesKit'; 172import { hilog } from '@kit.PerformanceAnalysisKit'; 173 174let eventParams: Record<string, number | string> = { 175 "int_data": 100, 176 "str_data": "strValue", 177}; 178hiAppEvent.write({ 179 domain: "test_domain", 180 name: "test_event", 181 eventType: hiAppEvent.EventType.FAULT, 182 params: eventParams, 183}, (err: BusinessError) => { 184 if (err) { 185 hilog.error(0x0000, 'hiAppEvent', `code: ${err.code}, message: ${err.message}`); 186 return; 187 } 188 hilog.info(0x0000, 'hiAppEvent', `success to write event`); 189}); 190``` 191 192## hiAppEvent.write 193 194write(info: AppEventInfo): Promise<void> 195 196应用事件打点方法，将事件写入到当天的事件文件中，可接收AppEventInfo类型的事件对象，使用Promise方式作为异步回调。 197 198**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 199 200**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 201 202**参数：** 203 204| 参数名 | 类型 | 必填 | 说明 | 205| ------ | ------------------------------ | ---- | -------------- | 206| info | [AppEventInfo](#appeventinfo) | 是 | 应用事件对象。 | 207 208**返回值：** 209 210| 类型 | 说明 | 211| ------------------- | ------------- | 212| Promise<void> | Promise对象。 | 213 214**错误码：** 215 216以下错误码的详细介绍请参见[应用事件打点错误码](errorcode-hiappevent.md)。 217 218| 错误码ID | 错误信息 | 219| -------- | --------------------------------------------- | 220| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 221| 11100001 | Function disabled. | 222| 11101001 | Invalid event domain. | 223| 11101002 | Invalid event name. | 224| 11101003 | Invalid number of event parameters. | 225| 11101004 | Invalid string length of the event parameter. | 226| 11101005 | Invalid event parameter name. | 227| 11101006 | Invalid array length of the event parameter. | 228 229**示例：** 230 231```ts 232import { BusinessError } from '@kit.BasicServicesKit'; 233import { hilog } from '@kit.PerformanceAnalysisKit'; 234 235let eventParams: Record<string, number | string> = { 236 "int_data": 100, 237 "str_data": "strValue", 238}; 239hiAppEvent.write({ 240 domain: "test_domain", 241 name: "test_event", 242 eventType: hiAppEvent.EventType.FAULT, 243 params: eventParams, 244}).then(() => { 245 hilog.info(0x0000, 'hiAppEvent', `success to write event`); 246}).catch((err: BusinessError) => { 247 hilog.error(0x0000, 'hiAppEvent', `code: ${err.code}, message: ${err.message}`); 248}); 249``` 250 251## AppEventInfo 252 253提供了应用事件信息的参数选项。 254 255**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 256 257**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 258 259| 名称 | 类型 | 必填 | 说明 | 260| --------- | ----------------------- | ---- | ------------------------------------------------------------ | 261| domain | string | 是 | 事件领域。事件领域名称支持数字、字母、下划线字符，需要以字母开头且不能以下划线结尾，长度非空且不超过32个字符。 | 262| name | string | 是 | 事件名称。首字符必须为字母字符或$字符，中间字符必须为数字字符、字母字符或下划线字符，结尾字符必须为数字字符或字母字符，长度非空且不超过48个字符。 | 263| eventType | [EventType](#eventtype) | 是 | 事件类型。 | 264| params | object | 是 | 事件参数对象，每个事件参数包括参数名和参数值。**系统事件中params包含的字段已由各系统事件定义，具体字段含义在各类系统事件指南的介绍中，例如[崩溃事件介绍](../../dfx/hiappevent-watcher-crash-events.md)。** 针对应用事件，打点写入的参数由开发者定义，其规格如下：<br>- 参数名为string类型，首字符必须为字母字符或$字符，中间字符必须为数字字符、字母字符或下划线字符，结尾字符必须为数字字符或字母字符，长度非空且不超过32个字符。<br>- 参数值支持string、number、boolean、数组类型，string类型参数长度需在8*1024个字符以内，超出会做丢弃处理；number类型参数取值需在Number.MIN_SAFE_INTEGER~Number.MAX_SAFE_INTEGER范围内，超出可能会产生不确定值；数组类型参数中的元素类型只能全为string、number、boolean中的一种，且元素个数需在100以内，超出会做丢弃处理。<br>- 参数个数需在32个以内，超出的参数会做丢弃处理。 | 265 266## hiAppEvent.setEventParam<sup>12+</sup> 267 268setEventParam(params: Record<string, ParamType>, domain: string, name?: string): Promise<void> 269 270事件自定义参数设置方法，使用Promise方式作为异步回调。在同一生命周期中，可以通过事件领域和事件名称关联系统事件和应用事件，系统事件仅支持崩溃和卡死事件。 271 272**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 273 274**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 275 276**参数：** 277 278| 参数名 | 类型 | 必填 | 说明 | 279| ------ | ------------------------------ | ---- | -------------- | 280| params | Record<string, [ParamType](#paramtype12)> | 是 | 事件自定义参数对象。参数名和参数值规格定义如下：<br>- 参数名为string类型，首字符必须为字母字符或$字符，中间字符必须为数字字符、字母字符或下划线字符，结尾字符必须为数字字符或字母字符，长度非空且不超过32个字符。<br>- 参数值为[ParamType](#paramtype12)类型，参数值长度需在1024个字符以内。<br>- 参数个数需在64个以内。 | 281| domain | string | 是 | 事件领域。事件领域可支持关联应用事件和系统事件（hiAppEvent.domain.OS）。 | 282| name | string | 否 | 事件名称。默认为空字符串，空字符串表示关联事件领域下的所有事件名称。事件名称可支持关联应用事件和系统事件，其中系统事件仅支持关联崩溃事件（hiAppEvent.event.APP_CRASH）和卡死事件（hiAppEvent.event.APP_FREEZE）。 | 283 284**返回值：** 285 286| 类型 | 说明 | 287| ------------------- | ------------- | 288| Promise<void> | Promise对象。 | 289 290**错误码：** 291 292以下错误码的详细介绍请参见[应用事件打点错误码](errorcode-hiappevent.md)。 293 294| 错误码ID | 错误信息 | 295| -------- | --------------------------------------------- | 296| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 297| 11101007 | The number of parameter keys exceeds the limit. | 298 299**示例：** 300 301```ts 302import { BusinessError } from '@kit.BasicServicesKit'; 303import { hilog } from '@kit.PerformanceAnalysisKit'; 304 305let params: Record<string, hiAppEvent.ParamType> = { 306 "int_data": 100, 307 "str_data": "strValue", 308}; 309// 给应用事件追加自定义参数 310hiAppEvent.setEventParam(params, "test_domain", "test_event").then(() => { 311 hilog.info(0x0000, 'hiAppEvent', `success to set svent param`); 312}).catch((err: BusinessError) => { 313 hilog.error(0x0000, 'hiAppEvent', `code: ${err.code}, message: ${err.message}`); 314}); 315``` 316 317## ParamType<sup>12+</sup> 318 319type ParamType = number | string | boolean | Array<string> 320 321事件自定义参数值的类型。 322 323**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 324 325**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 326 327| 类型 | 说明 | 328|--------------------------|-------------------| 329| number | 表示值类型为数字。 | 330| string | 表示值类型为字符串。 | 331| boolean | 表示值类型为布尔值。 | 332| Array<string> | 表示值类型为字符串类型的数组。 | 333 334## hiAppEvent.configure 335 336configure(config: ConfigOption): void 337 338应用事件打点配置方法，可用于配置打点开关、目录存储配额大小等功能。 339 340**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 341 342**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 343 344**参数：** 345 346| 参数名 | 类型 | 必填 | 说明 | 347| ------ | ----------------------------- | ---- | ------------------------ | 348| config | [ConfigOption](#configoption) | 是 | 应用事件打点配置项对象。 | 349 350**错误码：** 351 352以下错误码的详细介绍请参见[应用事件打点错误码](errorcode-hiappevent.md)。 353 354| 错误码ID | 错误信息 | 355| -------- | -------------------------------- | 356| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 357| 11103001 | Invalid max storage quota value. | 358 359**示例：** 360 361```ts 362// 配置打点开关为关闭状态 363let config1: hiAppEvent.ConfigOption = { 364 disable: true, 365}; 366hiAppEvent.configure(config1); 367 368// 配置文件目录存储配额为100M 369let config2: hiAppEvent.ConfigOption = { 370 maxStorage: '100M', 371}; 372hiAppEvent.configure(config2); 373``` 374 375## ConfigOption 376 377提供了对应用事件打点功能的配置选项。 378 379**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 380 381**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 382 383| 名称 | 类型 | 必填 | 说明 | 384| ---------- | ------- | ---- | ------------------------------------------------------------ | 385| disable | boolean | 否 | 打点功能开关，默认值为false。true：关闭打点功能，false：不关闭打点功能。 | 386| maxStorage | string | 否 | 打点数据存放目录的配额大小，默认值为“10M”。<br>在目录大小超出配额后，下次打点会触发对目录的清理操作：按从旧到新的顺序逐个删除打点数据文件，直到目录大小不超出配额时结束。<br>配额值字符串规格如下：<br>- 配额值字符串只由数字字符和大小单位字符（单位字符支持[b\|k\|kb\|m\|mb\|g\|gb\|t\|tb]，不区分大小写）构成。<br>- 配额值字符串必须以数字开头，后面可以选择不传单位字符（默认使用byte作为单位），或者以单位字符结尾。 | 387 388## hiAppEvent.setUserId<sup>11+</sup> 389 390setUserId(name: string, value: string): void 391 392设置用户ID。 393 394**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 395 396**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 397 398**参数：** 399 400| 参数名 | 类型 | 必填 | 说明 | 401| --------- | ------------------------- | ---- | ------------- | 402| name | string | 是 | 用户ID的key。只能包含大小写字母、数字、下划线和 $，不能以数字开头，长度非空且不超过256个字符。 | 403| value | string | 是 | 用户ID的值。长度不超过256，当值为null或空字符串时，则清除用户ID。 | 404 405**错误码：** 406 407| 错误码ID | 错误信息 | 408| ------- | ----------------- | 409| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 410 411**示例：** 412 413```ts 414import { hilog } from '@kit.PerformanceAnalysisKit'; 415 416try { 417 hiAppEvent.setUserId('key', 'value'); 418} catch (error) { 419 hilog.error(0x0000, 'hiAppEvent', `failed to setUserId event, code=${error.code}`); 420} 421``` 422 423## hiAppEvent.getUserId<sup>11+</sup> 424 425getUserId(name: string): string 426 427获取之前通过setUserId接口设置的value值。 428 429**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 430 431**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 432 433**参数：** 434 435| 参数名 | 类型 | 必填 | 说明 | 436| --------- | ----------------------- | ---- | ---------- | 437| name | string | 是 | 用户ID的key。只能包含大小写字母、数字、下划线和 $，不能以数字开头，长度不超过256。| 438 439**返回值：** 440 441| 类型 | 说明 | 442| ------ | ------------------------------- | 443| string | 用户ID的值。没有查到返回空字符串。 | 444 445**错误码：** 446 447| 错误码ID | 错误信息 | 448| ------- | ----------------- | 449| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 450 451**示例：** 452 453```ts 454import { hilog } from '@kit.PerformanceAnalysisKit'; 455 456hiAppEvent.setUserId('key', 'value'); 457try { 458 let value: string = hiAppEvent.getUserId('key'); 459 hilog.info(0x0000, 'hiAppEvent', `getUserId event was successful, userId=${value}`); 460} catch (error) { 461 hilog.error(0x0000, 'hiAppEvent', `failed to getUserId event, code=${error.code}`); 462} 463``` 464 465## hiAppEvent.setUserProperty<sup>11+</sup> 466 467setUserProperty(name: string, value: string): void 468 469设置用户属性。 470 471**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 472 473**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 474 475**参数：** 476 477| 参数名 | 类型 | 必填 | 说明 | 478| --------- | ------------------------- | ---- | -------------- | 479| name | string | 是 | 用户属性的key。只能包含大小写字母、数字、下划线和 $，不能以数字开头，长度非空且不超过256个字符。 | 480| value | string | 是 | 用户属性的值。长度不超过1024，当值为null、undefine或空，则清除用户属性。 | 481 482**错误码：** 483 484| 错误码ID | 错误信息 | 485| ------- | ----------------- | 486| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 487 488**示例：** 489 490```ts 491import { hilog } from '@kit.PerformanceAnalysisKit'; 492 493try { 494 hiAppEvent.setUserProperty('key', 'value'); 495} catch (error) { 496 hilog.error(0x0000, 'hiAppEvent', `failed to setUserProperty event, code=${error.code}`); 497} 498``` 499 500## hiAppEvent.getUserProperty<sup>11+</sup> 501 502getUserProperty(name: string): string 503 504获取之前通过setUserProperty接口设置的value值。 505 506**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 507 508**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 509 510**参数：** 511 512| 参数名 | 类型 | 必填 | 说明 | 513| --------- | ----------------------- | ---- | ---------- | 514| name | string | 是 | 用户属性的key。只能包含大小写字母、数字、下划线和 $，不能以数字开头，长度不超过256。| 515 516**返回值：** 517 518| 类型 | 说明 | 519| ------ | -------------------------------- | 520| string | 用户属性的值。 没有查到返回空字符串。 | 521 522**错误码：** 523 524| 错误码ID | 错误信息 | 525| ------- | ----------------- | 526| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 527 528**示例：** 529 530```ts 531import { hilog } from '@kit.PerformanceAnalysisKit'; 532 533hiAppEvent.setUserProperty('key', 'value'); 534try { 535 let value: string = hiAppEvent.getUserProperty('key'); 536 hilog.info(0x0000, 'hiAppEvent', `getUserProperty event was successful, userProperty=${value}`); 537} catch (error) { 538 hilog.error(0x0000, 'hiAppEvent', `failed to getUserProperty event, code=${error.code}`); 539} 540``` 541 542## hiAppEvent.addWatcher 543 544addWatcher(watcher: Watcher): AppEventPackageHolder 545 546添加应用事件观察者方法，可用于订阅应用事件。 547 548**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 549 550**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 551 552**参数：** 553 554| 参数名 | 类型 | 必填 | 说明 | 555| ------- | -------------------- | ---- | ---------------- | 556| watcher | [Watcher](#watcher) | 是 | 应用事件观察者。 | 557 558**返回值：** 559 560| 类型 | 说明 | 561| ------------------------------------------------ | ------------------------------------ | 562| [AppEventPackageHolder](#appeventpackageholder) | 订阅数据持有者，订阅失败时返回null。 | 563 564**错误码：** 565 566以下错误码的详细介绍请参见[应用事件打点错误码](errorcode-hiappevent.md)。 567 568| 错误码ID | 错误信息 | 569| -------- | ------------------------------- | 570| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 571| 11102001 | Invalid watcher name. | 572| 11102002 | Invalid filtering event domain. | 573| 11102003 | Invalid row value. | 574| 11102004 | Invalid size value. | 575| 11102005 | Invalid timeout value. | 576 577**示例：** 578 579```ts 580import { hilog } from '@kit.PerformanceAnalysisKit'; 581 582// 1. 如果观察者传入了回调的相关参数，则可以选择在自动触发的回调函数中对订阅事件进行处理 583hiAppEvent.addWatcher({ 584 name: "watcher1", 585 appEventFilters: [ 586 { 587 domain: "test_domain", 588 eventTypes: [hiAppEvent.EventType.FAULT, hiAppEvent.EventType.BEHAVIOR] 589 } 590 ], 591 triggerCondition: { 592 row: 10, 593 size: 1000, 594 timeOut: 1 595 }, 596 onTrigger: (curRow: number, curSize: number, holder: hiAppEvent.AppEventPackageHolder) => { 597 if (holder == null) { 598 hilog.error(0x0000, 'hiAppEvent', "holder is null"); 599 return; 600 } 601 hilog.info(0x0000, 'hiAppEvent', `curRow=${curRow}, curSize=${curSize}`); 602 let eventPkg: hiAppEvent.AppEventPackage | null = null; 603 while ((eventPkg = holder.takeNext()) != null) { 604 hilog.info(0x0000, 'hiAppEvent', `eventPkg.packageId=${eventPkg.packageId}`); 605 hilog.info(0x0000, 'hiAppEvent', `eventPkg.row=${eventPkg.row}`); 606 hilog.info(0x0000, 'hiAppEvent', `eventPkg.size=${eventPkg.size}`); 607 for (const eventInfo of eventPkg.data) { 608 hilog.info(0x0000, 'hiAppEvent', `eventPkg.data=${eventInfo}`); 609 } 610 } 611 } 612}); 613 614// 2. 如果观察者未传入回调的相关参数，则可以选择使用返回的holder对象手动去处理订阅事件 615// 针对异常退出时产生的崩溃事件（hiAppEvent.event.APP_CRASH）和卡死事件（hiAppEvent.event.APP_FREEZE），系统捕获维测日志有一定耗时，典型情况下30s内完成，极端情况下2min左右完成。在手动处理订阅事件的方法中，建议在进程启动后延时重试调用takeNext()获取此类事件。 616let holder = hiAppEvent.addWatcher({ 617 name: "watcher2", 618}); 619if (holder != null) { 620 let eventPkg: hiAppEvent.AppEventPackage | null = null; 621 while ((eventPkg = holder.takeNext()) != null) { 622 hilog.info(0x0000, 'hiAppEvent', `eventPkg.packageId=${eventPkg.packageId}`); 623 hilog.info(0x0000, 'hiAppEvent', `eventPkg.row=${eventPkg.row}`); 624 hilog.info(0x0000, 'hiAppEvent', `eventPkg.size=${eventPkg.size}`); 625 for (const eventInfo of eventPkg.data) { 626 hilog.info(0x0000, 'hiAppEvent', `eventPkg.data=${eventInfo}`); 627 } 628 } 629} 630 631// 3. 观察者可以在实时回调函数onReceive中处理订阅事件 632hiAppEvent.addWatcher({ 633 name: "watcher3", 634 appEventFilters: [ 635 { 636 domain: "test_domain", 637 eventTypes: [hiAppEvent.EventType.FAULT, hiAppEvent.EventType.BEHAVIOR] 638 } 639 ], 640 onReceive: (domain: string, appEventGroups: Array<hiAppEvent.AppEventGroup>) => { 641 hilog.info(0x0000, 'hiAppEvent', `domain=${domain}`); 642 for (const eventGroup of appEventGroups) { 643 hilog.info(0x0000, 'hiAppEvent', `eventName=${eventGroup.name}`); 644 for (const eventInfo of eventGroup.appEventInfos) { 645 hilog.info(0x0000, 'hiAppEvent', `event=${JSON.stringify(eventInfo)}`, ); 646 } 647 } 648 } 649}); 650``` 651 652## hiAppEvent.removeWatcher 653 654removeWatcher(watcher: Watcher): void 655 656移除应用事件观察者方法，可用于取消订阅应用事件。 657 658**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 659 660**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 661 662**参数：** 663 664| 参数名 | 类型 | 必填 | 说明 | 665| ------- | -------------------- | ---- | ---------------- | 666| watcher | [Watcher](#watcher) | 是 | 应用事件观察者。 | 667 668**错误码：** 669 670以下错误码的详细介绍请参见[应用事件打点错误码](errorcode-hiappevent.md)。 671 672| 错误码ID | 错误信息 | 673| -------- | --------------------- | 674| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 675| 11102001 | Invalid watcher name. | 676 677**示例：** 678 679```ts 680// 1. 定义一个应用事件观察者 681let watcher: hiAppEvent.Watcher = { 682 name: "watcher1", 683} 684 685// 2. 添加一个应用事件观察者来订阅事件 686hiAppEvent.addWatcher(watcher); 687 688// 3. 移除该应用事件观察者以取消订阅事件 689hiAppEvent.removeWatcher(watcher); 690``` 691 692## Watcher 693 694提供了应用事件观察者的参数选项。 695 696**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 697 698**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 699 700| 名称 | 类型 | 必填 | 说明 | 701| ---------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 702| name | string | 是 | 观察者名称，用于唯一标识观察者。 | 703| triggerCondition | [TriggerCondition](#triggercondition) | 否 | 订阅回调触发条件，需要与回调函数onTrigger一同传入才会生效。 | 704| appEventFilters | [AppEventFilter](#appeventfilter)[] | 否 | 订阅过滤条件，在需要对订阅事件进行过滤时传入。 | 705| onTrigger | (curRow: number, curSize: number, holder: [AppEventPackageHolder](#appeventpackageholder)) => void | 否 | 订阅回调函数，需要与回调触发条件triggerCondition一同传入才会生效，函数入参说明如下：<br>curRow：在本次回调触发时的订阅事件总数量； <br>curSize：在本次回调触发时的订阅事件总大小，单位为byte； <br/>holder：订阅数据持有者对象，可以通过其对订阅事件进行处理。 | 706| onReceive<sup>11+</sup> | (domain: string, appEventGroups: Array<[AppEventGroup](#appeventgroup11)>) => void | 否 | 订阅实时回调函数，与回调函数onTrigger同时存在时，只触发此回调，函数入参说明如下：<br>domain：回调事件的领域名称； <br>appEventGroups：回调事件集合。 | 707 708## TriggerCondition 709 710提供了回调触发条件的参数选项，只要满足任一条件就会触发订阅回调。 711 712**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 713 714**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 715 716| 名称 | 类型 | 必填 | 说明 | 717| ------- | ------ | ---- | -------------------------------------- | 718| row | number | 否 | 满足触发回调的事件总数量，正整数。默认值0，不触发回调。传入负值时，会被置为默认值。 | 719| size | number | 否 | 满足触发回调的事件总大小，正整数，单位为byte。默认值0，不触发回调。传入负值时，会被置为默认值。 | 720| timeOut | number | 否 | 满足触发回调的超时时长，正整数，单位为30s。默认值0，不触发回调。传入负值时，会被置为默认值。 | 721 722## AppEventFilter 723 724提供了过滤应用事件的参数选项。 725 726**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 727 728**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 729 730| 名称 | 类型 | 必填 | 说明 | 731| ---------- | ------------------------- | ---- | ------------------------ | 732| domain | string | 是 | 需要订阅的事件领域。 | 733| eventTypes | [EventType](#eventtype)[] | 否 | 需要订阅的事件类型集合。 | 734| names<sup>11+</sup> | string[] | 否 | 需要订阅的事件名称集合。 | 735 736## AppEventPackageHolder 737 738订阅数据持有者类，用于对订阅事件进行处理。 739 740### constructor 741 742constructor(watcherName: string) 743 744类构造函数，创建订阅数据持有者实例，通过观察者名称关联到应用内已添加的观察者对象。 745 746**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 747 748**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 749 750**参数：** 751 752| 参数名 | 类型 | 必填 | 说明 | 753| ------ | ----------------- | ---- | ------------------------ | 754| watcherName | string | 是 | 观察者名称。 | 755 756**示例：** 757 758```ts 759let holder1: hiAppEvent.AppEventPackageHolder = new hiAppEvent.AppEventPackageHolder("watcher1"); 760``` 761 762### setSize 763 764setSize(size: number): void 765 766设置每次取出的应用事件包的数据大小阈值。 767 768**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 769 770**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 771 772**参数：** 773 774| 参数名 | 类型 | 必填 | 说明 | 775| ------ | ------ | ---- | -------------------------------------------- | 776| size | number | 是 | 数据大小阈值，单位为byte，取值范围是大于等于0的数，超出范围会抛异常。 | 777 778**错误码：** 779 780以下错误码的详细介绍请参见[应用事件打点错误码](errorcode-hiappevent.md)。 781 782| 错误码ID | 错误信息 | 783| -------- | ------------------- | 784| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 785| 11104001 | Invalid size value. | 786 787**示例：** 788 789```ts 790let holder2: hiAppEvent.AppEventPackageHolder = new hiAppEvent.AppEventPackageHolder("watcher2"); 791holder2.setSize(1000); 792``` 793 794### setRow<sup>12+</sup> 795 796setRow(size: number): void 797 798设置每次取出的应用事件包的数据条数，优先级高于setSize，和setSize同时调用时仅setRow生效。 799 800**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 801 802**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 803 804**参数：** 805 806| 参数名 | 类型 | 必填 | 说明 | 807| ------ | ------ | ---- | -------------------------------------------- | 808| size | number | 是 | 应用事件条数，单位为条，取值范围是大于0的数，超出范围会抛异常。 | 809 810**错误码：** 811 812以下错误码的详细介绍请参见[应用事件打点错误码](errorcode-hiappevent.md)。 813 814| 错误码ID | 错误信息 | 815| -------- | ------------------- | 816| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 817| 11104001 | Invalid size value. | 818 819**示例：** 820 821```ts 822let holder3: hiAppEvent.AppEventPackageHolder = new hiAppEvent.AppEventPackageHolder("watcher3"); 823holder3.setRow(1000); 824``` 825 826### takeNext 827 828takeNext(): AppEventPackage 829 830根据设置的数据大小阈值或条数来取出订阅事件数据，当订阅事件数据全部被取出时返回null作为标识。 8311、应用仅调用setSize不调用setRow时，根据数据大小限制取订阅事件。 8322、应用调用setRow，无论是否调用setSize，都根据setRow设置的条数取订阅事件。 8333、setSize和setRow都没被调用时，默认取1条订阅事件。 834 835**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 836 837**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 838 839**返回值：** 840 841| 类型 | 说明 | 842| ----------------------------------- | ------------------------------------------------------ | 843| [AppEventPackage](#appeventpackage) | 取出的事件包对象，订阅事件数据被全部取出后会返回null。 | 844 845**示例：** 846 847```ts 848let holder4: hiAppEvent.AppEventPackageHolder = new hiAppEvent.AppEventPackageHolder("watcher4"); 849let eventPkg = holder4.takeNext(); 850``` 851 852## AppEventPackage 853 854提供了订阅返回的应用事件包的参数定义。 855 856**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 857 858| 名称 | 类型 | 必填 | 说明 | 859| --------- | -------- | ---- | ------------------------------ | 860| packageId | number | 是 | 事件包ID，从0开始自动递增。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 861| row | number | 是 | 事件包的事件数量。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 862| size | number | 是 | 事件包的事件大小，单位为byte。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 863| data | string[] | 是 | 事件包的事件信息。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 864| appEventInfos<sup>12+</sup> | Array<[AppEventInfo](#appeventinfo)> | 是 | 事件对象集合。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 865 866## AppEventGroup<sup>11+</sup> 867 868提供了订阅返回的事件组的参数定义。 869 870**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 871 872**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 873 874| 名称 | 类型 | 必填 | 说明 | 875| ------------- | ------------------------------- | ---- | ------------- | 876| name | string | 是 | 事件名称。 | 877| appEventInfos | Array<[AppEventInfo](#appeventinfo)> | 是 | 事件对象集合。 | 878 879## hiAppEvent.clearData 880 881clearData(): void 882 883应用事件打点数据清理方法，将应用存储在本地的打点数据进行清除。 884 885**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 886 887**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 888 889**示例：** 890 891```ts 892hiAppEvent.clearData(); 893``` 894 895 896## EventType 897 898事件类型枚举。 899 900**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 901 902**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 903 904| 名称 | 值 | 说明 | 905| --------- | ---- | -------------- | 906| FAULT | 1 | 故障类型事件。 | 907| STATISTIC | 2 | 统计类型事件。 | 908| SECURITY | 3 | 安全类型事件。 | 909| BEHAVIOR | 4 | 行为类型事件。 | 910 911 912## hiappevent.domain<sup>11+</sup> 913 914提供了所有预定义事件的领域名称常量。 915 916**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 917 918**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 919 920| 名称 | 类型 | 只读 | 说明 | 921| --- | ------ | ------ | ---------- | 922| OS | string | 是 | 系统领域。 | 923 924 925## hiappevent.event 926 927提供了所有预定义事件的事件名称常量。 928 929**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 930 931| 名称 | 类型 | 只读 | 说明 | 932| ------------------------- | ------ | ------ | -------------------- | 933| USER_LOGIN | string | 是 | 用户登录事件。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 934| USER_LOGOUT | string | 是 | 用户登出事件。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 935| DISTRIBUTED_SERVICE_START | string | 是 | 分布式服务启动事件。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 936| APP_CRASH<sup>11+</sup> | string | 是 | 应用崩溃事件。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 937| APP_FREEZE<sup>11+</sup> | string | 是 | 应用卡死事件。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 938| APP_LAUNCH<sup>12+</sup> | string | 是 | 应用启动耗时事件。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 939| SCROLL_JANK<sup>12+</sup> | string | 是 | 应用滑动丢帧事件。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 940| CPU_USAGE_HIGH<sup>12+</sup> | string | 是 | 应用CPU高负载事件。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 941| BATTERY_USAGE<sup>12+</sup> | string | 是 | 应用24h功耗器件分解统计事件。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 942| RESOURCE_OVERLIMIT<sup>12+</sup> | string | 是 | 应用资源泄露事件。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 943| ADDRESS_SANITIZER<sup>12+</sup> | string | 是 | 应用踩内存事件。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 944| MAIN_THREAD_JANK<sup>12+</sup> | string | 是 | 应用主线程超时事件。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 945 946 947## hiappevent.param 948 949提供了所有预定义参数的参数名称常量。 950 951**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 952 953**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 954 955| 名称 | 类型 | 只读 | 说明 | 956| ------------------------------- | ------ | ------ | ------------------ | 957| USER_ID | string | 是 | 用户自定义ID。 | 958| DISTRIBUTED_SERVICE_NAME | string | 是 | 分布式服务名称。 | 959| DISTRIBUTED_SERVICE_INSTANCE_ID | string | 是 | 分布式服务实例ID。 |