1# HiAppEvent Data Processor Library
2
3
4## Overview
5
6HiAppEvent implements the logging function for OpenHarmony applications. The data processor library provides the event processing capability for HiAppEvent. It needs to be provided by the data processor during device development.
7
8The following figure shows the service flowchart of the HiAppEvent data processor library.
9
10  **Figure 1** Service flowchart of the HiAppEvent data processor library
11
12  ![Service flowchart](../subsystems/figures/hiappevent_extend_so_stream.png)
13
14## Usage Scenarios
15
16After a data processor is added by using HiAppEvent APIs, an application event, once being submitted, will be distributed to the event handler. The event handler then performs proper processing, for example, reporting the event.
17
18## Function Description
19
20The HiAppEvent data processor library provides the event processing capability for the HiAppEvent event handler. Its functions are as follows:
21
22- Initial registration: provides the service logic for initializing the `.so` file when the data processor library is loaded and registers the data processor with HiAppEvent. The following figure shows the initial registration flowchart.
23
24  **Figure 2** Initial registration flowchart
25
26  ![Initial registration](../subsystems/figures/hiappevent_extend_so_inited.png)
27
28
29- Event reporting: provides APIs related to logging and reporting of application events. The following figure shows the event reporting flowchart.
30
31  **Figure 3** Event reporting flowchart
32
33  ![Event reporting](../subsystems/figures/hiappevent_extend_so_report.png)
34
35- User ID verification: provides APIs for verifying user IDs. See Figure 4 for the user ID verification flowchart.
36
37- User property verification: provides APIs for verifying user properties. See Figure 4 for the user property verification flowchart.
38
39- Event verification: provides APIs for verifying application events. See Figure 4 for the event verification flowchart.
40
41  **Figure 4** Data verification flowchart
42
43  ![Data verification](../subsystems/figures/hiappevent_extend_so_verify.png)
44
45## How to Develop
46
47#### Available APIs
48
49**Table 1** API called by the data processor library
50
51| API                                                                                        | Description                        |
52| ---------------------------------------------------------------------------------------------- | ---------------------------- |
53| int RegisterProcessor(const std::string& name, std::shared_ptr\<AppEventProcessor\> processor) | Registers a data processor with HiAppEvent.|
54
55**Table 1** APIs implemented by the data processor library
56
57| API                                                                                                                                                                | Description              |
58| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
59| int OnReport(int64_t processorSeq, const std::vector\<UserId\>& userIds, const std::vector\<UserProperty\>& userProperties, const std::vector\<AppEventInfo\>& events) | Reports events.        |
60| int ValidateUserId(const UserId& userId)                                                                                                                               | Verifies user IDs.      |
61| int ValidateUserProperty(const UserProperty& userProperty)                                                                                                             | Verifies user properties.|
62| int ValidateEvent(const AppEventInfo& event)                                                                                                                           | Verifies events.       |
63
64#### Development Procedure
65
661. Add the `.so` file initialization method to the `processor_init.cpp` file, and perform initial registration.
67
68   ```c++
69      #include "app_event_processor_mgr.h"
70
71      using namespace OHOS::HiviewDFX::HiAppEvent;
72
73      void __attribute__((constructor)) x_init(void)
74      {
75        ...
76        int result = AppEventProcessorMgr::RegisterProcessor("processor_example", new ProcessorExample());
77        printf("ProcessorExample OnReport\n");
78      }
79   ```
80
812. Define the `ProcessorExample` class, which is inherited from the base class `AppEventProcessor`, in the `processor_example.h` file.
82
83   ```c++
84      #include <vector>
85      #include "app_event_processor.h"
86
87      using namespace OHOS::HiviewDFX::HiAppEvent;
88
89      class ProcessorExample : public AppEventProcessor {
90      public:
91          int OnReport(int64_t processorSeq, const std::vector<UserId>& userIds, const std::vector<UserProperty>& userProperties, const std::vector<AppEventInfo>& events) override;
92          int ValidateUserId(const UserId& userId) override;
93          int ValidateUserProperty(const UserProperty& userProperty) override;
94          int ValidateEvent(const AppEventInfo& event) override;
95      ...
96      };
97   ```
98
993. Implement the `ProcessorExample` class in the `processor_example.cpp` file, and override related functions based on the service logic.
100
101   ```c++
102    #include "processor_example.h"
103
104    int ProcessorExample::OnReport(int64_t processorSeq, const std::vector<UserId>& userIds, const std::vector<UserProperty>& userProperties, const std::vector<AppEventInfo>& events)
105    {
106        ... // Enable specific event processing in the OnReport function.
107        printf("ProcessorExample OnReport\n");
108        return 0;
109    }
110
111    int ProcessorExample::ValidateUserId(const UserId& userId)
112    {
113        ... // Enable user ID verification in the ValidateUserId function.
114        printf("ProcessorExample ValidateUserId\n");
115        return 0;
116    }
117
118    int ProcessorExample::ValidateUserProperty(const UserProperty& userProperty)
119    {
120        ... // Enable user property verification in the ValidateUserProperty function.
121        printf("ProcessorExample ValidateUserProperty\n");
122        return 0;
123    }
124
125    int ProcessorExample::ValidateEvent(const AppEventInfo& event)
126    {
127        ... // Enable event verification in the ValidateEvent function.
128        printf("ProcessorExample ValidateEvent\n");
129        return 0;
130    }
131   ```
132
1334. Configure the `ProcessorExample` class in the `build.gn` class file, and compile it with the data processor library.
134
135   ```conf
136    sources = [
137      ... // Include the required source file.
138      "./src/processor_init.cpp",
139      "./src/processor_example.cpp",
140    ]
141    external_deps = [
142      ... // Include the required external dependency library.
143      "hiappevent:hiappevent_innerapi",
144    ]
145   ```
146
147## References
148
149For more information about the source code and usage of HiAppEvent, access the [HiAppEvent code repository](https://gitee.com/openharmony/hiviewdfx_hiappevent).
150