README.en.md
1# AppDomainNameVerify
2
3## Introduction
4
5AppDomainNameVerify is a part of the bundle management subsystem. It works with the BaseFramework part and ability framework to provide the App Linking$^1$ feature. The main functions of AppDomainNameVerify are as follows:
6
7- During application installation, AppDomainNameVerify communicates with the domain server associated with the application, verifies the mapping between the application and domain name, and saves the mapping.
8- When a link is clicked, AppDomainNameVerify filters the ability of the application associated with the domain name based on the saved mapping.
9
10> **NOTE**
11>
12> App Linking redirects users from different platform to your in-app content. Compared with Deep Link, App Linking is more secure and reliable and provides better user experience.
13
14### Architecture
15
16**Figure 1** Architecture of AppDomainNameVerify
17
18
19
20### Process
21
22#### Interaction with BundleManagerService
23
24* During application installation, BundleManagerService calls the domain name verification API of AppDomainNameVerify to obtain the asset configuration file of all HTTPS domain names declared in **module.json5**. It checks whether any field of the **apps** array in the asset configuration file matches the current application. If so, the verification is successful. Otherwise, the verification fails.
25* During application uninstall, BundleManagerService calls the deletion API of AppDomainNameVerify to delete the verification result of the application.
26* During application update, BundleManagerService calls the APIs of AppDomainNameVerify to delete the verification result of the application and then initiate a new round of verification.
27* When **startAbility()** is called to trigger an inter-application implicit redirection, BundleManagerService passes in the want (implicit redirection, with an HTTPS URI) and abilities and transfers them to AppDomainNameVerify. Based on the cached mappings between the applications matching the passed-in abilities and the URI domain name in the want, AppDomainNameVerify obtains the ability of the application that passes the verification and sends that ability to BundleManagerService for more accurate redirection.
28
29#### Periodic Update
30
31If the verification fails, AppDomainNameVerify automatically updates the verification result on a regular basis after the device is powered on.
32
33## Directory Structure
34
35```text
36/foundation/bundlemanager/app_domain_verify/
37├── etc # Process configuration files
38├── figures # Architecture
39├── interfaces # APIs provided for external systems
40│ └── inner_api # Inner APIs
41├── profile # System service configuration files
42├── services # Feature implementation code
43├── test # Test code
44└──README.en.md # Instructions for use
45```
46
47## Build
48
49In the root directory of the OpenHarmony source code, call the following command to compile **app_domain_verify** separately:
50
51```shell
52./build.sh --product-name rk3568 --ccache --build-target app_domain_verify
53```
54
55> **NOTE**
56> - --**product-name**: product name, for example, **Hi3516DV300** and **rk3568**.
57> - --**ccache**: cache used during the build.
58> - --**build-target**: part to build.
59
60## Inner API Development Guide
61
62### Available APIs
63
64#### app_domain_verify_mgr_client.h
65
66Import the following header file before API calling:
67
68```c++
69#include "app_domain_verify_mgr_client.h"
70```
71
72|API|Description|
73|---|---|
74|VerifyDomain(const std::string &appIdentifier, const std::string &bundleName, const std::string &fingerprint, const std::vector<SkillUri> &skillUris): void|Called by BundleManagerService to trigger application domain name verification during application installation and update.|
75|ClearDomainVerifyStatus(const std::string &appIdentifier, const std::string &bundleName): bool|Called by BundleManagerService to clear the application verification information during application uninstall. The return value indicates whether the clearance is successful.|
76|FilterAbilities(const OHOS::AAFwk::Want &want, const std::vector<OHOS::AppExecFwk::AbilityInfo> &originAbilityInfos, std::vector<OHOS::AppExecFwk::AbilityInfo> &filtedAbilityInfos): bool|Called by BundleManagerService to find, from **AbilityInfos**, the ability of the application that passes the verification based on the HTTPS domain name in the want, when **startAbility** is used for inter-application implicit redirection. The return value indicates whether the filtering is successful.|
77
78#### skill_uri.h
79
80**skill_uri** information structure
81
82|Name|Type|Description|
83|----|----|----|
84| scheme | std::string | Protocol name of the URI. |
85| host | std::string | Host address of the URI. |
86| port | std::string | Port of the URI. |
87| path| std::string | Path of the URI. Set **path**, **pathStartWith**, or **pathRegex** as needed. |
88| pathStartWith| std::string | Path of the URI. Set **path**, **pathStartWith**, or **pathRegex** as needed. |
89| pathRegex| std::string | Path of the URI. Set **path**, **pathStartWith**, or **pathRegex** as needed. |
90| type| std::string | Data type that matches the want. The value complies with the Multipurpose Internet Mail Extensions (MIME) type specification. |
91
92### How to Develop
93
941. Add dependencies to bundle.json.
95
96 ```json
97 "deps": {
98 "components": [
99 "app_domain_verify"
100 ]
101 }
102 ```
103
1042. Add the dependency on the client module to the .gn file.
105
106 ```gn
107 external_deps = [
108 "app_domain_verify:app_domain_verify_mgr_client",
109 "app_domain_verify:app_domain_verify_common"
110 ]
111 ```
112
1133. Import the header file of the client to the header file.
114
115 ```c++
116 #include "app_domain_verify_mgr_client.h"
117 ```
118
1194. Call the APIs.
120
121 Call the APIs by referring to the description in [Available APIs](#available-apis) to verify the domain name.
README.md
1# 应用域名校验部件
2
3## 简介
4
5应用域名校验部件是包管理子系统中的一个部件，其与包管理基础框架，元能力管理服务，互相协作共同完成`Applinking`$^1$功能。该部件主要功能为：
6
71. 在应用的安装阶段，与应用关联的域名服务器进行通信，校验应用与域名的双向关联关系，并保存该关联关系。
81. 在打开链接时，根据保存的关联关系，过滤出域名关联的应用的ability。
9
10*注释：*
11
121. Applinking是一种链接跳转技术，是一种通过https链接直接将用户带到应用程序中的特定内容的技术。相比Deeplink，Applinking技术更加安全可靠，体验也更佳。
13
14### 架构图
15
16
17
18**图 1** 应用域名校验部件架构图
19
20### 基本流程
21
22#### 与包管理的交互
23
24* 应用安装时，包管理调用该部件的校验域名接口，获取应用module.json5中声明所有的https域名下的资产配置文件，校验资产配置文件apps数组字段中是否存在项匹配当前应用，如存在则在当前域名下校验成功，否则失败。
25* 应用卸载时，包管理调用该部件的删除接口，删去当前应用的校验结果。
26* 应用更新时，包管理会调用该部件的接口先删除当前应用的校验结果，再重新发起校验。
27* 当应用间使用startAbility进行应用间隐式跳转时，包管理会将Want(隐式跳转，uri为一个https链接)和初筛出的待跳转Ability作为入参，传递给应用域名校验部件，部件根据入参Ability所在应用与Want中uri域名的校验关系缓存，过滤出校验成功的应用的Ability，传回给包管理，完成更精确地应用间跳转。
28
29#### 周期刷新
30
31应用域名校验部件会在设备完成开机后以及固定的时间周期内主动刷新校验失败的应用校验结果。
32
33## 代码目录
34
35```text
36/foundation/bundlemanager/app_domain_verify/
37├── etc # 组件包含的进程的配置文件
38├── figures # 架构图
39├── interfaces # 组件对外提供的接口代码
40│ └── inner_api # 内部接口存放目录
41├── profile # 组件包含的系统服务的配置文件
42├── services # 应用域名校验服务实现
43├── test # 测试相关代码
44└──README_ZH.md # 使用说明
45```
46
47## 编译构建
48
49在OpenHarmony源码根目录下，调用以下指令，单独编译app_domain_verify。
50
51```shell
52./build.sh --product-name rk3568 --ccache --build-target app_domain_verify
53```
54
55> **说明：**
56--product-name：产品名称，例如Hi3516DV300、rk3568等。
57--ccache：编译时使用缓存功能。
58--build-target: 编译的部件名称。
59
60## Inner API开发指导
61
62### 接口说明
63
64#### app_domain_verify_mgr_client.h
65
66接口调用需要引入以下头文件。
67
68```c++
69#include "app_domain_verify_mgr_client.h"
70```
71
72|接口|说明|
73|---|---|
74|`VerifyDomain(const std::string &appIdentifier, const std::string &bundleName, const std::string &fingerprint, const std::vector<SkillUri> &skillUris)：void`|提供给BundleManagerService使用，在应用安装和更新时调用，用于触发应用域名校验任务。|
75|`ClearDomainVerifyStatus(const std::string &appIdentifier, const std::string &bundleName)：bool`|提供给BundleManagerService使用，在应用卸载时调用，用于清理被卸载应用的校验信息。返回值用于判断是否成功清理。|
76|`FilterAbilities(const OHOS::AAFwk::Want &want, const std::vector<OHOS::AppExecFwk::AbilityInfo> &originAbilityInfos, std::vector<OHOS::AppExecFwk::AbilityInfo> &filtedAbilityInfos)：bool`|提供给BundleManagerService使用，当应用间使用startAbility进行应用间隐式跳转时，从入参AbilityInfos中筛选出所在应用与want中https域名校验成功的部分。返回值用于判断是否筛选成功。|
77
78#### skill_uri.h
79
80skill_uri 信息结构体。
81
82|属性|类型|描述|
83|----|----|----|
84| scheme | std::string | URI的协议名部分。 |
85| host | std::string | URI的主机地址部分。 |
86| port | std::string | URI的端口部分。 |
87| path| std::string | URI的路径部分，path、pathStartWith和pathRegex配置时三选一。 |
88| pathStartWith| std::string | URI的路径部分，path、pathStartWith和pathRegex配置时三选一。 |
89| pathRegex| std::string | URI的路径部分，path、pathStartWith和pathRegex配置时三选一。 |
90| type| std::string | 标识与Want相匹配的数据类型，使用MIME类型规范。 |
91
92### 开发步骤
93
94#### 在bundle.json中加入依赖
95
96```json
97"deps": {
98 "components": [
99 "app_domain_verify"
100 ]
101}
102```
103
104#### 在模块gn文件中加入对客户端模块的依赖
105
106```gn
107external_deps = [
108 "app_domain_verify:app_domain_verify_mgr_client",
109 "app_domain_verify:app_domain_verify_common"
110]
111```
112
113#### 在头文件中引入客户端的头文件
114
115```c++
116#include "app_domain_verify_mgr_client.h"
117```
118
119#### 调用接口
120
121参考`接口说明`章节调用接口，完成域名校验相关功能。
122
