@ohos.hiviewdfx.hiAppEvent (应用事件打点)

本模块提供了应用事件打点能力，包括应用事件落盘、应用事件订阅、应用事件清理、打点功能配置等功能。

说明：

本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

import hiAppEvent from '@ohos.hiviewdfx.hiAppEvent';

hiAppEvent.addProcessor¹¹⁺

addProcessor(processor: Processor): number

开发者可添加数据处理者，该数据处理者用于提供事件上云功能，数据处理者的实现可预置在设备中，开发者可根据数据处理者的约束设置属性。

Processor的配置信息需要由数据处理者提供，目前设备内暂未预置可供交互的数据处理者，因此当前事件上云功能不可用。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

参数：

参数名	类型	必填	说明
processor	Processor	是	上报事件的数据处理者。

返回值：

类型	说明
number	所添加上报事件数据处理者的ID。添加失败返回-1，添加成功返回大于0的值。

错误码：

错误码ID	错误信息
401	Parameter error.

示例：

import hilog from '@ohos.hilog';

try {
    let processor: hiAppEvent.Processor = {
      name: 'analytics_demo'
    };
    let id: number = hiAppEvent.addProcessor(processor);
    hilog.info(0x0000, 'hiAppEvent', `addProcessor event was successful, id=${id}`);
} catch (error) {
    hilog.error(0x0000, 'hiAppEvent', `failed to addProcessor event, code=${error.code}`);
}

Processor¹¹⁺

可以上报事件的数据处理者对象。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

名称	类型	必填	说明
name	string	是	数据处理者的名称。名称只能包含大小写字母、数字、下划线和 $，不能以数字开头，长度非空且不超过256个字符。
debugMode	boolean	否	是否开启debug模式，默认值为false。配置值为true表示开启debug模式，false表示不开启debug模式。
routeInfo	string	否	服务器位置信息，默认为空字符串。传入字符串长度不能超过8KB，超过时会被置为默认值。
appId	string	否	应用id，默认为空字符串。传入字符串长度不能超过8KB，超过时会被置为默认值。
onStartReport	boolean	否	数据处理者在启动时是否上报事件，默认值为false。配置值为true表示上报事件，false表示不上报事件。
onBackgroundReport	boolean	否	当应用程序进入后台时是否上报事件，默认值为false。配置值为true表示上报事件，false表示不上报事件。
periodReport	number	否	事件定时上报时间周期，单位为秒。传入数值必须大于或等于0，小于0时会被置为默认值0，不进行定时上报。
batchReport	number	否	事件上报阈值，当事件条数达到阈值时上报事件。传入数值必须大于0且小于1000，不在数值范围内会被置为默认值0，不进行上报。
userIds	string[]	否	数据处理者可以上报的用户ID的name数组。name对应setUserId接口的name参数。
userProperties	string[]	否	数据处理者可以上报的用户属性的name数组。name对应setUserProperty接口的name参数。
eventConfigs	AppEventReportConfig[]	否	数据处理者可以上报的事件数组。

AppEventReportConfig¹¹⁺

数据处理者可以上报事件的描述配置。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

名称	类型	必填	说明
domain	string	否	事件领域。事件领域名称支持数字、小写字母、下划线字符，需要以小写字母开头且不能以下划线结尾，长度非空且不超过16个字符。
name	string	否	事件名称。首字符必须为字母字符或$字符，中间字符必须为数字字符、字母字符或下划线字符，结尾字符必须为数字字符或字母字符，长度非空且不超过48个字符。
isRealTime	boolean	否	是否实时上报事件。配置值为true表示实时上报事件，false表示不实时上报事件。

hiAppEvent.removeProcessor¹¹⁺

removeProcessor(id: number): void

删除上报事件的数据处理者。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

参数：

参数名	类型	必填	说明
id	number	是	上报事件数据处理者ID。值大于0。

错误码：

错误码ID	错误信息
401	Parameter error.

示例：

import hilog from '@ohos.hilog';

try {
    let processor: hiAppEvent.Processor = {
      name: 'analytics_demo'
    };
    let id: number = hiAppEvent.addProcessor(processor);
    hiAppEvent.removeProcessor(id);
} catch (error) {
    hilog.error(0x0000, 'hiAppEvent', `failed to removeProcessor event, code=${error.code}`);
}

hiAppEvent.write

write(info: AppEventInfo, callback: AsyncCallback<void>): void

应用事件打点方法，将事件写入到当天的事件文件中，可接收AppEventInfo类型的事件对象，使用callback方式作为异步回调。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

参数：

参数名	类型	必填	说明
info	AppEventInfo	是	应用事件对象。
callback	AsyncCallback<void>	是	打点回调函数。

