1# @ohos.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本模块提供了应用事件打点能力，包括对打点数据的落盘，以及对打点功能的管理配置。 11 12> **说明：** 13> 14> - 本模块接口从API version 9开始废弃，建议使用新接口[`@ohos.hiviewdfx.hiAppEvent`](js-apis-hiviewdfx-hiappevent.md)替代。 15> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 16 17 18## 导入模块 19 20```ts 21import hiAppEvent from '@ohos.hiAppEvent'; 22``` 23 24## 使用说明 25 26开发者在使用应用事件打点功能前，需要首先了解应用事件相关的参数规格定义。 27 28**事件名称** 29 30事件名称为string类型，字符串非空且长度在48个字符以内，首字符必须为字母字符或$字符，中间字符必须为数字字符、字母字符或下划线字符，结尾字符必须为数字字符或字母字符。 31 32**事件类型** 33 34事件类型为[EventType](#eventtype)枚举类型。 35 36**事件参数** 37 38事件参数为object类型，key为事件的参数名称，value为事件的参数值，其规格定义如下： 39 40- 参数名为string类型，字符串非空且长度在32个字符以内，首字符必须为字母字符或$字符，中间字符必须为数字字符、字母字符或下划线字符，结尾字符必须为数字字符或字母字符； 41- 参数值支持string、number、boolean、数组类型； 42- 参数值为string类型时，其长度需在8*1024个字符以内，超出会做丢弃处理； 43- 参数值为number类型时，其取值需在Number.MIN_SAFE_INTEGER~Number.MAX_SAFE_INTEGER范围内，超出可能会产生不确定值； 44- 参数值为数组类型时，数组中的元素类型只能全为string、number、boolean中的一种，且元素个数需在100以内，超出会做丢弃处理； 45- 参数个数需在32以内，超出的参数会做丢弃处理。 46 47**事件回调** 48 49开发者在调用事件打点方法后，可以在回调函数中对打点返回值进行处理，当前支持callback形式和Promise形式的回调，其返回值规格定义如下： 50 51- 返回值为0，表示事件校验成功，将事件直接落盘到事件文件； 52- 返回值大于0，表示事件校验存在异常参数，在忽略异常参数后将事件落盘到事件文件； 53- 返回值小于0，表示事件校验失败，不将事件落盘到事件文件。 54 55## hiAppEvent.write 56 57write(eventName: string, eventType: EventType, keyValues: object, callback: AsyncCallback<void>): void 58 59应用事件打点方法，将事件写入到当天的事件文件中，使用callback方式作为异步回调。 60 61**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 62 63**参数：** 64 65| 参数名 | 类型 | 必填 | 说明 | 66| --------- | ------------------------- | ---- | -------------- | 67| eventName | string | 是 | 事件名称。 | 68| eventType | [EventType](#eventtype) | 是 | 事件类型。 | 69| keyValues | object | 是 | 事件参数。 | 70| callback | AsyncCallback<void> | 是 | 事件回调函数。 | 71 72**示例：** 73 74```ts 75import { BusinessError } from '@ohos.base' 76 77let eventParams: Record<string, number | string> = { 78 "int_data": 100, 79 "str_data": "strValue", 80}; 81hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, eventParams, (err: BusinessError) => { 82 if (err) { 83 // 事件写入异常：事件存在异常参数时忽略异常参数后继续写入，或者事件校验失败时不执行写入 84 console.error(`failed to write event, code=${err.code}`); 85 return; 86 } 87 // 事件写入正常 88 console.log(`success to write event`); 89}); 90``` 91 92 93## hiAppEvent.write 94 95write(eventName: string, eventType: EventType, keyValues: object): Promise<void> 96 97应用事件打点方法，将事件写入到当天的事件文件中，使用Promise方式作为异步回调。 98 99**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 100 101**参数：** 102 103| 参数名 | 类型 | 必填 | 说明 | 104| --------- | ----------------------- | ---- | ---------- | 105| eventName | string | 是 | 事件名称。 | 106| eventType | [EventType](#eventtype) | 是 | 事件类型。 | 107| keyValues | object | 是 | 事件参数。 | 108 109**返回值：** 110 111| 类型 | 说明 | 112| ------------------- | ------------------------------------------------------------ | 113| Promise<void> | Promise对象，可以在其then()、catch()方法中分别对事件写入成功、写入异常的情况进行异步处理。 | 114 115**示例：** 116 117```ts 118import { BusinessError } from '@ohos.base' 119 120let eventParams: Record<string, number | string> = { 121 "int_data": 100, 122 "str_data": "strValue", 123}; 124hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, eventParams).then(() => { 125 // 事件写入正常 126 console.log(`success to write event`); 127}).catch((err: BusinessError) => { 128 // 事件写入异常：事件存在异常参数时忽略异常参数后继续写入，或者事件校验失败时不执行写入 129 console.error(`failed to write event, code=${err.code}`); 130}); 131``` 132 133## hiAppEvent.configure 134 135configure(config: ConfigOption): boolean 136 137应用事件打点配置方法，可用于配置打点开关、文件目录存储限额大小等功能。 138 139**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 140 141**参数：** 142 143| 参数名 | 类型 | 必填 | 说明 | 144| ------ | ----------------------------- | ---- | ------------------------ | 145| config | [ConfigOption](#configoption) | 是 | 应用事件打点配置项对象。 | 146 147**返回值：** 148 149| 类型 | 说明 | 150| ------- | ----------------------------------------------------------- | 151| boolean | 配置结果，true 表示配置成功，false 表示配置失败。 | 152 153**示例：** 154 155```ts 156// 配置应用事件打点功能开关 157let config1: hiAppEvent.ConfigOption = { 158 disable: true, 159}; 160hiAppEvent.configure(config1); 161 162// 配置事件文件目录存储限额大小 163let config2: hiAppEvent.ConfigOption = { 164 maxStorage: '100M', 165}; 166hiAppEvent.configure(config2); 167``` 168 169## ConfigOption 170 171此接口提供了应用打点的配置选项。 172 173**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 174 175| 名称 | 类型 | 必填 | 说明 | 176| ---------- | ------- | ---- | ------------------------------------------------------------ | 177| disable | boolean | 否 | 应用打点功能开关。配置值为true表示关闭打点功能，false表示不关闭打点功能。 | 178| maxStorage | string | 否 | 打点数据本地存储文件所在目录的配额大小，默认限额为“10M”。所在目录大小超出限额后会对目录进行清理操作，会按从旧到新的顺序逐个删除打点数据文件，直到目录大小不超出限额时停止。 | 179 180 181## EventType 182 183事件类型枚举。 184 185**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 186 187| 名称 | 值 | 说明 | 188| --------- | ---- | -------------- | 189| FAULT | 1 | 故障类型事件。 | 190| STATISTIC | 2 | 统计类型事件。 | 191| SECURITY | 3 | 安全类型事件。 | 192| BEHAVIOR | 4 | 行为类型事件。 | 193 194 195## Event 196 197此接口提供了所有预定义事件的事件名称常量。 198 199**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 200 201| 名称 | 类型 | 可读 | 可写 | 说明 | 202| ------------------------- | ------ | ---- | ---- | -------------------- | 203| USER_LOGIN | string | 是 | 否 | 用户登录事件。 | 204| USER_LOGOUT | string | 是 | 否 | 用户登出事件。 | 205| DISTRIBUTED_SERVICE_START | string | 是 | 否 | 分布式服务启动事件。 | 206 207 208## Param 209 210此接口提供了所有预定义参数的参数名称常量。 211 212**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 213 214| 名称 | 类型 | 可读 | 可写 | 说明 | 215| ------------------------------- | ------ | ---- | ---- | ------------------ | 216| USER_ID | string | 是 | 否 | 用户自定义ID。 | 217| DISTRIBUTED_SERVICE_NAME | string | 是 | 否 | 分布式服务名称。 | 218| DISTRIBUTED_SERVICE_INSTANCE_ID | string | 是 | 否 | 分布式服务实例ID。 |