HiAppEvent介绍
============

#### 简介

HiAppEvent是系统为应用开发者提供的事件订阅和事件打点机制，支持记录应用运行过程中的故障、统计、安全和行为事件，帮助开发者定位问题、分析应用运行情况，统计访问量、用户活跃度、操作习惯以及其他影响用户使用产品的关键因素。

#### 基本概念

**打点**：记录用户操作引起的变化，提供业务数据信息，供开发、产品、运维分析。

*   事件领域：标识事件的领域，建议设置为业务领域名称，以便于区分不同的业务领域。
    
*   事件名称：指定事件的名称，建议设置为具体的业务名称，以便于描述实际的业务意义。
    
*   事件类型：指定事件的类型，支持以下四种类型事件：
    
    *   行为事件：记录用户日常操作行为的事件，例如按钮点击、界面跳转等行为。
    *   故障事件：定位和分析应用故障的事件，例如界面卡顿、网络中断等故障。
    *   统计事件：统计和度量应用关键行为的事件，例如对使用时长、访问数等的统计。
    *   安全事件：记录涉及应用安全行为的事件，例如用户授权等行为。
*   事件参数：指定事件的参数，每个事件可以包含一组参数，建议设置为事件属性或事件发生的上下文信息，以便于描述事件的详细信息。
    

**事件订阅**：通过HiAppEvent的接口[addWatcher](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-hiviewdfx-hiappevent#hiappeventaddwatcher)，开发者可以注册监听自己关注的系统事件或应用事件。目的是当订阅的事件发生后，接收事件的回调信息并进行处理。

#### 实现原理

#### \[h2\]系统事件订阅机制

在当前系统应用沙箱机制下，应用进程仅可以直接访问自己的应用沙箱目录，参考[应用沙箱目录](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/app-sandbox-directory)。而系统事件信息的存放路径不在应用沙箱目录中，因此无法直接获取。

应用调用HiAppEvent的addWatcher接口订阅系统事件并创建共享目录。当应用进程发生故障时，DFX系统捕获相关信息，生成事件和日志，并写入到共享目录。HiAppEvent监听到事件后，将事件回调给应用。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/89/v3/lx5A0HYHRZyU4q2-_lYZ7w/zh-cn_image_0000002625108265.png?HW-CC-KV=V1&HW-CC-Date=20260612T073453Z&HW-CC-Expire=86400&HW-CC-Sign=55C1303F2E1562D7E6CBB0BA0AE937EE71B586EF25E03FE853EED8B7A1C6576B)

#### \[h2\]应用事件订阅机制

应用调用addWatcher接口订阅关注的应用事件后，还需在应用事件发生时，调用[write](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-hiviewdfx-hiappevent#hiappeventwrite-1)接口进行打点，用来记录应用事件。

HiAppEvent通过事件领域和事件名称关联应用事件，并通过addWatcher接口设置的回调方式将事件回调给应用。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/cc/v3/kDpp43aATsaZ24fvRU2Ftg/zh-cn_image_0000002594668748.png?HW-CC-KV=V1&HW-CC-Date=20260612T073453Z&HW-CC-Expire=86400&HW-CC-Sign=FEE8445CD4E129F2AE4E1B101BD1AC1C6947E421ADE706006B8DBD939FB299EB)

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/73/v3/KqlNsjELScCRb-xjxmpt9Q/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073453Z&HW-CC-Expire=86400&HW-CC-Sign=BBFEC45486F295C045B2ADE3BD22DAF4363F5053A2DA347E79B7D9F521AFB175)

若应用已订阅到相关事件，但在触发回调前应用退出，则未回调的事件会在应用下次启动调用addWatcher后进行回调。例如订阅崩溃事件场景，在应用崩溃退出后，下次启动调用addWatcher后执行事件回调。

#### 约束与限制

*   订阅接口addWatcher是同步接口，涉及IO操作。对于性能有要求的模块，建议将接口的调用放到非主线程。
    
*   订阅接口addWatcher传入的名称name是唯一的，相同的name，后一次调用会覆盖前一次的订阅。
    
*   目前应用有普通应用、[应用分身](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/app-clone)、元服务、[输入法应用](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/inputmethod-application-guide)等多种类型，不同类型应用上，系统事件的订阅规格不同。从API version 22开始，HiAppEvent系统事件订阅能力支持输入法应用。具体规格可参见如下表格：
    

| 系统事件名称 | 是否支持应用分身订阅 | 是否支持元服务订阅 | 是否支持输入法应用订阅 |
| :-- | :-- | :-- | :-- |
| 崩溃事件 | 支持 | 支持 | 支持 |
| 应用冻屏事件 | 支持 | 支持 | 支持 |
| 应用冻屏告警事件 | 支持 | 支持 | 支持 |
| 资源泄漏事件 | 支持 | 支持 | 支持 |
| 地址越界事件 | 支持 | 不支持 | 支持 |
| 主线程超时事件 | 支持 | 支持 | 支持 |
| 任务执行超时事件 | 支持 | 不支持 | 支持 |
| 应用终止事件 | 支持 | 支持 | 支持 |
| 启动耗时事件 | 不支持 | 支持 | 不支持 |
| 滑动丢帧事件 | 不支持 | 支持 | 不支持 |
| CPU高负载事件 | 不支持 | 不支持 | 支持 |
| 24h功耗器件分解统计事件 | 不支持 | 不支持 | 支持 |
| 音频卡顿事件 | 不支持 | 不支持 | 不支持 |
| ArkWeb抛滑丢帧事件 | 支持 | 支持 | 支持 |