1# HiAppEvent组件<a name="ZH-CN_TOPIC_0000001162014029"></a> 2 3- [简介](#section11660541593) 4- [目录](#section161941989596) 5- [编译构建](#section137768191623) 6- [说明](#section1312121216216) 7 - [接口说明](#section1551164914237) 8 - [使用说明](#section129654513264) 9 10- [相关仓](#section1371113476307) 11 12## 简介<a name="section11660541593"></a> 13 14HiAppEvent为OpenHarmony应用提供事件打点接口，用于帮助应用记录在运行过程中发生的故障信息、统计信息、安全信息、用户行为信息，以支撑开发者分析应用的运行情况。 15 16**图 1** HiAppEvent架构图<a name="fig32154874419"></a> 17 18 19## 目录<a name="section161941989596"></a> 20 21``` 22/base/hiviewdfx/hiappevent # hiappevent部件代码 23├── frameworks # 框架代码 24│ └── native # 打点接口的native实现代码 25├── interfaces # 对外接口存放目录 26│ └── js # js接口 27│ └── innerkits # js接口内部实现代码 28│ └── napi # 基于napi实现的js接口代码 29├── test # 测试用例代码 30``` 31 32## 编译构建<a name="section137768191623"></a> 33 34依赖 Clang 编译器\(Clang 8.0.0 \)及以上，依赖C++11版本及以上。 35 36## 说明<a name="section1312121216216"></a> 37 38### 接口说明<a name="section1551164914237"></a> 39 40#### JS接口说明 41 42**表 1** JS 打点接口介绍 43 44<a name="table107919166559"></a> 45<table><thead align="left"><tr id="row1880201655520"><th class="cellrowborder" valign="top" width="15.981598159815983%" id="mcps1.2.4.1.1"><p id="p5801164558"><a name="p5801164558"></a><a name="p5801164558"></a>模块</p> 46</th> 47<th class="cellrowborder" valign="top" width="50.68506850685068%" id="mcps1.2.4.1.2"><p id="p168019163559"><a name="p168019163559"></a><a name="p168019163559"></a>方法</p> 48</th> 49<th class="cellrowborder" valign="top" width="33.33333333333333%" id="mcps1.2.4.1.3"><p id="p780101685516"><a name="p780101685516"></a><a name="p780101685516"></a>描述</p> 50</th> 51</tr> 52</thead> 53<tbody><tr id="row148011162552"><td class="cellrowborder" valign="top" width="15.981598159815983%" headers="mcps1.2.4.1.1 "><p id="p188061611553"><a name="p188061611553"></a><a name="p188061611553"></a>hiAppEvent</p> 54</td> 55<td class="cellrowborder" valign="top" width="50.68506850685068%" headers="mcps1.2.4.1.2 "><p id="p1880171695519"><a name="p1880171695519"></a><a name="p1880171695519"></a>write(string eventName, EventType type, object keyValues, AsyncCallback<void> callback): void</p> 56</td> 57<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.3 "><p id="p983410810310"><a name="p983410810310"></a><a name="p983410810310"></a>接口功能：应用事件异步打点方法，使用callback方式作为异步回调。</p> 58<p id="p683519817319"><a name="p683519817319"></a><a name="p683519817319"></a>输入参数：</p> 59<a name="ul108351681336"></a><a name="ul108351681336"></a><ul id="ul108351681336"><li>eventName：事件名称。</li><li>type：事件类型。</li><li>keyValues：事件参数键值对，为Json对象类型。</li><li>callback：回调函数，可以在回调函数中处理接口返回值。返回值为0表示事件参数校验成功，事件正常异步写入事件文件；大于0表示事件存在异常参数，事件在忽略异常参数后再异步写入事件文件；小于0表示事件校验失败，不执行事件异步打点操作。</li></ul> 60</td> 61</tr> 62<tr id="row78021665512"><td class="cellrowborder" valign="top" width="15.981598159815983%" headers="mcps1.2.4.1.1 "><p id="p1380916165510"><a name="p1380916165510"></a><a name="p1380916165510"></a>hiAppEvent</p> 63</td> 64<td class="cellrowborder" valign="top" width="50.68506850685068%" headers="mcps1.2.4.1.2 "><p id="p1380161665518"><a name="p1380161665518"></a><a name="p1380161665518"></a>write(string eventName, EventType type, object keyValues): Promise<void></p> 65</td> 66<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.3 "><p id="p12532811415"><a name="p12532811415"></a><a name="p12532811415"></a>接口功能：应用事件异步打点方法，使用promise方式作为异步回调。</p> 67<p id="p75313814417"><a name="p75313814417"></a><a name="p75313814417"></a>输入参数：同上。</p> 68</td> 69</tr> 70</tbody> 71</table> 72 73**表 2** JS 事件类型枚举——EventType 74 75| 类型 | 描述 | 76| --------- | -------------- | 77| FAULT | 故障类型事件。 | 78| STATISTIC | 统计类型事件。 | 79| SECURITY | 安全类型事件。 | 80| BEHAVIOR | 行为类型事件。 | 81 82**表 3** JS 打点配置接口介绍 83 84<table> 85 <tr> 86 <td>模块</td> 87 <td>方法</td> 88 <td>描述</td> 89 </tr> 90 <tr> 91 <td>hiAppEvent</td> 92 <td>configure(config: ConfigOption): boolean</td> 93 <td>接口功能：应用事件打点配置方法，可以对打点功能进行自定义配置。<br/>输入参数：<ul><li>config：应用事件打点配置项对象。</li></ul>返回值：boolean，true表示配置成功，false表示配置失败。</td> 94 </tr> 95</table> 96 97**表 4** JS 应用打点配置选项——ConfigOption 98 99| 参数名 | 类型 | 必填 | 说明 | 100| ---------- | ------- | ---- | ------------------------------------------------------------ | 101| disable | boolean | 否 | 应用打点功能开关。配置值为true表示关闭打点功能，false表示不关闭打点功能。 | 102| maxStorage | string | 否 | 打点数据本地存储文件所在目录的配额大小，默认限额为“10M”。所在目录大小超出限额后会对目录进行清理操作，会按从旧到新的顺序逐个删除打点数据文件，直到目录大小不超出限额时停止。 | 103 104**表 5** JS 预定义事件名称常量接口——Event 105 106| 常量名 | 类型 | 描述 | 107| ------------------------- | ------ | -------------------- | 108| USER_LOGIN | string | 用户登录事件。 | 109| USER_LOGOUT | string | 用户登出事件。 | 110| DISTRIBUTED_SERVICE_START | string | 分布式服务启动事件。 | 111 112**表 6** JS 预定义参数名称常量接口——Param 113 114| 常量名 | 类型 | 描述 | 115| ------------------------------- | ------ | ------------------ | 116| USER_ID | string | 用户自定义ID。 | 117| DISTRIBUTED_SERVICE_NAME | string | 分布式服务名称。 | 118| DISTRIBUTED_SERVICE_INSTANCE_ID | string | 分布式服务实例ID。 | 119 120#### Native接口说明 121 122**表 1** 打点接口介绍 123 124<table> 125 <tr> 126 <td>方法</td> 127 <td>返回值</td> 128 <td>描述</td> 129 </tr> 130 <tr> 131 <td>OH_HiAppEvent_Write(const char* domain, const char* name, enum EventType type, const ParamList list)</td> 132 <td>int</td> 133 <td>接口功能：应用事件打点方法。<br/>输入参数： 134 <ul> 135 <li>domain：事件领域。</li> 136 <li>name：事件名称。</li> 137 <li>type：事件类型。</li> 138 <li>list：事件参数列表，实质上是一个指向链表头节点的指针——ParamListNode*，列表的每个参数节点由参数名和参数值组成。</li> 139 </ul>返回值：int，错误码。 140 </td> 141 </tr> 142</table> 143 144**表 2** 事件参数列表构造接口介绍 145 146| 方法 | 返回值 | 描述 | 147| ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | 148| OH_HiAppEvent_CreateParamList() | ParamList | 创建一个ParamList节点。返回指向创建节点的指针。 | 149| OH_HiAppEvent_DestroyParamList(ParamList list) | void | 从头节点开始逐个删除参数列表的各个节点，并释放内存。 | 150| OH_HiAppEvent_AddBoolParam(ParamList list, const char* name, bool boolean) | ParamList | 创建一个bool类型的参数节点，并将该节点添加到ParamList。 | 151| OH_HiAppEvent_AddBoolArrayParam(ParamList list, const char* name, const bool* booleans, int arrSize) | ParamList | 创建一个bool数组类型的参数节点，并将该节点添加到ParamList。 | 152| OH_HiAppEvent_AddInt8Param(ParamList list, const char* name, int8_t num) | ParamList | 创建一个int8_t类型的参数节点，并将该节点添加到ParamList。 | 153| OH_HiAppEvent_AddInt8ArrayParam(ParamList list, const char* name, const int8_t* nums, int arrSize) | ParamList | 创建一个int8_t数组类型的参数节点，并将该节点添加到ParamList。 | 154| OH_HiAppEvent_AddInt16Param(ParamList list, const char* name, int16_t num) | ParamList | 创建一个int16_t类型的参数节点，并将该节点添加到ParamList。 | 155| OH_HiAppEvent_AddInt16ArrayParam(ParamList list, const char* name, const int16_t* nums, int arrSize) | ParamList | 创建一个int16_t数组类型的参数节点，并将该节点添加到ParamList。 | 156| OH_HiAppEvent_AddInt32Param(ParamList list, const char* name, int32_t num) | ParamList | 创建一个int32_t类型的参数节点，并将该节点添加到ParamList。 | 157| OH_HiAppEvent_AddInt32ArrayParam(ParamList list, const char* name, const int32_t* nums, int arrSize) | ParamList | 创建一个int32_t数组类型的参数节点，并将该节点添加到ParamList。 | 158| OH_HiAppEvent_AddInt64Param(ParamList list, const char* name, int64_t num) | ParamList | 创建一个int64_t类型的参数节点，并将该节点添加到ParamList。 | 159| OH_HiAppEvent_AddInt64ArrayParam(ParamList list, const char* name, const int64_t* nums, int arrSize) | ParamList | 创建一个int64_t数组类型的参数节点，并将该节点添加到ParamList。 | 160| OH_HiAppEvent_AddFloatParam(ParamList list, const char* name, float num) | ParamList | 创建一个float类型的参数节点，并将该节点添加到ParamList。 | 161| OH_HiAppEvent_AddFloatArrayParam(ParamList list, const char* name, const float* nums, int arrSize) | ParamList | 创建一个float数组类型的参数节点，并将该节点添加到ParamList。 | 162| OH_HiAppEvent_AddDoubleParam(ParamList list, const char* name, double num) | ParamList | 创建一个double类型的参数节点，并将该节点添加到ParamList。 | 163| OH_HiAppEvent_AddDoubleArrayParam(ParamList list, const char* name, const double* nums, int arrSize) | ParamList | 创建一个double数组类型的参数节点，并将该节点添加到ParamList。 | 164| OH_HiAppEvent_AddStringParam(ParamList list, const char* name, const char* str) | ParamList | 创建一个char*类型的参数节点，并将该节点添加到ParamList。 | 165| OH_HiAppEvent_AddStringArrayParam(ParamList list, const char* name, const char * const *strs, int arrSize) | ParamList | 创建一个char*数组类型的参数节点，并将该节点添加到ParamList。 | 166 167**表 3** 打点配置接口介绍 168 169<table> 170 <tr> 171 <td>方法</td> 172 <td>返回值</td> 173 <td>描述</td> 174 </tr> 175 <tr> 176 <td>OH_HiAppEvent_Configure(const char* name, const char* value)</td> 177 <td>bool</td> 178 <td>接口功能：应用事件打点配置方法，可以对打点功能进行自定义配置。<br/>输入参数： 179 <ul> 180 <li>name：配置项名称，可直接传入预定义好的配置项常量。</li> 181 <li>value：配置项值。</li> 182 </ul>返回值：bool，返回true表示配置成功，返回false表示配置失败。 183 </td> 184 </tr> 185</table> 186 187**表 4** 配置项常量介绍 188 189| 常量名 | 类型 | 描述 | 190| ----------- | ------------ | ------------------------------------------------------------ | 191| DISABLE | const char[] | 打点功能开关的配置项名称，对应的默认配置值为“false”表示不关闭打点功能。 | 192| MAX_STORAGE | const char[] | 打点落盘文件存放目录配额大小的配置项名称，对应的默认配置值为“10M”。 | 193 194**表 5** 预定义事件名称常量介绍 195 196| 常量名 | 类型 | 描述 | 197| ------------------------------- | ------------ | ------------------------ | 198| EVENT_USER_LOGIN | const char[] | 用户登录事件名称。 | 199| EVENT_USER_LOGOUT | const char[] | 用户登出事件名称。 | 200| EVENT_DISTRIBUTED_SERVICE_START | const char[] | 分布式服务启动事件名称。 | 201 202**表 6** 预定义参数名称常量介绍 203 204| 类型 | 描述 | | 205| ------------------------------------- | ------------ | ------------------ | 206| PARAM_USER_ID | const char[] | 用户自定义ID。 | 207| PARAM_DISTRIBUTED_SERVICE_NAME | const char[] | 分布式服务名称。 | 208| PARAM_DISTRIBUTED_SERVICE_INSTANCE_ID | const char[] | 分布式服务实例ID。 | 209 210### 使用说明<a name="section129654513264"></a> 211 212#### JS接口开发实例 213 2141. 源代码开发 215 216 引入模块： 217 218 ```js 219 import hiAppEvent from '@ohos.hiAppEvent' 220 ``` 221 2222. 应用执行事件打点 223 224 ```js 225 // callback方式 226 hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str_data":"strValue"}, (err, value) => { 227 if (err) { 228 // 事件写入异常：事件存在异常参数或者事件校验失败不执行写入 229 console.error(`failed to write event because ${err.code}`); 230 return; 231 } 232 233 // 事件写入正常 234 console.log(`success to write event: ${value}`); 235 }); 236 237 // Promise方式 238 hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str_data":"strValue"}) 239 .then((value) => { 240 // 事件写入正常 241 console.log(`success to write event: ${value}`); 242 }).catch((err) => { 243 // 事件写入异常：事件存在异常参数或者事件校验失败不执行写入 244 console.error(`failed to write event because ${err.code}`); 245 }); 246 ``` 247 2483. 应用对打点功能进行自定义配置 249 250 ```js 251 // 配置应用事件打点功能开关 252 hiAppEvent.configure({ 253 disable: true 254 }) 255 256 // 配置事件文件目录存储限额大小 257 hiAppEvent.configure({ 258 maxStorage: '100M' 259 }) 260 ``` 261 262#### Native接口开发实例 263 2641. 源代码开发 265 266 引入模块： 267 268 ```c++ 269 #include "hiappevent/hiappevent.h" 270 ``` 271 2722. 应用执行事件打点 273 274 ```c++ 275 // 1. 创建空参数list 276 ParamList list = OH_HiAppEvent_CreateParamList(); 277 278 // 2. 向list添加要传入的键值对参数 279 // 2.1 传入int32_t参数值 280 int32_t num = 1; 281 OH_HiAppEvent_AddInt32Param(list, "int32_key", num); 282 // 2.2 传入int32_t数组参数值 283 int32_t nums3[] = {1, INT32_MAX, INT32_MIN}; 284 OH_HiAppEvent_AddInt32ArrayParam(list, "int32_arr_key", nums3, sizeof(nums3) / sizeof(nums3[0])); 285 // 2.3 传入字符串数组参数值 286 char str1[] = "hello"; 287 char str2[] = "world"; 288 char* strs[] = {str1, str2}; 289 OH_HiAppEvent_AddStringArrayParam(list, "string_arr_key", strs, sizeof(strs) / sizeof(strs[0])); 290 291 // 3. 执行打点操作 292 int result = OH_HiAppEvent_Write("domain", "name", BEHAVIOR, list); 293 printf("HiAppEvent logging test, res=%d\n", result); 294 295 // 4. 销毁ParamLIst对象，释放内存 296 OH_HiAppEvent_DestroyParamList(list); 297 ``` 298 2993. 应用对打点功能进行自定义配置 300 301 ```c++ 302 // 关闭应用打点功能 303 OH_HiAppEvent_Configure(DISABLE, "true"); 304 305 // 配置打点数据文件目录存储限额为100M 306 OH_HiAppEvent_Configure(MAX_STORAGE, "100M"); 307 ``` 308 309## 相关仓<a name="section1371113476307"></a> 310 311[DFX子系统](https://gitee.com/openharmony/docs/blob/master/zh-cn/readme/DFX%E5%AD%90%E7%B3%BB%E7%BB%9F.md) 312 313[hiviewdfx\_hiview](https://gitee.com/openharmony/hiviewdfx_hiview/blob/master/README_zh.md) 314 315[hiviewdfx\_hilog](https://gitee.com/openharmony/hiviewdfx_hilog/blob/master/README_zh.md) 316 317**hiviewdfx\_hiappevent** 318 319[hiviewdfx\_hisysevent](https://gitee.com/openharmony/hiviewdfx_hisysevent/blob/master/README_zh.md) 320 321[hiviewdfx\_faultloggerd](https://gitee.com/openharmony/hiviewdfx_faultloggerd/blob/master/README_zh.md) 322 323[hiviewdfx\_hilog\_lite](https://gitee.com/openharmony/hiviewdfx_hilog_lite/blob/master/README_zh.md) 324 325[hiviewdfx\_hievent\_lite](https://gitee.com/openharmony/hiviewdfx_hievent_lite/blob/master/README_zh.md) 326 327[hiviewdfx\_hiview\_lite](https://gitee.com/openharmony/hiviewdfx_hiview_lite/blob/master/README_zh.md) 328 329