错误码：

以下错误码的详细介绍请参见应用事件打点错误码。

错误码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.

示例：

import { BusinessError } from '@ohos.base';
import hilog from '@ohos.hilog';

let eventParams: Record<string, number | string> = {
  "int_data": 100,
  "str_data": "strValue",
};
hiAppEvent.write({
  domain: "test_domain",
  name: "test_event",
  eventType: hiAppEvent.EventType.FAULT,
  params: eventParams,
}, (err: BusinessError) => {
  if (err) {
    hilog.error(0x0000, 'hiAppEvent', `code: ${err.code}, message: ${err.message}`);
    return;
  }
  hilog.info(0x0000, 'hiAppEvent', `success to write event`);
});

hiAppEvent.write

write(info: AppEventInfo): Promise<void>

应用事件打点方法，将事件写入到当天的事件文件中，可接收AppEventInfo类型的事件对象，使用Promise方式作为异步回调。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

参数：

参数名	类型	必填	说明
info	AppEventInfo	是	应用事件对象。

返回值：

类型	说明
Promise<void>	Promise对象。

错误码：

以下错误码的详细介绍请参见应用事件打点错误码。

错误码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.

示例：

import { BusinessError } from '@ohos.base';
import hilog from '@ohos.hilog';

let eventParams: Record<string, number | string> = {
  "int_data": 100,
  "str_data": "strValue",
};
hiAppEvent.write({
  domain: "test_domain",
  name: "test_event",
  eventType: hiAppEvent.EventType.FAULT,
  params: eventParams,
}).then(() => {
  hilog.info(0x0000, 'hiAppEvent', `success to write event`);
}).catch((err: BusinessError) => {
  hilog.error(0x0000, 'hiAppEvent', `code: ${err.code}, message: ${err.message}`);
});

AppEventInfo

提供了应用事件信息的参数选项。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

名称	类型	必填	说明
domain	string	是	事件领域。事件领域名称支持数字、小写字母、下划线字符，需要以小写字母开头且不能以下划线结尾，长度非空且不超过16个字符。
name	string	是	事件名称。首字符必须为字母字符或$字符，中间字符必须为数字字符、字母字符或下划线字符，结尾字符必须为数字字符或字母字符，长度非空且不超过48个字符。
eventType	EventType	是	事件类型。
params	object	是	事件参数对象，每个事件参数包括参数名和参数值，其规格定义如下： - 参数名为string类型，首字符必须为字母字符或$字符，中间字符必须为数字字符、字母字符或下划线字符，结尾字符必须为数字字符或字母字符，长度非空且不超过16个字符。 - 参数值支持string、number、boolean、数组类型，string类型参数长度需在8*1024个字符以内，超出会做丢弃处理；number类型参数取值需在Number.MIN_SAFE_INTEGER~Number.MAX_SAFE_INTEGER范围内，超出可能会产生不确定值；数组类型参数中的元素类型只能全为string、number、boolean中的一种，且元素个数需在100以内，超出会做丢弃处理。 - 参数个数需在32个以内，超出的参数会做丢弃处理。

hiAppEvent.configure

configure(config: ConfigOption): void

应用事件打点配置方法，可用于配置打点开关、目录存储配额大小等功能。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

参数：

参数名	类型	必填	说明
config	ConfigOption	是	应用事件打点配置项对象。

错误码：

以下错误码的详细介绍请参见应用事件打点错误码。

错误码ID	错误信息
11103001	Invalid max storage quota value.

示例：

// 配置打点开关为关闭状态
let config1: hiAppEvent.ConfigOption = {
  disable: true,
};
hiAppEvent.configure(config1);

// 配置文件目录存储配额为100M
let config2: hiAppEvent.ConfigOption = {
  maxStorage: '100M',
};
hiAppEvent.configure(config2);

ConfigOption

提供了对应用事件打点功能的配置选项。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

名称	类型	必填	说明
disable	boolean	否	打点功能开关，默认值为false。true：关闭打点功能，false：不关闭打点功能。
maxStorage	string	否	打点数据存放目录的配额大小，默认值为“10M”。在目录大小超出配额后，下次打点会触发对目录的清理操作：按从旧到新的顺序逐个删除打点数据文件，直到目录大小不超出配额时结束。配额值字符串规格如下： - 配额值字符串只由数字字符和大小单位字符（单位字符支持[b\|k\|kb\|m\|mb\|g\|gb\|t\|tb]，不区分大小写）构成。 - 配额值字符串必须以数字开头，后面可以选择不传单位字符（默认使用byte作为单位），或者以单位字符结尾。

