1# HiAppEvent数据处理者lib库概述
2
3
4## 简介
5
6HiAppEvent是面向OpenHarmony应用开发者提供的打点功能，数据处理者lib库为HiAppEvent提供事件处理能力，lib库需要数据处理者开发方在设备开发时提供。
7
8HiAppEvent数据处理者lib库处理流程图如下图所示：
9
10  **图1** HiAppEvent数据处理者lib库处理流程图
11
12  ![处理流程图](../subsystems/figures/hiappevent_extend_so_stream.png)
13
14## 使用场景
15
16开发者使用HiAppEvent接口添加处理者并提交应用事件时，事件将会分发给事件处理者，由处理者对事件进行相应处理，例如上报。
17
18## 功能说明
19
20HiAppEvent数据处理者lib库为HiAppEvent事件处理者提供事件处理能力，功能介绍如下：
21
22- 初始化注册：提供了数据处理者lib库加载时初始化so的逻辑，以及向HiAppEvent进行处理者注册。初始化注册功能如下图所示：
23
24  **图2** 初始化注册
25
26  ![初始化注册](../subsystems/figures/hiappevent_extend_so_inited.png)
27
28
29- 事件上报：提供了事件打点的相关接口能力，支持对打点事件进行上报。事件上报功能如下图所示：
30
31  **图3** 事件上报
32
33  ![事件上报](../subsystems/figures/hiappevent_extend_so_report.png)
34
35- 校验UserId：提供了校验UserId的相关接口能力，支持对UserId合法性进行校验。校验UserId功能如图4所示。
36
37- 校验UserProperty：提供了校验UserProperty的相关接口能力，支持对UserProperty合法性进行校验。校验UserProperty功能如图4所示。
38
39- 校验Event：提供了校验Event的相关接口能力，支持对Event合法性进行校验。校验Event功能如图4所示。
40
41  **图4** 校验数据
42
43  ![校验数据](../subsystems/figures/hiappevent_extend_so_verify.png)
44
45## 开发指导
46
47#### 接口说明
48
49**表1** 数据处理者lib库需调用的API接口功能介绍
50
51| 接口名                                                                                         | 描述                         |
52| ---------------------------------------------------------------------------------------------- | ---------------------------- |
53| int RegisterProcessor(const std::string& name, std::shared_ptr\<AppEventProcessor\> processor) | 向HiAppEvent注册数据处理者。 |
54
55**表2** 数据处理者lib库需实现的API接口功能介绍
56
57| 接口名                                                                                                                                                                 | 描述               |
58| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
59| int OnReport(int64_t processorSeq, const std::vector\<UserId\>& userIds, const std::vector\<UserProperty\>& userProperties, const std::vector\<AppEventInfo\>& events) | 事件上报。         |
60| int ValidateUserId(const UserId& userId)                                                                                                                               | 校验UserId。       |
61| int ValidateUserProperty(const UserProperty& userProperty)                                                                                                             | 校验UserProperty。 |
62| int ValidateEvent(const AppEventInfo& event)                                                                                                                           | 校验Event。        |
63
64#### 开发步骤
65
661. 在`processor_init.cpp`添加以下so初始化的方法，并进行初始化注册：
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. 在`processor_example.h`定义`ProcessorExample`类，继承于处理者基类AppEventProcessor的处理者实现类：
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. 在`processor_example.cpp`实现`ProcessorExample`类，根据业务覆写实现相应的函数。
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        ... // 在事件上报函数中，可以对事件进行特定业务处理
107        printf("ProcessorExample OnReport\n");
108        return 0;
109    }
110
111    int ProcessorExample::ValidateUserId(const UserId& userId)
112    {
113        ... // 在校验UserId函数中，可以对UserId进行校验
114        printf("ProcessorExample ValidateUserId\n");
115        return 0;
116    }
117
118    int ProcessorExample::ValidateUserProperty(const UserProperty& userProperty)
119    {
120        ... // 在校验UserProperty函数中，可以对UserProperty进行校验
121        printf("ProcessorExample ValidateUserProperty\n");
122        return 0;
123    }
124
125    int ProcessorExample::ValidateEvent(const AppEventInfo& event)
126    {
127        ... // 在校验Event函数中，可以对Event进行校验
128        printf("ProcessorExample ValidateEvent\n");
129        return 0;
130    }
131   ```
132
1334. 将处理者类配置在build.gn文件中，随数据处理者lib库进行编译：
134
135   ```conf
136    sources = [
137      ... // 添加所需使用的源文件
138      "./src/processor_init.cpp",
139      "./src/processor_example.cpp",
140    ]
141    external_deps = [
142      ... // 添加所需使用的外部依赖库
143      "hiappevent:hiappevent_innerapi",
144    ]
145   ```
146
147## 参考
148
149如果您想了解更多关于HiAppEvent特性的源码及使用信息，请参考[HiAppEvent代码仓](https://gitee.com/openharmony/hiviewdfx_hiappevent)。