提交 86cdb02b 编写于 作者: O openharmony_ci 提交者: Gitee

!891 增加应用事件打点开发指南

Merge pull request !891 from zengyawen/master
......@@ -2,19 +2,15 @@
- [Application Development Overview](application-dev-guide.md)
- [DevEco Studio \(OpenHarmony\) User Guide](quick-start/deveco-studio-user-guide-for-openharmony.md)
- [Directory Structure](quick-start/package-structure.md)
- [Getting Started](quick-start/start.md)
- [ArkUI](ui/ui-arkui.md)
- [JavaScript-based Web-like Development Paradigm](ui/ui-arkui-js.md)
- [TypeScript-based Declarative Development Paradigm](ui/ui-arkui-ts.md)
- [Audio](media/audio.md)
- [IPC & RPC](connectivity/ipc-rpc.md)
- [Application Event Logging](application-event-logging/hiappevent.md)
- [JavaScript Development References](js-reference/js-reference.md)
- [JavaScript-based Web-like Development Paradigm](js-reference/js-based-web-like-development-paradigm/js-web-development-like.md)
......
# Development Guidelines on Application Event Logging
## When to Use
The event logging function helps applications log various information generated during running.
## Available APIs
JS application event logging APIs are provided by the **hiAppEvent** module.
**APIs for event logging:**
| API | Return Value | Description |
| ------------------------------------------------------------ | -------------- | ------------------------------------------------------------ |
| write(string eventName, EventType type, object keyValues, AsyncCallback\<void> callback): void | void | Logs application events in asynchronous mode. This method uses an asynchronous callback to return the result. |
| write(string eventName, EventType type, object keyValues): Promise\<void> | Promise\<void> | Logs application events in asynchronous mode. This method uses a promise to return the result. |
- **eventName**: event name you customized. The event name can contain a maximum of 48 characters, including digits (0 to 9), letters (a to z), and underscores (\_). It must start with a letter.
- **type**: event type enumerated by **EventType**.
| Type | Description |
| --------- | ----------------- |
| FAULT | Fault event |
| STATISTIC | Statistical event |
| SECURITY | Security event |
| BEHAVIOR | Behavior event |
- **keyValues**: event parameter key-value pair. For a variable-length parameter, enter each pair of parameter name and value in sequence. For a JSON parameter, enter the parameter name as the key and parameter value as the value.
- A parameter name must be a string, and a parameter value must be a string, number, boolean, or array (which is a basic element).
- The number of event parameters must be less than or equal to 32.
- The parameter name can contain a maximum of 16 characters, including digits (0 to 9), letters (a to z), and underscores (\_). It must start with a letter and cannot end with an underscore (\_).
- A string value can contain a maximum of 8*1024 characters.
- An array value can contain a maximum of 100 elements. Excess elements will be truncated.
- **callback**: callback function used to process the received return value. The value **0** indicates that the event parameter verification is successful, and the event will be written to the event file asynchronously. A value greater than **0** indicates that invalid parameters are present in the event, and the event will be written to the event file asynchronously after the invalid parameters are ignored. A value smaller than **0** indicates that the event parameter verification fails, and the event will not be written to the event file asynchronously.
When an asynchronous callback is used, the return value can be processed directly in the callback. When a promise is used, the return value can also be processed in the promise in a similar way. For details about the result codes, see [Event Verification Result Codes](hiappevent-overview.md#Event Verification Result Codes).
**APIs for event logging configuration:**
| API | Return Value | Description |
| ------------------------------ | ------------ | ------------------------------------------------------------ |
| configure(ConfigOption config) | boolean | Sets the configuration options for application event logging.<br/>The value **true** indicates that the operation is successful, and value **false** indicates the opposite. |
- **config**: configuration options for application event logging.
Configuration options for application event logging (**ConfigOption**)
| Name | Type | Mandatory | Description |
| ---------- | ------- | --------- | ------------------------------------------------------------ |
| disable | boolean | No | Sets the application event logging switch. The value **true** means to disable the application event logging function, and value **false** means the opposite. |
| maxStorage | string | No | Specifies the maximum size of the event file storage directory. The default value is 10M. |
**Predefined event name constants (Event)**:
| Constant | Type | Description |
| ------------------------- | ------ | ---------------------------------------------- |
| USER_LOGIN | string | Name of the user login event. |
| USER_LOGOUT | string | Name of the user logout event. |
| DISTRIBUTED_SERVICE_START | string | Name of the distributed service startup event. |
**Predefined parameter name constants (Param):**
| Constant | Type | Description |
| ------------------------------- | ------ | -------------------------------- |
| USER_ID | string | Custom user ID. |
| DISTRIBUTED_SERVICE_NAME | string | Distributed service name. |
| DISTRIBUTED_SERVICE_INSTANCE_ID | string | Distributed service instance ID. |
## How to Develop
In this example, an application event is logged after the application startup execution page is loaded.
1. Create a JS application project. In the displayed Project window, choose **entry > src > main** > **js** > **default** > **pages > index**, and double-click index.js. Add the code to log the initial application event after page loading. The sample code is as follows:
```js
import hiAppEvent from '@ohos.hiAppEvent'
export default {
data: {
title: ""
},
onInit() {
this.title = this.$t('strings.world');
// 1. Callback mode
hiAppEvent.write("start_event", hiAppEvent.EventType.BEHAVIOR, {"int_data":100, "str_data":"strValue"}, (err, value) => {
if (err) {
console.error(`failed to write event because ${err.code}`);
return;
}
console.log(`success to write event: ${value}`);
});
// 2. Promise mode
hiAppEvent.write("start_event", hiAppEvent.EventType.BEHAVIOR, {"int_data":100, "str_data":"strValue"})
.then((value) => {
console.log(`success to write event: ${value}`);
}).catch((err) => {
console.error(`failed to write event because ${err.code}`);
});
});
// 3. Set the application event logging switch.
hiAppEvent.configure({
disable: true
});
// 4. Set the maximum size of the event file storage directory. The default value is 10M.
hiAppEvent.configure({
maxStorage: '100M'
});
}
}
```
2. Tap the run button on the application UI to run the project.
# Overview of Application Event Logging
HiAppEvent provides event logging APIs for applications to log the fault, statistical, security, and user behavior events reported during running. Based on event information, you will be able to analyze the running status of your application.
## Basic Concepts
The HiAppEvent module of OpenHarmony can be used to develop application event services and provide functions related to application events, including flushing application events to a disk and querying historical application event data.
- **Logging**
Logs changes caused by user operations to provide service data for development, product, and O&M analysis.
## Event Verification Result Codes
| Result Code | Cause | Check Rule | Processing Method |
| ----------- | ---------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| 0 | None | Event verification is successful. | Event logging is normal. No action is required. |
| -1 | Invalid event name | The event name is not empty and contains a maximum of 48 characters.<br/>The event name consists of only the following characters: digits (0 to 9), letters (a to z), and underscore (\_).<br/>The event name does not start with a digit or underscore (_). | Ignore this event and do not perform logging. |
| -2 | Invalid event parameter type | The event name must be a string.<br/>The event type must be a number.<br/>The key value must be an object. | Ignore this event and do not perform logging. |
| -99 | Application event logging disabled | The application event logging function is disabled. | Ignore this event and do not perform logging. |
| -100 | Unknown error | None | Ignore this event and do not perform logging. |
| 1 | Invalid key name | The key name is not empty and contains a maximum of 16 characters.<br/>The key name consists of only the following characters: digits (0 to 9), letters (a to z), and underscore (\_).<br/>The key name does not start with a digit or underscore (\_).<br/>The key name does not end with an underscore (_). | Ignore the key-value pair and continue to perform logging. |
| 2 | Invalid key type | The key must be a string. | Ignore the key-value pair and continue to perform logging. |
| 3 | Invalid value type | The supported value types vary depending on the programming language:<br/>boolean, number, string, or Array [basic element] | Ignore the key-value pair and continue to perform logging. |
| 4 | Value too long | The value can contain a maximum of 8*1024 characters. | Ignore the key-value pair and continue to perform logging. |
| 5 | Excess key-value pairs | The number of key-value pairs must be less than or equal to 32. | Ignore the excess key-value pairs and continue to perform logging. |
| 6 | Excess elements in a list value | The number of elements in a list value must be less than or equal to 100. | Truncate the list with only the first 100 elements retained, and continue to perform logging. |
| 7 | Invalid list value | A list value can only be a basic element.<br/>The elements in a list value must be of the same type. | Ignore the key-value pair and continue to perform logging. |
\ No newline at end of file
# Application Event Logging
- [Overview of Application Event Logging](hiappevent-overview.md)
- [Development Guidelines on Application Event Logging](hiappevent-guidelines.md)
......@@ -10,5 +10,6 @@
- [基于TS扩展的声明式开发范式](ui/ui-arkui-ts.md)
- [音频](media/audio.md)
- [IPC与RPC通信](connectivity/ipc-rpc.md)
- [应用事件打点](application-event-logging/hiappevent.md)
- [JS 开发参考](js-reference/Readme-CN.md)
# 应用事件开发指导
## 场景介绍
应用事件打点的主要工作是在应用运行过程中,帮助应用记录在运行过程中发生的各种信息。
## 接口说明
应用事件JS打点接口由hiAppEvent模块提供。
**打点接口功能介绍:**
| 接口名 | 返回值 | 描述 |
| ------------------------------------------------------------ | -------------- | ---------------------------------------------------- |
| write(string eventName, EventType type, object keyValues, AsyncCallback\<void> callback): void | void | 应用事件异步打点方法,使用callback方式作为异步回调。 |
| write(string eventName, EventType type, object keyValues): Promise\<void> | Promise\<void> | 应用事件异步打点方法,使用promise方式作为异步回调。 |
- 参数eventName:开发者自定义事件名称。事件名称在48个字符以内,有效的字符是0-9、a-z、下划线,只能以字母开头。
- 参数type:事件所属的类型,取值为枚举EventType,具体值如下表。
| 类型 | 描述 |
| --------- | -------------- |
| FAULT | 故障类型事件。 |
| STATISTIC | 统计类型事件。 |
| SECURITY | 安全类型事件。 |
| BEHAVIOR | 行为类型事件。 |
- 参数keyValues:事件参数键值对,如果是变长参数类型,则依次输入事件的参数名与参数值。如果是Json对象类型,则Json对象的key是事件的参数名,value是事件的参数值。
- 参数名只支持string类型,参数值只支持boolean、number、string、Array(数组参数值为基本类型)。
- 事件的参数个数必须小于等于32。
- 参数名在16个字符以内,有效的字符是0-9、a-z、下划线,只能以字母开头,不能以下划线结尾。
- string类型参数值在8*1024个字符内。
- Array类型参数值的元素个数必须在100个以内,超出时会进行截断处理。
- 参数callback:回调函数,可以在回调函数中处理接口返回值。返回值为0表示事件参数校验成功,事件正常异步写入事件文件;大于0表示事件存在异常参数,事件在忽略异常参数后再异步写入事件文件;小于0表示事件校验失败,不执行事件异步打点操作。
当采用callback作为异步回调时,可以在callback中进行下一步处理。当采用Promise对象返回时,可以在Promise对象中类似地处理接口返回值。具体结果码说明见[事件校验结果码](hiappevent-overview.md#事件校验结果码)
**打点配置接口功能介绍:**
| 接口名 | 返回值 | 描述 |
| ------------------------------ | ------- | ------------------------------------------------------------ |
| configure(ConfigOption config) | boolean | 应用事件打点配置方法,可以对打点功能进行自定义配置。返回true表示配置成功,false表示配置失败。 |
- 参数config:应用事件打点配置项对象。应用打点配置选项ConfigOption如下表。
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ------- | ---- | ------------------------------------------------------------ |
| disable | boolean | 否 | 应用打点功能开关,例如配置值为true表示关闭打点功能。 |
| maxStorage | string | 否 | 打点落盘文件存放目录的配额大小,默认限额为“10M”,超出限额后会对存放目录进行清理。 |
**预定义事件名称常量接口Event:**
| 常量名 | 类型 | 描述 |
| ------------------------- | ------ | ------------------------ |
| USER_LOGIN | string | 用户登录事件名称。 |
| USER_LOGOUT | string | 用户登出事件名称。 |
| DISTRIBUTED_SERVICE_START | string | 分布式服务启动事件名称。 |
**预定义参数名称常量接口Param:**
| 常量名 | 类型 | 描述 |
| ------------------------------- | ------ | ------------------ |
| USER_ID | string | 用户自定义ID。 |
| DISTRIBUTED_SERVICE_NAME | string | 分布式服务名称。 |
| DISTRIBUTED_SERVICE_INSTANCE_ID | string | 分布式服务示例ID。 |
## 开发步骤
在应用启动执行页面加载后,执行一个应用事件打点,用于记录应用的初始页面加载事件。
1. 新建一个JS应用工程,在“Project”窗口点击“entry > src > main > js > default > pages > index”,打开工程中的“index.js”文件,在页面执行加载后,执行一个应用事件打点,用于记录应用的初始页面加载事件,示例代码如下:
```js
import hiAppEvent from '@ohos.hiAppEvent'
export default {
data: {
title: ""
},
onInit() {
this.title = this.$t('strings.world');
// 1.callback方式
hiAppEvent.write("start_event", hiAppEvent.EventType.BEHAVIOR, {"int_data":100, "str_data":"strValue"}, (err, value) => {
if (err) {
console.error(`failed to write event because ${err.code}`);
return;
}
console.log(`success to write event: ${value}`);
});
// 2.Promise方式
hiAppEvent.write("start_event", hiAppEvent.EventType.BEHAVIOR, {"int_data":100, "str_data":"strValue"})
.then((value) => {
console.log(`success to write event: ${value}`);
}).catch((err) => {
console.error(`failed to write event because ${err.code}`);
});
});
// 3.配置应用打点开关
hiAppEvent.configure({
disable: true
});
// 4.配置事件文件目录限额(默认为10M)
hiAppEvent.configure({
maxStorage: '100M'
});
}
}
```
2. 运行项目,点击应用界面上的运行按钮。
# 应用事件打点概述
HiAppEvent提供了应用事件打点接口,为应用提供事件打点的功能,用于帮助应用记录在运行过程中发生的故障信息、统计信息、安全信息、用户行为信息,以支撑开发者分析应用的运行情况。
## 基本概念
OpenHarmony系统HiAppEvent模块支持应用事件业务的开发,提供应用事件相关的功能,主要包括应用事件落盘、查询历史应用事件数据等功能。
- **打点**
记录由用户操作引起的变化,提供业务数据信息,以供开发、产品、运维分析。
## 事件校验结果码
| 错误码 | 原因 | 校验规则 | 处理结果 |
| ------ | --------------------------- | ------------------------------------------------------------ | ----------------------------------------------------- |
| 0 | 无 | 事件校验成功 | 事件正常打点。 |
| -1 | 无效的事件名称 | 非空且长度在48个字符以内(含)。<br>只由以下字符组成:0-9、a-z、_。<br/>非数字以及下划线开头。 | 忽略该事件,不执行打点。 |
| -2 | 无效的事件基本参数类型 | 事件名称参数必须为string。<br/>事件类型参数必须为number类型。<br/>keyValues参数必须为object类型。 | 忽略该事件,不执行打点。 |
| -99 | 应用打点功能被关闭 | 应用打点功能被关闭。 | 忽略该事件,不执行打点。 |
| -100 | 未知错误 | 无。 | 忽略该事件,不执行打点。 |
| 1 | 无效的key参数名称 | 非空且长度在16个字符以内(含)。<br/>只由以下字符组成:0-9、a-z、_。<br/>非数字以及下划线开头。<br/>非下划线结尾。 | 忽略该键值对参数后,继续执行打点。 |
| 2 | 无效的key参数类型 | Key参数必须为字符串类型。 | 忽略该键值对参数后,继续执行打点。 |
| 3 | 无效的value参数类型 | value参数只支持以下类型:<br/>boolean、number、string、Array[基本类型]。<br/> | 忽略该键值对参数后,继续执行打点。 |
| 4 | value参数值过长 | 参数值长度必须在8*1024个字符以内(含)。 | 忽略该键值对参数后,继续执行打点。 |
| 5 | key-value参数对数过多 | key-value参数对数必须在32对以内(含)。 | 忽略后面多余的键值对参数后,继续执行打点。 |
| 6 | List类型的value参数容量过大 | List类型的value参数容量必须在100个以内(含)。 | 对List进行截断(只保留前100个元素)后,继续执行打点。 |
| 7 | 无效的List类型value参数 | List的泛型类型只能为基本类型。<br/>List内的参数必须为同一类型。 | 忽略该键值对参数后,继续执行打点。 |
\ No newline at end of file
# 应用事件打点
- [应用事件打点概述](hiappevent-overview.md)
- [应用事件打点开发指导](hiappevent-guidelines.md)
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册