hiAppEvent.setUserId¹¹⁺

setUserId(name: string, value: string): void

设置用户ID。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

参数：

参数名	类型	必填	说明
name	string	是	用户ID的key。只能包含大小写字母、数字、下划线和 $，不能以数字开头，长度非空且不超过256个字符。
value	string	是	用户ID的值。长度不超过256，当值为null或空字符串时，则清除用户ID。

错误码：

错误码ID	错误信息
401	Parameter error.

示例：

import hilog from '@ohos.hilog';

try {
  hiAppEvent.setUserId('key', 'value');
} catch (error) {
  hilog.error(0x0000, 'hiAppEvent', `failed to setUserId event, code=${error.code}`);
}

hiAppEvent.getUserId¹¹⁺

getUserId(name: string): string

获取之前通过setUserId接口设置的value值。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

参数：

参数名	类型	必填	说明
name	string	是	用户ID的key。只能包含大小写字母、数字、下划线和 $，不能以数字开头，长度不超过256。

返回值：

类型	说明
string	用户ID的值。没有查到返回空字符串。

错误码：

错误码ID	错误信息
401	Parameter error.

示例：

import hilog from '@ohos.hilog';

hiAppEvent.setUserId('key', 'value');
try {
  let value: string = hiAppEvent.getUserId('key');
  hilog.info(0x0000, 'hiAppEvent', `getUserId event was successful, userId=${value}`);
} catch (error) {
  hilog.error(0x0000, 'hiAppEvent', `failed to getUserId event, code=${error.code}`);
}

hiAppEvent.setUserProperty¹¹⁺

setUserProperty(name: string, value: string): void

设置用户属性。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

参数：

参数名	类型	必填	说明
name	string	是	用户属性的key。只能包含大小写字母、数字、下划线和 $，不能以数字开头，长度非空且不超过256个字符。
value	string	是	用户属性的值。长度不超过1024，当值为null、undefine或空，则清除用户属性。

错误码：

错误码ID	错误信息
401	Parameter error.

示例：

import hilog from '@ohos.hilog';

try {
  hiAppEvent.setUserProperty('key', 'value');
} catch (error) {
  hilog.error(0x0000, 'hiAppEvent', `failed to setUserProperty event, code=${error.code}`);
}

hiAppEvent.getUserProperty¹¹⁺

getUserProperty(name: string): string

获取之前通过setUserProperty接口设置的value值。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

参数：

参数名	类型	必填	说明
name	string	是	用户属性的key。只能包含大小写字母、数字、下划线和 $，不能以数字开头，长度不超过256。

返回值：

类型	说明
string	用户属性的值。没有查到返回空字符串。

错误码：

错误码ID	错误信息
401	Parameter error.

示例：

import hilog from '@ohos.hilog';

hiAppEvent.setUserProperty('key', 'value');
try {
  let value: string = hiAppEvent.getUserProperty('key');
  hilog.info(0x0000, 'hiAppEvent', `getUserProperty event was successful, userProperty=${value}`);
} catch (error) {
  hilog.error(0x0000, 'hiAppEvent', `failed to getUserProperty event, code=${error.code}`);
}

hiAppEvent.addWatcher

addWatcher(watcher: Watcher): AppEventPackageHolder

添加应用事件观察者方法，可用于订阅应用事件。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

参数：

参数名	类型	必填	说明
watcher	Watcher	是	应用事件观察者。

返回值：

类型	说明
AppEventPackageHolder	订阅数据持有者，订阅失败时返回null。

错误码：

以下错误码的详细介绍请参见应用事件打点错误码。

错误码ID	错误信息
11102001	Invalid watcher name.
11102002	Invalid filtering event domain.
11102003	Invalid row value.
11102004	Invalid size value.
11102005	Invalid timeout value.

示例：

import hilog from '@ohos.hilog';

// 1. 如果观察者传入了回调的相关参数，则可以选择在自动触发的回调函数中对订阅事件进行处理
hiAppEvent.addWatcher({
  name: "watcher1",
  appEventFilters: [
    {
      domain: "test_domain",
      eventTypes: [hiAppEvent.EventType.FAULT, hiAppEvent.EventType.BEHAVIOR]
    }
  ],
  triggerCondition: {
    row: 10,
    size: 1000,
    timeOut: 1
  },
  onTrigger: (curRow: number, curSize: number, holder: hiAppEvent.AppEventPackageHolder) => {
    if (holder == null) {
      hilog.error(0x0000, 'hiAppEvent', "holder is null");
      return;
    }
    hilog.info(0x0000, 'hiAppEvent', `curRow=${curRow}, curSize=${curSize}`);
    let eventPkg: hiAppEvent.AppEventPackage | null = null;
    while ((eventPkg = holder.takeNext()) != null) {
      hilog.info(0x0000, 'hiAppEvent', `eventPkg.packageId=${eventPkg.packageId}`);
      hilog.info(0x0000, 'hiAppEvent', `eventPkg.row=${eventPkg.row}`);
      hilog.info(0x0000, 'hiAppEvent', `eventPkg.size=${eventPkg.size}`);
      for (const eventInfo of eventPkg.data) {
        hilog.info(0x0000, 'hiAppEvent', `eventPkg.data=${eventInfo}`);
      }
    }
  }
});

