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