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