// 2. 如果观察者未传入回调的相关参数，则可以选择使用返回的holder对象手动去处理订阅事件
let holder = hiAppEvent.addWatcher({
  name: "watcher2",
});
if (holder != null) {
  let eventPkg: hiAppEvent.AppEventPackage | null = null;
  while ((eventPkg = holder.takeNext()) != null) {
    hilog.info(0x0000, 'hiAppEvent', `eventPkg.packageId=${eventPkg.packageId}`);
    hilog.info(0x0000, 'hiAppEvent', `eventPkg.row=${eventPkg.row}`);
    hilog.info(0x0000, 'hiAppEvent', `eventPkg.size=${eventPkg.size}`);
    for (const eventInfo of eventPkg.data) {
      hilog.info(0x0000, 'hiAppEvent', `eventPkg.data=${eventInfo}`);
    }
  }
}

// 3. 观察者可以在实时回调函数onReceive中处理订阅事件
hiAppEvent.addWatcher({
  name: "watcher3",
  appEventFilters: [
    {
      domain: "test_domain",
      eventTypes: [hiAppEvent.EventType.FAULT, hiAppEvent.EventType.BEHAVIOR]
    }
  ],
  onReceive: (domain: string, appEventGroups: Array<hiAppEvent.AppEventGroup>) => {
    hilog.info(0x0000, 'hiAppEvent', `domain=${domain}`);
    for (const eventGroup of appEventGroups) {
      hilog.info(0x0000, 'hiAppEvent', `eventName=${eventGroup.name}`);
      for (const eventInfo of eventGroup.appEventInfos) {
        hilog.info(0x0000, 'hiAppEvent', `event=${JSON.stringify(eventInfo)}`, );
      }
    }
  }
});

hiAppEvent.removeWatcher

removeWatcher(watcher: Watcher): void

移除应用事件观察者方法，可用于取消订阅应用事件。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

参数：

参数名	类型	必填	说明
watcher	Watcher	是	应用事件观察者。

错误码：

以下错误码的详细介绍请参见应用事件打点错误码。

错误码ID	错误信息
11102001	Invalid watcher name.

示例：

// 1. 定义一个应用事件观察者
let watcher: hiAppEvent.Watcher = {
  name: "watcher1",
}

// 2. 添加一个应用事件观察者来订阅事件
hiAppEvent.addWatcher(watcher);

// 3. 移除该应用事件观察者以取消订阅事件
hiAppEvent.removeWatcher(watcher);

Watcher

提供了应用事件观察者的参数选项。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

名称	类型	必填	说明
name	string	是	观察者名称，用于唯一标识观察者。
triggerCondition	TriggerCondition	否	订阅回调触发条件，需要与回调函数onTrigger一同传入才会生效。
appEventFilters	AppEventFilter[]	否	订阅过滤条件，在需要对订阅事件进行过滤时传入。
onTrigger	(curRow: number, curSize: number, holder: AppEventPackageHolder) => void	否	订阅回调函数，需要与回调触发条件triggerCondition一同传入才会生效，函数入参说明如下： curRow：在本次回调触发时的订阅事件总数量； curSize：在本次回调触发时的订阅事件总大小，单位为byte； holder：订阅数据持有者对象，可以通过其对订阅事件进行处理。
onReceive¹¹⁺	(domain: string, appEventGroups: Array<AppEventGroup>) => void	否	订阅实时回调函数，与回调函数onTrigger同时存在时，只触发此回调，函数入参说明如下： domain：回调事件的领域名称； appEventGroups：回调事件集合。

TriggerCondition

提供了回调触发条件的参数选项，只要满足任一条件就会触发订阅回调。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

名称	类型	必填	说明
row	number	否	满足触发回调的事件总数量。
size	number	否	满足触发回调的事件总大小，单位为byte。
timeOut	number	否	满足触发回调的超时时长，单位为30s。

AppEventFilter

提供了过滤应用事件的参数选项。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

