diff --git a/zh-cn/application-dev/dfx/hiappevent-guidelines.md b/zh-cn/application-dev/dfx/hiappevent-guidelines.md index cdecfcafbb0a94aaf26271a49abd3dabd0908a83..d56dc9a859e36738bb3a819cdb73ee628da4da86 100644 --- a/zh-cn/application-dev/dfx/hiappevent-guidelines.md +++ b/zh-cn/application-dev/dfx/hiappevent-guidelines.md @@ -1,4 +1,4 @@ -# 应用事件开发指导 +# 应用事件打点开发指导 ## 场景介绍 @@ -8,7 +8,7 @@ 应用事件JS打点接口由hiAppEvent模块提供。 -以下仅提供简单的接口介绍，API接口的具体使用说明（参数使用限制、具体取值范围等），请参考[应用事件打点API文档](../reference/apis/js-apis-hiappevent.md)。 +以下仅提供简单的接口介绍，API接口的具体使用说明（参数使用限制、具体取值范围等）请参考[应用事件打点API文档](../reference/apis/js-apis-hiviewdfx-hiappevent.md)。 **打点接口功能介绍：** @@ -17,17 +17,11 @@ | write(AppEventInfo info, AsyncCallback\ callback): void | 应用事件异步打点方法，使用callback方式作为异步回调。 | | write(AppEventInfo info): Promise\ | 应用事件异步打点方法，使用Promise方式作为异步回调。 | -当采用callback作为异步回调时，可以在callback中进行下一步处理。 - -当采用Promise对象返回时，也可以在Promise对象中类似地处理接口返回值。 - -具体结果码说明见[事件校验结果码](#事件校验结果码)。 - **打点配置接口功能介绍：** -| 接口名 | 描述 | -| --------------------------------------- | ---------------------------------------------------- | -| configure(ConfigOption config): boolean | 应用事件打点配置方法，可以对打点功能进行自定义配置。 | +| 接口名 | 描述 | +| ------------------------------------ | ---------------------------------------------------- | +| configure(ConfigOption config): void | 应用事件打点配置方法，可以对打点功能进行自定义配置。 | **订阅接口功能介绍：** @@ -42,24 +36,6 @@ | ----------------- | -------------------- | | clearData(): void | 清除本地的打点数据。 | -### 事件校验结果码 - -| 错误码 | 原因 | 校验规则 | 处理结果 | -| ------ | ----------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------- | -| 0 | 无 | 事件校验成功 | 事件正常打点。 | -| -1 | 无效的事件名称 | 非空且长度在48个字符以内（含）。
只由以下字符组成：0-9、a-z、_。
非数字以及下划线开头。 | 忽略该事件，不执行打点。 | -| -2 | 无效的事件基本参数类型 | 事件名称参数必须为string。
事件类型参数必须为number类型。
事件参数必须为object类型。 | 忽略该事件，不执行打点。 | -| -4 | 无效的事件领域名称 | 非空且长度在32个字符以内（含）。
只由以下字符组成：0-9、a-z、_。
非数字以及下划线开头。 | 忽略该事件，不执行打点。 | -| -99 | 应用打点功能被关闭 | 应用打点功能被关闭。 | 忽略该事件，不执行打点。 | -| -100 | 未知错误 | 无。 | 忽略该事件，不执行打点。 | -| 1 | 无效的key参数名称 | 非空且长度在16个字符以内（含）。
只由以下字符组成：0-9、a-z、_。
非数字以及下划线开头。
非下划线结尾。 | 忽略该键值对参数后，继续执行打点。 | -| 2 | 无效的key参数类型 | Key参数必须为字符串类型。 | 忽略该键值对参数后，继续执行打点。 | -| 3 | 无效的value参数类型 | value参数只支持以下类型：
boolean、number、string、Array[基本类型]。 | 忽略该键值对参数后，继续执行打点。 | -| 4 | 非法长度的string类型value参数 | 参数值长度必须在8*1024个字符以内（含）。 | 对字符串进行截断（只保留前8*1024个字符）后，继续执行打点。 | -| 5 | key-value参数对数过多 | key-value参数对数必须在32对以内（含）。 | 忽略后面多余的键值对参数后，继续执行打点。 | -| 6 | 非法容量的Array类型value参数 | Array类型的value参数容量必须在100个以内（含）。 | 对数组进行截断（只保留前100个元素）后，继续执行打点。 | -| 7 | 非法类型的Array类型value参数 | Array内的参数必须为同一类型，且只能为boolean、number、string类型。 | 忽略该键值对参数后，继续执行打点。 | - ## 开发步骤 以一次应用事件打点订阅流程为例，说明开发步骤。 @@ -67,7 +43,7 @@ 1. 新建一个ets应用工程，编辑工程中的“entry > src > main > ets > pages > index.ets” 文件，依次添加三个按钮，以对应用事件打点订阅流程进行模拟。其中，按钮1模拟了应用事件打点的调用，按钮2模拟了添加自动触发回调的事件订阅者的调用，按钮3模拟了移除事件订阅者的调用，完整示例代码如下： ```ts - import hiAppEvent from '@ohos.hiAppEvent'; + import hiAppEvent from '@ohos.hiviewdfx.hiAppEvent'; @Entry @Component @@ -91,10 +67,10 @@ int_data: 100, str_data: "strValue" } - }).then((value) => { - console.log(`HiAppEvent success to write event: ${value}`); + }).then(() => { + console.log(`HiAppEvent success to write event`); }).catch((err) => { - console.error(`HiAppEvent failed to write event because ${err.code}`); + console.error(`code: ${err.code}, message: ${err.message}`); }); }) diff --git a/zh-cn/application-dev/dfx/hiappevent-overview.md b/zh-cn/application-dev/dfx/hiappevent-overview.md index 49d4a3baf10bec20a6239b24835fadba32271187..0a6d27bebe4dcd32a06284d31734267413ceb86d 100644 --- a/zh-cn/application-dev/dfx/hiappevent-overview.md +++ b/zh-cn/application-dev/dfx/hiappevent-overview.md @@ -4,7 +4,7 @@ HiAppEvent提供了应用事件打点接口，为应用提供事件打点的功 ## 基本概念 -HiAppEvent模块支持应用事件业务的开发，提供应用事件相关的功能，主要包括应用事件落盘、应用事件订阅、应用事件清理等功能。 +HiAppEvent模块支持应用事件业务的开发，提供应用事件相关的功能，主要包括应用事件落盘、应用事件订阅、应用事件清理、打点功能配置等功能。 **打点**：记录由用户操作引起的变化，提供业务数据信息，以供开发、产品、运维分析。 diff --git a/zh-cn/application-dev/reference/apis/js-apis-hiappevent.md b/zh-cn/application-dev/reference/apis/js-apis-hiappevent.md index 64bcef93dbd8f297263d84e1f00c7278c0b68430..b2aa4eead87307c8f41758558d1f6c851dfabe67 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-hiappevent.md +++ b/zh-cn/application-dev/reference/apis/js-apis-hiappevent.md @@ -3,7 +3,8 @@ 本模块提供了应用事件打点能力，包括对打点数据的落盘，以及对打点功能的管理配置。 > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** -> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 +> - 本模块接口从API version 9开始废弃，建议使用新接口[@ohos.hiviewdfx.hiAppEvent](js-apis-hiviewdfx-hiappevent)替代。 +> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 ## 导入模块 @@ -16,13 +17,9 @@ import hiAppEvent from '@ohos.hiAppEvent'; 开发者在使用应用事件打点功能前，需要首先了解应用事件相关的参数规格定义。 -**事件领域** - -事件领域为string类型，字符串非空且长度在32个字符以内，有效的字符是0-9、a-z、下划线，不能以下划线开头。 - **事件名称** -事件名称为string类型，字符串非空且长度在48个字符以内，有效的字符是0-9、a-z、下划线，不能以下划线开头。 +事件名称为string类型，字符串非空且长度在48个字符以内，有效的字符是0-9、a-z、下划线，只能以小写字母开头，不能以下划线结尾。 **事件类型** @@ -32,7 +29,7 @@ import hiAppEvent from '@ohos.hiAppEvent'; 事件参数为object类型，key为事件的参数名称，value为事件的参数值，其规格定义如下： -- 参数名为string类型，字符串非空且长度在16个字符以内，有效的字符是0-9、a-z、下划线，不能以下划线开头或结尾； +- 参数名为string类型，字符串非空且长度在16个字符以内，有效的字符是0-9、a-z、下划线，只能以小写字母开头，不能以下划线结尾； - 参数值支持string、number、boolean、Array类型； - 参数值为string类型时，其长度需在8*1024个字符以内，超出会做截断处理； - 参数值为Array类型时，Array中的元素类型只能全为string、number、boolean中的一种，且元素个数需在100以内，超出会做丢弃处理； @@ -46,20 +43,10 @@ import hiAppEvent from '@ohos.hiAppEvent'; - 返回值大于0，表示事件校验存在异常参数，在忽略异常参数后将事件落盘到事件文件； - 返回值小于0，表示事件校验失败，不将事件落盘到事件文件。 -**订阅回调** - -开发者在调用事件订阅方法后，可以在订阅回调函数中对订阅数据进行处理，其入参定义如下： - -- curRow：返回的订阅事件数量； -- curSize：返回的订阅事件数据大小，单位为byte； -- holder：返回的订阅事件数据持有者，可以通过其对订阅事件进行处理。 - -## hiAppEvent.write(deprecated) +## hiAppEvent.write write(eventName: string, eventType: EventType, keyValues: object, callback: AsyncCallback<void>): void -> **说明：** 从 API Version 9 开始废弃，建议使用[hiAppEvent.write](#hiappeventwrite9)替代。 - 应用事件打点方法，将事件写入到当天的事件文件中，使用callback方式作为异步回调。 **系统能力：** SystemCapability.HiviewDFX.HiAppEvent @@ -89,12 +76,10 @@ hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str ``` -## hiAppEvent.write(deprecated) +## hiAppEvent.write write(eventName: string, eventType: EventType, keyValues: object): Promise<void> -> **说明：** 从 API Version 9 开始废弃，建议使用[hiAppEvent.write](#hiappeventwrite9-1)替代。 - 应用事件打点方法，将事件写入到当天的事件文件中，使用Promise方式作为异步回调。 **系统能力：** SystemCapability.HiviewDFX.HiAppEvent @@ -126,97 +111,6 @@ hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str }); ``` -## hiAppEvent.write9+ - -write(info: [AppEventInfo](#appeventinfo9), callback: AsyncCallback<void>): void - -应用事件打点方法，将事件写入到当天的事件文件中，可接收[AppEventInfo](#appeventinfo9)类型的事件对象，使用callback方式作为异步回调。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------ | ---- | -------------- | -| info | [AppEventInfo](#appeventinfo9) | 是 | 应用事件对象。 | -| callback | AsyncCallback<void> | 否 | 事件回调函数。 | - -**示例：** - -```js -hiAppEvent.write({ - domain: "test_domain", - name: "test_event", - eventType: hiAppEvent.EventType.FAULT, - params: { - 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}`); -}); -``` - -## hiAppEvent.write9+ - -write(info: [AppEventInfo](#appeventinfo9)): Promise<void> - -应用事件打点方法，将事件写入到当天的事件文件中，可接收[AppEventInfo](#appeventinfo9)类型的事件对象，使用Promise方式作为异步回调。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------------------------------ | ---- | -------------- | -| info | [AppEventInfo](#appeventinfo9) | 是 | 应用事件对象。 | - -**返回值：** - -| 类型 | 说明 | -| ------------------- | ------------------------------------------------------------ | -| Promise<void> | Promise对象，可以在其then()、catch()方法中分别对事件写入成功、写入异常的情况进行异步处理。 | - -**示例：** - -```js -hiAppEvent.write({ - domain: "test_domain", - name: "test_event", - eventType: hiAppEvent.EventType.FAULT, - params: { - 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}`); -}); -``` - -## AppEventInfo9+ - -此接口提供了应用事件信息的参数选项。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -| 名称 | 参数类型 | 必填 | 说明 | -| --------- | ----------------------- | ---- | ---------- | -| domain | string | 是 | 事件领域。 | -| name | string | 是 | 事件名称。 | -| eventType | [EventType](#eventtype) | 是 | 事件类型。 | -| params | object | 是 | 事件参数。 | - ## hiAppEvent.configure configure(config: ConfigOption): boolean @@ -262,225 +156,6 @@ hiAppEvent.configure({ | disable | boolean | 否 | 应用打点功能开关。配置值为true表示关闭打点功能，false表示不关闭打点功能。 | | maxStorage | string | 否 | 打点数据本地存储文件所在目录的配额大小，默认限额为“10M”。所在目录大小超出限额后会对目录进行清理操作，会按从旧到新的顺序逐个删除打点数据文件，直到目录大小不超出限额时停止。 | -## hiAppEvent.addWatcher9+ - -addWatcher(watcher: [Watcher](#watcher9)): [AppEventPackageHolder](#appeventpackageholder9) - -添加应用事件订阅者。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------- | -------------------- | ---- | ---------------- | -| watcher | [Watcher](#watcher9) | 是 | 应用事件订阅者。 | - -**返回值：** - -| 类型 | 说明 | -| ------------------------------------------------ | ------------------------------------ | -| [AppEventPackageHolder](#appeventpackageholder9) | 订阅数据持有者，订阅失败时返回null。 | - -**示例：** - -```js -// 1. 如果订阅者传入了回调的相关参数，则可以选择在自动触发的回调函数中对订阅事件进行处理 -hiAppEvent.addWatcher({ - name: "watcher1", - appEventFilters: [ - { - domain: "domain_test1", - eventTypes: [hiAppEvent.EventType.FAULT, hiAppEvent.EventType.BEHAVIOR] - } - ], - triggerCondition: { - row: 10, - size: 1000, - timeOut: 1 - }, - onTrigger: function (curRow, curSize, holder) { - if (holder == null) { - console.error("holder is null"); - return; - } - let eventPkg = null; - while ((eventPkg = holder.takeNext()) != null) { - console.info(`eventPkg.packageId=${eventPkg.packageId}`); - console.info(`eventPkg.row=${eventPkg.row}`); - console.info(`eventPkg.size=${eventPkg.size}`); - for (const eventInfo of eventPkg.data) { - console.info(`eventPkg.data=${eventInfo}`); - } - } - } -}); - -// 2. 如果订阅者未传入回调的相关参数，则可以选择使用返回的holder对象手动去处理订阅事件 -let holder = hiAppEvent.addWatcher({ - name: "watcher2", -}); -if (holder != null) { - let eventPkg = null; - while ((eventPkg = holder.takeNext()) != null) { - console.info(`eventPkg.packageId=${eventPkg.packageId}`); - console.info(`eventPkg.row=${eventPkg.row}`); - console.info(`eventPkg.size=${eventPkg.size}`); - for (const eventInfo of eventPkg.data) { - console.info(`eventPkg.data=${eventInfo}`); - } - } -} -``` - -## hiAppEvent.removeWatcher9+ - -removeWatcher(watcher: [Watcher](#watcher9)): void - -移除应用事件订阅者。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------- | -------------------- | ---- | ---------------- | -| watcher | [Watcher](#watcher9) | 是 | 应用事件订阅者。 | - -**示例：** - -```js -// 1. 定义一个应用事件订阅者 -let watcher = { - name: "watcher1", -} - -// 2. 开始订阅事件 -hiAppEvent.addWatcher(watcher); - -// 3. 取消订阅事件 -hiAppEvent.removeWatcher(watcher); -``` - -## Watcher9+ - -此接口提供了应用事件订阅者的参数选项。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -| 名称 | 参数类型 | 必填 | 说明 | -| ---------------- | ------------------------------------------------------------ | ---- | -------------------------------- | -| name | string | 是 | 订阅者名称，用于唯一标识订阅者。 | -| triggerCondition | [TriggerCondition](#triggercondition9) | 否 | 订阅回调触发条件。 | -| appEventFilters | [AppEventFilter](#appeventfilter9)[] | 否 | 订阅过滤条件。 | -| onTrigger | (curRow: number, curSize: number, holder: [AppEventPackageHolder](#appeventpackageholder9)) => void | 否 | 订阅回调函数 。 | - -## TriggerCondition9+ - -此接口提供了订阅者回调触发条件的参数选项。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -| 名称 | 参数类型 | 必填 | 说明 | -| ------- | -------- | ---- | -------------------------------------- | -| row | number | 否 | 满足触发回调的事件总数。 | -| size | number | 否 | 满足触发回调的事件总大小，单位为byte。 | -| timeOut | number | 否 | 满足触发回调的定时时长，单位为30s。 | - -## AppEventFilter9+ - -此接口提供了订阅者过滤应用事件的参数选项。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -| 名称 | 参数类型 | 必填 | 说明 | -| ---------- | ------------------------- | ---- | ------------------------ | -| domain | string | 是 | 需要订阅的事件领域。 | -| eventTypes | [EventType](#eventtype)[] | 否 | 需要订阅的事件类型集合。 | - -## AppEventPackageHolder9+ - -订阅数据持有者类，用于对订阅事件进行处理。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -### constructor9+ - -constructor(watcherName: string); - -类构造函数，在添加订阅时会被系统自动调用来创建一个订阅数据持有者对象并返回给开发者。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -**示例：** - -```js -let holder = hiAppEvent.addWatcher({ - name: "watcher", -}); -``` - -### setSize9+ - -setSize(size: number): void - -设置每次取出的应用事件包的数据大小阈值，单位为byte，默认值为512*1024。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -**示例：** - -```js -let holder = hiAppEvent.addWatcher({ - name: "watcher", -}); -holder.setSize(1000); -``` - -### takeNext9+ - -takeNext(): [AppEventPackage](#appeventpackage9) - -根据设置的数据大小阈值来取出订阅事件数据，当订阅事件数据全部被取出时返回null作为标识。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -**示例：** - -```js -let holder = hiAppEvent.addWatcher({ - name: "watcher", -}); -let eventPkg = holder.takeNext(); -``` - -## AppEventPackage9+ - -此接口提供了订阅返回的应用事件包的参数定义。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -| 名称 | 参数类型 | 说明 | -| --------- | -------- | ------------------------------ | -| packageId | number | 事件包ID，从0开始自动递增。 | -| row | number | 事件包的事件数量。 | -| size | number | 事件包的数据大小，单位为byte。 | -| data | string[] | 事件包的事件信息。 | - -## hiAppEvent.clearData9+ - -clearData(): void - -应用打点数据清理方法，将应用存储在本地的打点数据进行清除。 - -**系统能力：** SystemCapability.HiviewDFX.HiAppEvent - -**示例：** - -```js -hiAppEvent.clearData(); -``` - ## EventType diff --git a/zh-cn/application-dev/reference/apis/js-apis-hiviewdfx-hiappevent.md b/zh-cn/application-dev/reference/apis/js-apis-hiviewdfx-hiappevent.md new file mode 100644 index 0000000000000000000000000000000000000000..f3dd2e21bc90b44260d70f6d7954bf08136b142a --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-hiviewdfx-hiappevent.md @@ -0,0 +1,477 @@ +# 应用事件打点 + +本模块提供了应用事件打点能力，包括应用事件落盘、应用事件订阅、应用事件清理、打点功能配置等功能。 + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + +## 导入模块 + +```js +import hiAppEvent from '@ohos.hiviewdfx.hiAppEvent'; +``` + +## 使用说明 + +开发者在使用应用事件打点功能前，需要首先了解应用事件相关的使用规格。 + +**事件打点回调** + +开发者在调用事件打点方法时，可以在回调函数中对打点结果进行处理，当前支持callback形式和Promise形式的回调。 + +**事件订阅回调** + +开发者在调用事件订阅方法时，可以在订阅回调函数中对订阅数据进行处理，其入参定义如下： + +- curRow：返回的订阅事件数量； +- curSize：返回的订阅事件数据大小，单位为byte； +- holder：返回的订阅事件数据持有者，可以通过其对订阅事件进行处理。 + +## hiAppEvent.write + +write(info: [AppEventInfo](#appeventinfo), callback: AsyncCallback<void>): void + +应用事件打点方法，将事件写入到当天的事件文件中，可接收[AppEventInfo](#appeventinfo)类型的事件对象，使用callback方式作为异步回调。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------ | ---- | -------------- | +| info | [AppEventInfo](#appeventinfo) | 是 | 应用事件对象。 | +| callback | AsyncCallback<void> | 否 | 事件回调函数。 | + +**错误码：** + +以下错误码的详细介绍请参见[应用事件打点错误码](../errorcodes/errcode-hiviewdfx-hiappevent.md)。 + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------------- | +| 11100001 | Function is disabled. | +| 11101001 | Invalid event domain. | +| 11101002 | Invalid event name. | +| 11101003 | Invalid number of event parameters. | +| 11101004 | Invalid string length of the event parameter. | +| 11101005 | Invalid event parameter name. | +| 11101006 | Invalid array length of the event parameter. | + +**示例：** + +```js +hiAppEvent.write({ + domain: "test_domain", + name: "test_event", + eventType: hiAppEvent.EventType.FAULT, + params: { + int_data: 100, + str_data: "strValue" + } +}, (err) => { + if (err) { + console.error(`code: ${err.code}, message: ${err.message}`); + return; + } + console.log(`success to write event`); +}); +``` + +## hiAppEvent.write + +write(info: [AppEventInfo](#appeventinfo)): Promise<void> + +应用事件打点方法，将事件写入到当天的事件文件中，可接收[AppEventInfo](#appeventinfo)类型的事件对象，使用Promise方式作为异步回调。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------------------------------ | ---- | -------------- | +| info | [AppEventInfo](#appeventinfo) | 是 | 应用事件对象。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------- | ------------------------------------------------------------ | +| Promise<void> | Promise对象，可以在其then()、catch()方法中分别对事件写入成功、写入异常的情况进行异步处理。 | + +**错误码：** + +以下错误码的详细介绍请参见[应用事件打点错误码](../errorcodes/errcode-hiviewdfx-hiappevent.md)。 + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------------- | +| 11100001 | Function is disabled. | +| 11101001 | Invalid event domain. | +| 11101002 | Invalid event name. | +| 11101003 | Invalid number of event parameters. | +| 11101004 | Invalid string length of the event parameter. | +| 11101005 | Invalid event parameter name. | +| 11101006 | Invalid array length of the event parameter. | + +**示例：** + +```js +hiAppEvent.write({ + domain: "test_domain", + name: "test_event", + eventType: hiAppEvent.EventType.FAULT, + params: { + int_data: 100, + str_data: "strValue" + } +}).then(() => { + console.log(`success to write event`); +}).catch((err) => { + console.error(`code: ${err.code}, message: ${err.message}`); +}); +``` + +## AppEventInfo + +此接口提供了应用事件信息的参数选项。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +| 名称 | 参数类型 | 必填 | 说明 | +| --------- | ----------------------- | ---- | ---------- | +| domain | string | 是 | 事件领域。 | +| name | string | 是 | 事件名称。 | +| eventType | [EventType](#eventtype) | 是 | 事件类型。 | +| params | object | 是 | 事件参数。 | + +## hiAppEvent.configure + +configure(config: ConfigOption): void + +应用事件打点配置方法，可用于配置打点开关、文件目录存储限额大小等功能。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ----------------------------- | ---- | ------------------------ | +| config | [ConfigOption](#configoption) | 是 | 应用事件打点配置项对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[应用事件打点错误码](../errorcodes/errcode-hiviewdfx-hiappevent.md)。 + +| 错误码ID | 错误信息 | +| -------- | -------------------------------- | +| 11103001 | Invalid max storage quota value. | + +**示例：** + +```js +// 配置应用事件打点功能开关 +hiAppEvent.configure({ + disable: true +}); + +// 配置事件文件目录存储限额大小 +hiAppEvent.configure({ + maxStorage: '100M' +}); +``` + +## ConfigOption + +此接口提供了应用事件打点的配置选项。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------- | ---- | ------------------------------------------------------------ | +| disable | boolean | 否 | 应用事件打点功能开关。配置值为true表示关闭打点功能，false表示不关闭打点功能。 | +| maxStorage | string | 否 | 打点数据本地存储文件所在目录的配额大小，默认限额为“10M”。所在目录大小超出限额后会对目录进行清理操作，会按从旧到新的顺序逐个删除打点数据文件，直到目录大小不超出限额时停止。 | + +## hiAppEvent.addWatcher + +addWatcher(watcher: [Watcher](#watcher)): [AppEventPackageHolder](#appeventpackageholder) + +添加应用事件订阅者。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | -------------------- | ---- | ---------------- | +| watcher | [Watcher](#watcher) | 是 | 应用事件订阅者。 | + +**返回值：** + +| 类型 | 说明 | +| ------------------------------------------------ | ------------------------------------ | +| [AppEventPackageHolder](#appeventpackageholder) | 订阅数据持有者，订阅失败时返回null。 | + +**错误码：** + +以下错误码的详细介绍请参见[应用事件打点错误码](../errorcodes/errcode-hiviewdfx-hiappevent.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------- | +| 11102001 | Invalid watcher name. | +| 11102002 | Invalid filtering event domain. | +| 11102003 | Invalid row value. | +| 11102004 | Invalid size value. | +| 11102005 | Invalid timeout value. | + +**示例：** + +```js +// 1. 如果订阅者传入了回调的相关参数，则可以选择在自动触发的回调函数中对订阅事件进行处理 +hiAppEvent.addWatcher({ + name: "watcher1", + appEventFilters: [ + { + domain: "domain_test1", + eventTypes: [hiAppEvent.EventType.FAULT, hiAppEvent.EventType.BEHAVIOR] + } + ], + triggerCondition: { + row: 10, + size: 1000, + timeOut: 1 + }, + onTrigger: function (curRow, curSize, holder) { + if (holder == null) { + console.error("holder is null"); + return; + } + let eventPkg = null; + while ((eventPkg = holder.takeNext()) != null) { + console.info(`eventPkg.packageId=${eventPkg.packageId}`); + console.info(`eventPkg.row=${eventPkg.row}`); + console.info(`eventPkg.size=${eventPkg.size}`); + for (const eventInfo of eventPkg.data) { + console.info(`eventPkg.data=${eventInfo}`); + } + } + } +}); + +// 2. 如果订阅者未传入回调的相关参数，则可以选择使用返回的holder对象手动去处理订阅事件 +let holder = hiAppEvent.addWatcher({ + name: "watcher2", +}); +if (holder != null) { + let eventPkg = null; + while ((eventPkg = holder.takeNext()) != null) { + console.info(`eventPkg.packageId=${eventPkg.packageId}`); + console.info(`eventPkg.row=${eventPkg.row}`); + console.info(`eventPkg.size=${eventPkg.size}`); + for (const eventInfo of eventPkg.data) { + console.info(`eventPkg.data=${eventInfo}`); + } + } +} +``` + +## hiAppEvent.removeWatcher + +removeWatcher(watcher: [Watcher](#watcher)): void + +移除应用事件订阅者。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | -------------------- | ---- | ---------------- | +| watcher | [Watcher](#watcher) | 是 | 应用事件订阅者。 | + +**错误码：** + +以下错误码的详细介绍请参见[应用事件打点错误码](../errorcodes/errcode-hiviewdfx-hiappevent.md)。 + +| 错误码ID | 错误信息 | +| -------- | --------------------- | +| 11102001 | Invalid watcher name. | + +**示例：** + +```js +// 1. 定义一个应用事件订阅者 +let watcher = { + name: "watcher1", +} + +// 2. 开始订阅事件 +hiAppEvent.addWatcher(watcher); + +// 3. 取消订阅事件 +hiAppEvent.removeWatcher(watcher); +``` + +## Watcher + +此接口提供了应用事件订阅者的参数选项。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +| 名称 | 参数类型 | 必填 | 说明 | +| ---------------- | ------------------------------------------------------------ | ---- | -------------------------------- | +| name | string | 是 | 订阅者名称，用于唯一标识订阅者。 | +| triggerCondition | [TriggerCondition](#triggercondition) | 否 | 订阅回调触发条件。 | +| appEventFilters | [AppEventFilter](#appeventfilter)[] | 否 | 订阅过滤条件。 | +| onTrigger | (curRow: number, curSize: number, holder: [AppEventPackageHolder](#appeventpackageholder)) => void | 否 | 订阅回调函数 。 | + +## TriggerCondition + +此接口提供了订阅者回调触发条件的参数选项。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +| 名称 | 参数类型 | 必填 | 说明 | +| ------- | -------- | ---- | -------------------------------------- | +| row | number | 否 | 满足触发回调的事件总数。 | +| size | number | 否 | 满足触发回调的事件总大小，单位为byte。 | +| timeOut | number | 否 | 满足触发回调的定时时长，单位为30s。 | + +## AppEventFilter + +此接口提供了订阅者过滤应用事件的参数选项。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +| 名称 | 参数类型 | 必填 | 说明 | +| ---------- | ------------------------- | ---- | ------------------------ | +| domain | string | 是 | 需要订阅的事件领域。 | +| eventTypes | [EventType](#eventtype)[] | 否 | 需要订阅的事件类型集合。 | + +## AppEventPackageHolder + +订阅数据持有者类，用于对订阅事件进行处理。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +### constructor + +constructor(watcherName: string); + +类构造函数，在添加订阅时会被系统自动调用来创建一个订阅数据持有者对象并返回给开发者。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +**示例：** + +```js +let holder = hiAppEvent.addWatcher({ + name: "watcher", +}); +``` + +### setSize + +setSize(size: number): void + +设置每次取出的应用事件包的数据大小阈值，单位为byte，默认值为512*1024。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +**错误码：** + +以下错误码的详细介绍请参见[应用事件打点错误码](../errorcodes/errcode-hiviewdfx-hiappevent.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------- | +| 11104001 | Invalid size value. | + +**示例：** + +```js +let holder = hiAppEvent.addWatcher({ + name: "watcher", +}); +holder.setSize(1000); +``` + +### takeNext + +takeNext(): [AppEventPackage](#appeventpackage) + +根据设置的数据大小阈值来取出订阅事件数据，当订阅事件数据全部被取出时返回null作为标识。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +**示例：** + +```js +let holder = hiAppEvent.addWatcher({ + name: "watcher", +}); +let eventPkg = holder.takeNext(); +``` + +## AppEventPackage + +此接口提供了订阅返回的应用事件包的参数定义。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +| 名称 | 参数类型 | 说明 | +| --------- | -------- | ------------------------------ | +| packageId | number | 事件包ID，从0开始自动递增。 | +| row | number | 事件包的事件数量。 | +| size | number | 事件包的数据大小，单位为byte。 | +| data | string[] | 事件包的事件信息。 | + +## hiAppEvent.clearData + +clearData(): void + +应用事件打点数据清理方法，将应用存储在本地的打点数据进行清除。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +**示例：** + +```js +hiAppEvent.clearData(); +``` + + +## EventType + +事件类型枚举。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +| 名称 | 默认值 | 说明 | +| --------- | ------ | -------------- | +| FAULT | 1 | 故障类型事件。 | +| STATISTIC | 2 | 统计类型事件。 | +| SECURITY | 3 | 安全类型事件。 | +| BEHAVIOR | 4 | 行为类型事件。 | + + +## Event + +此接口提供了所有预定义事件的事件名称常量。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| ------------------------- | -------- | ---- | ---- | -------------------- | +| USER_LOGIN | string | 是 | 否 | 用户登录事件。 | +| USER_LOGOUT | string | 是 | 否 | 用户登出事件。 | +| DISTRIBUTED_SERVICE_START | string | 是 | 否 | 分布式服务启动事件。 | + + +## Param + +此接口提供了所有预定义参数的参数名称常量。 + +**系统能力：** SystemCapability.HiviewDFX.HiAppEvent + +| 名称 | 参数类型 | 可读 | 可写 | 说明 | +| ------------------------------- | -------- | ---- | ---- | ------------------ | +| USER_ID | string | 是 | 否 | 用户自定义ID。 | +| DISTRIBUTED_SERVICE_NAME | string | 是 | 否 | 分布式服务名称。 | +| DISTRIBUTED_SERVICE_INSTANCE_ID | string | 是 | 否 | 分布式服务实例ID。 | \ No newline at end of file diff --git a/zh-cn/application-dev/reference/errorcodes/errcode-hiviewdfx-hiappevent.md b/zh-cn/application-dev/reference/errorcodes/errcode-hiviewdfx-hiappevent.md new file mode 100644 index 0000000000000000000000000000000000000000..c36645d3d21788f24bddabcf644ca4f438bb8cab --- /dev/null +++ b/zh-cn/application-dev/reference/errorcodes/errcode-hiviewdfx-hiappevent.md @@ -0,0 +1,278 @@ +# 应用事件打点错误码 + +## 11100001 打点功能被关闭 + +**错误信息** + +Function is disabled. + +**错误描述** + +在调用write接口进行应用事件打点时，由于打点功能未开启，系统将忽略相关事件。 + +**可能原因** + +应用事件打点功能被关闭了。 + +**处理步骤** +调用配置接口开启打点功能。 + + ```js + hiAppEvent.configure({ + disable: false + }); + ``` + +## 11101001 非法的事件领域名称 +**错误信息** + +Invalid event domain. + +**错误描述** + +在调用write接口进行应用事件打点时，由于传入了非法的事件领域名称，系统将忽略相关事件。 + +**可能原因** + +传入的事件领域名称不符合以下规则： + +- 事件领域名称只包含数字、小写字母、下划线字符。 +- 事件领域名称以小写字母开头，不以下划线结尾。 +- 事件领域名称非空且长度不超过32个字符。 + +**处理步骤** +传入合法的事件领域名称。 + +## 11101002 非法的事件名称 + +**错误信息** + +Invalid event name. + +**错误描述** + +在调用write接口进行应用事件打点时，由于传入了非法的事件名称，系统将忽略相关事件。 + +**可能原因** + +传入的事件名称不符合以下规则： + +- 事件名称只包含数字、小写字母、下划线字符。 +- 事件名称以小写字母开头，不以下划线结尾。 +- 事件名称非空且长度不超过48个字符。 + +**处理步骤** + +传入合法的事件名称。 + +## 11101003 非法的事件参数数量 + +**错误信息** + +Invalid number of event parameters. + +**错误描述** + +在调用write接口进行应用事件打点时，由于传入了非法的事件参数数量，额外的事件参数将被丢弃。 + +**可能原因** + +传入的事件参数数量超过32个。 + +**处理步骤** + +传入合法数量的事件参数。 + +## 11101004 非法的事件参数字符串长度 + +**错误信息** + +Invalid string length of the event parameter. + +**错误描述** + +在调用write接口进行应用事件打点时，由于事件参数值传入了超长的字符串，超出长度的字符将被丢弃。 + +**可能原因** + +传入的事件参数值中的字符串长度超过8*1024个字符。 + +**处理步骤** + +传入合法字符串长度的事件参数值。 + +## 11101005 非法的事件参数名称 + +**错误信息** + +Invalid event parameter name. + +**错误描述** + +在调用write接口进行应用事件打点时，由于传入了非法的事件参数名称，系统将忽略相关事件参数。 + +**可能原因** + +传入的事件名称不符合以下规则： + +- 事件名称只包含数字、小写字母、下划线字符。 +- 事件名称以小写字母开头，不以下划线结尾。 +- 事件名称非空且长度不超过16个字符。 + +**处理步骤** + +传入合法的事件参数名称。 + +## 11101006 非法的事件参数数组长度 + +**错误信息** + +Invalid array length of the event parameter. + +**错误描述** + +在调用write接口进行应用事件打点时，由于事件参数值传入了超出长度的数组，额外的数组元素将被丢弃。 + +**可能原因** + +传入的事件参数值中的数组长度超过100。 + +**处理步骤** + +传入合法长度数组的事件参数值。 + +## 11102001 非法的观察者名称 + +**错误信息** + +Invalid watcher name. + +**错误描述** + +在调用addWatcher接口进行事件订阅时，由于传入了非法的观察者名称，系统将忽略此次订阅。 + +**可能原因** + +传入的观察者名称不符合以下规则： + +- 观察者名称只包含数字、小写字母、下划线字符。 +- 观察者名称以小写字母开头，不以下划线结尾。 +- 观察者名称非空且长度不超过32个字符。 + +**处理步骤** + +传入合法的观察者名称。 + +## 11102002 非法的过滤事件领域 + +**错误信息** + +Invalid filtering event domain. + +**错误描述** + +在调用addWatcher接口进行事件订阅时，由于传入了非法的过滤事件领域，系统将忽略此次订阅。 + +**可能原因** + +传入的过滤事件领域名称不符合以下规则： + +- 事件领域名称只包含数字、小写字母、下划线字符。 +- 事件领域名称以小写字母开头，不以下划线结尾。 +- 事件领域名称非空且长度不超过32个字符。 + +**处理步骤** + +传入合法的过滤事件领域名称。 + +## 11102003 非法的条数值 + +**错误信息** + +Invalid row value. + +**错误描述** + +在调用addWatcher接口进行事件订阅时，由于回调触发条件传入了非法的事件个数值，系统将忽略此次订阅。 + +**可能原因** + +传入的回调触发条件中的条数值为负数。 + +**处理步骤** + +传入自然数值的条数值。 + +## 11102004 非法的大小值 + +**错误信息** + +Invalid size value. + +**错误描述** + +在调用addWatcher接口进行事件订阅时，由于回调触发条件传入了非法的事件大小值，系统将忽略此次订阅。 + +**可能原因** + +传入的回调触发条件中的大小值为负数。 + +**处理步骤** + +传入自然数值的大小值。 + +## 11102005 非法的超时值 + +**错误信息** + +Invalid timeout value. + +**错误描述** + +在调用addWatcher接口进行事件订阅时，由于回调触发条件传入了非法的超时值，系统将忽略此次订阅。 + +**可能原因** + +传入的回调触发条件中的超时值为负数。 + +**处理步骤** + +传入自然数值的超时值。 + +## 11103001 非法的最大存储配额值 + +**错误信息** + +Invalid max storage quota value. + +**错误描述** + +在调用configure接口进行打点配置时，由于传入了非法的最大存储配额值，系统将忽略此次配置。 + +**可能原因** + +传入的最大存储配额值字符串不符合以下规则： + +- 最大存储配额值以数字开头，以大小单位（单位字符支持[b|k|kb|m|mb|g|gb|t|tb]，不区分大小写）结尾，且不包含其他字符。 + +**处理步骤** + +传入合法的最大存储配额值字符串。 + +## 11104001 非法的事件包大小值 + +**错误信息** + +Invalid size value. + +**错误描述** + +在调用setSize接口对每次取出的事件包大小阈值进行设置时，由于传入了非法的事件包大小值，系统将忽略此次设置。 + +**可能原因** + +传入的事件包大小值为负数。 + +**处理步骤** + +传入自然数值的事件包大小。 \ No newline at end of file