1# 应用打点 2 3本模块提供了应用事件打点能力，包括对打点数据的落盘，以及对打点功能的管理配置。 4 5>  **说明：** 6> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 7 8 9## 导入模块 10 11``` 12import hiAppEvent from '@ohos.hiAppEvent'; 13``` 14 15 16## hiAppEvent.write 17 18write(eventName: string, eventType: EventType, keyValues: object, callback: AsyncCallback<void>): void 19 20应用事件打点方法，将事件写入到当天的事件文件中，可接收类型为Json对象的事件参数，使用callback方式作为异步回调。 21 22**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 23 24**参数：** 25 26| 参数名 | 类型 | 必填 | 说明 | 27| --------- | ------------------------- | ---- | ------------------------------------------------------------ | 28| eventName | string | 是 | 应用事件名称。<br/>由开发者自定义。事件名称在48个字符以内，有效的字符是0-9、a-z、下划线，只能以字母开头。 | 29| eventType | [EventType](#eventtype) | 是 | 应用事件类型。 | 30| keyValues | object | 是 | 事件参数键值对，如果是变长参数类型，则依次输入事件的参数名与参数值。如果是Json对象类型，则Json对象的key是事件的参数名，value是事件的参数值。<br/>- key类型只能为string，value类型只能为string、number、boolean、Array（数组数据类型只能为string、number、boolean）。<br/>- 事件的参数个数必须小于等于32。<br/>- 参数名在16个字符以内，有效的字符是0-9、a-z、下划线，只能以字母开头，不能以下划线结尾。<br/>- string类型参数值在8*1024个字符内。<br/>- Array类型参数值的元素个数必须在100个以内，超出时会进行截断处理。 | 31| callback | AsyncCallback<void> | 否 | 回调函数，可以在回调函数中处理接口返回值。<br/>- 返回值为0表示事件校验成功，事件正常异步写入事件文件；<br/>- 大于0表示事件校验存在异常参数，在忽略异常参数后将事件异步写入事件文件；<br/>- 小于0表示事件校验失败，不将事件写入事件文件。 | 32 33**示例：** 34 35``` 36hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str_data":"strValue"}, (err, value) => { 37 if (err) { 38 // 事件写入异常：事件存在异常参数时忽略异常参数后继续写入，或者事件校验失败时不执行写入 39 console.error(`failed to write event because ${err.code}`); 40 return; 41 } 42 43 // 事件写入正常 44 console.log(`success to write event: ${value}`); 45}); 46``` 47 48 49## hiAppEvent.write 50 51write(eventName: string, eventType: EventType, keyValues: object): Promise<void> 52 53应用事件打点方法，将事件写入到当天的事件文件中，可接收类型为Json对象的事件参数，使用promise方式作为异步回调。 54 55**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 56 57**参数：** 58 59| 参数名 | 类型 | 必填 | 说明 | 60| --------- | ----------------------- | ---- | ------------------------------------------------------------ | 61| eventName | string | 是 | 应用事件名称。<br/>由开发者自定义。事件名称在48个字符以内，有效的字符是0-9、a-z、下划线，只能以字母开头。 | 62| eventType | [EventType](#eventtype) | 是 | 应用事件类型。 | 63| keyValues | object | 是 | 事件参数键值对，如果是变长参数类型，则依次输入事件的参数名与参数值。如果是Json对象类型，则Json对象的key是事件的参数名，value是事件的参数值。<br/>- key类型只能为string，value类型只能为string、number、boolean、Array（数组数据类型只能为string、number、boolean）。<br/>- 事件的参数个数必须小于等于32。<br/>- 参数名在16个字符以内，有效的字符是0-9、a-z、下划线，只能以字母开头，不能以下划线结尾。<br/>- string类型参数值在8*1024个字符内。<br/>- Array类型参数值的元素个数必须在100个以内，超出时会进行截断处理。 | 64 65**返回值：** 66 67| 类型 | 说明 | 68| ------------------- | ------------------------------------------------------------ | 69| Promise<void> | Promise实例，可以在其then()、catch()方法中分别对事件写入成功、写入异常的情况进行回调处理。 | 70 71**示例：** 72 73``` 74hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str_data":"strValue"}) 75 .then((value) => { 76 // 事件写入正常 77 console.log(`success to write event: ${value}`); 78 }).catch((err) => { 79 // 事件写入异常：事件存在异常参数时忽略异常参数后继续写入，或者事件校验失败时不执行写入 80 console.error(`failed to write event because ${err.code}`); 81 }); 82``` 83 84 85## hiAppEvent.configure 86 87configure(config: ConfigOption): boolean 88 89应用事件打点配置方法，可用于配置打点开关、文件目录存储限额大小等功能。 90 91**系统能力：** SystemCapability.HiviewDFX.HiAppEvent 92 93**参数：** 94 95| 参数名 | 类型 | 必填 | 说明 | 96| ------ | ----------------------------- | ---- | ------------------------ | 97| config | [ConfigOption](#configoption) | 是 | 应用事件打点配置项对象。 | 98 99**返回值：** 100 101| 类型 | 说明 | 102| ------- | ----------------------------------------------------------- | 103| boolean | 配置结果，true 表示配置成功，false 表示配置失败。 | 104 105**示例：** 106``` 107// 配置应用事件打点功能开关 108hiAppEvent.configure({ 109 disable: true 110}); 111 112// 配置事件文件目录存储限额大小 113hiAppEvent.configure({ 114 maxStorage: '100M' 115}); 116``` 117 118 119## ConfigOption 120 121此接口提供了应用打点的配置选项。 122 123**系统能力：** 以下各项对应的系统能力均为SystemCapability.HiviewDFX.HiAppEvent。 124 125| 参数名 | 类型 | 必填 | 说明 | 126| ---------- | ------- | ---- | ------------------------------------------------------------ | 127| disable | boolean | 否 | 应用打点功能开关。配置值为true表示关闭打点功能，false表示不关闭打点功能。 | 128| maxStorage | string | 否 | 打点数据本地存储文件所在目录的配额大小，默认限额为“10M”。所在目录大小超出限额后会对目录进行清理操作，会按从旧到新的顺序逐个删除打点数据文件，直到目录大小不超出限额时停止。 | 129 130 131## EventType 132 133事件类型枚举。 134 135**系统能力：** 以下各项对应的系统能力均为SystemCapability.HiviewDFX.HiAppEvent。 136 137| 名称 | 默认值 | 说明 | 138| --------- | ------ | -------------- | 139| FAULT | 1 | 故障类型事件。 | 140| STATISTIC | 2 | 统计类型事件。 | 141| SECURITY | 3 | 安全类型事件。 | 142| BEHAVIOR | 4 | 行为类型事件。 | 143 144 145## Event 146 147此接口提供了所有预定义事件的事件名称常量。 148 149**系统能力：** 以下各项对应的系统能力均为SystemCapability.HiviewDFX.HiAppEvent。 150 151| 名称 | 参数类型 | 可读 | 可写 | 说明 | 152| ------------------------- | -------- | ---- | ---- | -------------------- | 153| USER_LOGIN | string | 是 | 否 | 用户登录事件。 | 154| USER_LOGOUT | string | 是 | 否 | 用户登出事件。 | 155| DISTRIBUTED_SERVICE_START | string | 是 | 否 | 分布式服务启动事件。 | 156 157 158## Param 159 160此接口提供了所有预定义参数的参数名称常量。 161 162**系统能力：** 以下各项对应的系统能力均为SystemCapability.HiviewDFX.HiAppEvent。 163 164| 名称 | 参数类型 | 可读 | 可写 | 说明 | 165| ------------------------------- | -------- | ---- | ---- | ------------------ | 166| USER_ID | string | 是 | 否 | 用户自定义ID。 | 167| DISTRIBUTED_SERVICE_NAME | string | 是 | 否 | 分布式服务名称。 | 168| DISTRIBUTED_SERVICE_INSTANCE_ID | string | 是 | 否 | 分布式服务实例ID。 |