名称	类型	必填	说明
domain	string	是	需要订阅的事件领域。
eventTypes	EventType[]	否	需要订阅的事件类型集合。
names¹¹⁺	string[]	否	需要订阅的事件名称集合。

AppEventPackageHolder

订阅数据持有者类，用于对订阅事件进行处理。

constructor

constructor(watcherName: string)

类构造函数，创建订阅数据持有者实例，通过观察者名称关联到应用内已添加的观察者对象。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

参数：

参数名	类型	必填	说明
watcherName	string	是	观察者名称。

示例：

let holder1: hiAppEvent.AppEventPackageHolder = new hiAppEvent.AppEventPackageHolder("watcher1");

setSize

setSize(size: number): void

设置每次取出的应用事件包的数据大小阈值。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

参数：

参数名	类型	必填	说明
size	number	是	数据大小阈值，单位为byte，默认值为512*1024。

错误码：

以下错误码的详细介绍请参见应用事件打点错误码。

错误码ID	错误信息
11104001	Invalid size value.

示例：

let holder2: hiAppEvent.AppEventPackageHolder = new hiAppEvent.AppEventPackageHolder("watcher2");
holder2.setSize(1000);

takeNext

takeNext(): AppEventPackage

根据设置的数据大小阈值来取出订阅事件数据，当订阅事件数据全部被取出时返回null作为标识。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

返回值：

类型	说明
AppEventPackage	取出的事件包对象，订阅事件数据被全部取出后会返回null。

示例：

let holder3: hiAppEvent.AppEventPackageHolder = new hiAppEvent.AppEventPackageHolder("watcher3");
let eventPkg = holder3.takeNext();

AppEventPackage

提供了订阅返回的应用事件包的参数定义。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

名称	类型	必填	说明
packageId	number	是	事件包ID，从0开始自动递增。
row	number	是	事件包的事件数量。
size	number	是	事件包的事件大小，单位为byte。
data	string[]	是	事件包的事件信息。

AppEventGroup¹¹⁺

提供了订阅返回的事件组的参数定义。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

名称	类型	必填	说明
name	string	是	事件名称。
appEventInfos	Array<AppEventInfo>	是	事件对象集合。

hiAppEvent.clearData

clearData(): void

应用事件打点数据清理方法，将应用存储在本地的打点数据进行清除。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

示例：

hiAppEvent.clearData();

EventType

事件类型枚举。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

名称	值	说明
FAULT	1	故障类型事件。
STATISTIC	2	统计类型事件。
SECURITY	3	安全类型事件。
BEHAVIOR	4	行为类型事件。

domain¹¹⁺

提供了所有预定义事件的领域名称常量。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

名称	类型	说明
OS	string	系统领域。

event

提供了所有预定义事件的事件名称常量。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

名称	类型	说明
USER_LOGIN	string	用户登录事件。
USER_LOGOUT	string	用户登出事件。
DISTRIBUTED_SERVICE_START	string	分布式服务启动事件。
APP_CRASH¹¹⁺	string	应用崩溃事件。
APP_FREEZE¹¹⁺	string	应用卡死事件。

param

提供了所有预定义参数的参数名称常量。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

名称	类型	说明
USER_ID	string	用户自定义ID。
DISTRIBUTED_SERVICE_NAME	string	分布式服务名称。
DISTRIBUTED_SERVICE_INSTANCE_ID	string	分布式服务实例ID。

@ohos.hiviewdfx.hiAppEvent (应用事件打点)

导入模块

hiAppEvent.addProcessor11+

Processor11+

AppEventReportConfig11+

hiAppEvent.removeProcessor11+

hiAppEvent.write

hiAppEvent.write

AppEventInfo

hiAppEvent.configure

ConfigOption

hiAppEvent.setUserId11+

hiAppEvent.getUserId11+

hiAppEvent.setUserProperty11+

hiAppEvent.getUserProperty11+

hiAppEvent.addWatcher

hiAppEvent.removeWatcher

Watcher

TriggerCondition

AppEventFilter

AppEventPackageHolder

constructor

setSize

takeNext

AppEventPackage

AppEventGroup11+

hiAppEvent.clearData

EventType

domain11+

event

param

hiAppEvent.addProcessor¹¹⁺

Processor¹¹⁺

AppEventReportConfig¹¹⁺

hiAppEvent.removeProcessor¹¹⁺

hiAppEvent.setUserId¹¹⁺

hiAppEvent.getUserId¹¹⁺

hiAppEvent.setUserProperty¹¹⁺

hiAppEvent.getUserProperty¹¹⁺

AppEventGroup¹¹⁺

domain¹¹⁺