1# Subscribing to Application Events (ArkTS)
2
3HiAppEvent provides APIs for subscribing to application events.
4
5## Available APIs
6
7For details about how to use the APIs (such as parameter usage constraints and value ranges), see [Application Event Logging](../reference/apis-performance-analysis-kit/js-apis-hiviewdfx-hiappevent.md).
8
9**Event Logging APIs**
10
11| API                                             | Description                                        |
12| --------------------------------------------------- | -------------------------------------------- |
13| write(info: AppEventInfo, callback: AsyncCallback\<void>): void | Writes events to the event file through **AppEventInfo** objects. This API uses an asynchronous callback to return the result. |
14| write(info: AppEventInfo): Promise\<void>               | Writes events to the event file through **AppEventInfo** objects. This API uses a promise to return the result. |
15
16**Subscription APIs**
17
18| API                                             | Description                                        |
19| --------------------------------------------------- | -------------------------------------------- |
20| addWatcher(watcher: Watcher): AppEventPackageHolder | Adds a watcher to listen for application events. |
21| removeWatcher(watcher: Watcher): void               | Removes a watcher to unsubscribe from application events. |
22
23## How to Develop
24
25The following describes how to log and subscribe to button onclick events.
26
271. Create an ArkTS application project. In the **entry/src/main/ets/entryability/EntryAbility.ets** file, import the dependent modules.
28
29   ```ts
30   import { hiAppEvent, hilog } from '@kit.PerformanceAnalysisKit';
31   ```
32
332. In the **entry/src/main/ets/entryability/EntryAbility.ets** file, add a watcher in **onCreate()** to subscribe to button onclick events. The sample code is as follows:
34
35   ```ts
36    hiAppEvent.addWatcher({
37      // Set the watcher name. The system identifies different watchers based on their names.
38      name: "watcher1",
39      // Add the application events to watch, for example, button onclick events.
40      appEventFilters: [{ domain: "button" }],
41      // Set the subscription callback trigger condition. For example, trigger a callback when one event is logged.
42      triggerCondition: { row: 1 },
43      // Implement the subscription callback function to apply custom processing to the obtained event logging data.
44      onTrigger: (curRow: number, curSize: number, holder: hiAppEvent.AppEventPackageHolder) => {
45        // If the holder object is null, return after the error is recorded.
46        if (holder == null) {
47          hilog.error(0x0000, 'testTag', "HiAppEvent holder is null");
48          return;
49        }
50        hilog.info(0x0000, 'testTag', `HiAppEvent onTrigger: curRow=%{public}d, curSize=%{public}d`, curRow, curSize);
51        let eventPkg: hiAppEvent.AppEventPackage | null = null;
52        // Fetch the subscription event package based on the specified threshold (512 KB by default) until all subscription event data is fetched.
53        // If all subscription event data is fetched, return a null event package to end this subscription callback.
54        while ((eventPkg = holder.takeNext()) != null) {
55          // Apply custom processing to the event logging data obtained, for example, print the event logging data in the log.
56          hilog.info(0x0000, 'testTag', `HiAppEvent eventPkg.packageId=%{public}d`, eventPkg.packageId);
57          hilog.info(0x0000, 'testTag', `HiAppEvent eventPkg.row=%{public}d`, eventPkg.row);
58          hilog.info(0x0000, 'testTag', `HiAppEvent eventPkg.size=%{public}d`, eventPkg.size);
59          for (const eventInfo of eventPkg.data) {
60            hilog.info(0x0000, 'testTag', `HiAppEvent eventPkg.info=%{public}s`, eventInfo);
61          }
62        }
63      }
64    });
65
663. In the **entry/src/main/ets/pages/Index.ets** file, import the dependent modules.
67
68   ```ts
69   import { BusinessError } from '@kit.BasicServicesKit';
70   import { hiAppEvent, hilog } from '@kit.PerformanceAnalysisKit';
71   ```
72
734. In the **entry/src/main/ets/pages/index.ets** file, add the **writeTest** button with **onClick()** to enable an event to be logged when the button is clicked. The sample code is as follows:
74
75   ```ts
76     Button("writeTest").onClick(()=>{
77       // In onClick(), use hiAppEvent.write() to log an event when the button is clicked.
78       let eventParams: Record<string, number> = { 'click_time': 100 };
79       let eventInfo: hiAppEvent.AppEventInfo = {
80         // Define the event domain.
81         domain: "button",
82         // Define the event name.
83         name: "click",
84         // Define the event type.
85         eventType: hiAppEvent.EventType.BEHAVIOR,
86         // Define the event parameters.
87         params: eventParams,
88       };
89       hiAppEvent.write(eventInfo).then(() => {
90         hilog.info(0x0000, 'testTag', `HiAppEvent success to write event`)
91       }).catch((err: BusinessError) => {
92         hilog.error(0x0000, 'testTag', `HiAppEvent err.code: ${err.code}, err.message: ${err.message}`)
93       });
94     })
95   ```
96
975. In DevEco Studio, click the **Run** button to run the project. Then, click the **writeTest** button to trigger logging of a button onclick event.
98
996. In the **Log** window, you can view the event logging information and the processing of the logging data after the callback is invoked.
100
101   ```text
102   HiAppEvent success to write event
103   HiAppEvent eventPkg.packageId=0
104   HiAppEvent eventPkg.row=1
105   HiAppEvent eventPkg.size=124
106   HiAppEvent eventPkg.info={"domain_":"button","name_":"click","type_":4,"time_":1670268234523,"tz_":"+0800","pid_":3295,"tid_":3309,"click_time":100}
107   ```
108