1# Using App Linking for Application Redirection
2
3## Overview
4
5In App Linking, the system directs users to specific content in the target application based on the passed-in URI (HTTPS link). Unlike [Deep Linking](deep-linking-startup.md), users can directly access the content regardless of whether the target application is installed.
6
7
8## When to Use
9
10* App Linking applies to scenarios with high security requirements. It helps prevent spoofing of the target application.
11
12* App Linking applies to scenarios with high requirements on user experience. Users can directly access the content regardless of whether the target application is installed.
13
14## Working Principles
15
16* App Linking adopts domain name verification, which is unavailable in Deep Linking. Domain name verification helps identify valid applications, making links more secure and reliable.
17
18* App Linking requires that an HTTPS website be displayed in two modes: application and web page. When the application is installed, the application is preferentially opened to present the content. When the application is not installed, the web page is opened to present the content.
19
20
21## Procedure for the Target Application
22
23To use App Linking in the target application, perform the following operations:
24
251. Declare a domain name.
262. Associate the application on the developer website.
273. Add code to the ability of the application to handle the passed-in link.
28
29
30### Declaring a Domain Name
31
32Configure the [module.json5 file](../quick-start/module-configuration-file.md) of the application to declare the domain name associated with the application, and enable domain name verification:
33
34* The **actions** field must contain **ohos.want.action.viewData**.
35* The **entities** field must contain **entity.system.browsable**.
36* The **uris** field must contain an element whose **scheme** is **https** and **host** is a domain name address.
37* **domainVerify** must be set to **true**.
38
39For example, the configuration below declares that the application is associated with the domain name www.example.com.
40
41```json
42{
43  "module": {
44    // ...
45    "abilities": [
46      {
47        // ...
48        "skills": [
49          {
50            "entities": [
51              // entities must contain "entity.system.browsable".
52              "entity.system.browsable"
53            ],
54            "actions": [
55              // actions must contain "ohos.want.action.viewData".
56              "ohos.want.action.viewData"
57            ],
58            "uris": [
59              {
60                // scheme must be set to https.
61                "scheme": "https",
62                // host must be set to the associated domain name.
63                "host": "www.example.com",
64                // path is optional. To distinguish between applications that are associated with the same domain name, you are advised to configure this field.
65                "path": "path1"
66              }
67            ],
68            // domainVerify must be set to true.
69           "domainVerify": true
70          }
71        ]
72      }
73    ]
74  }
75}
76```
77
78### Associating the Application on the Developer Website
79
80Perform the following operations on the developer website to associate the application:
81
821. Create the domain name configuration file **applinking.json**.
83
84   The content is as follows:
85
86   ```json
87   {
88    "applinking": {
89      "apps": [
90        {
91          "appIdentifier": "1234"
92        }
93      ]
94    }
95   }
96   ```
97
98   **app-identifer** is the unique identifier allocated to an application during application signing. It is also the value of the **app-identifer** field declared in the [HarmonyAppProvision configuration file](../security/app-provision-structure.md).
99
1001. Place the domain name configuration file in a fixed directory on the DNS.
101
102   The fixed directory is as follows:
103
104   > https://*your.domain.name*/.well-known/applinking.json
105
106   For example, if the domain name is www.example.com, place the **applinking.json** file in the following directory:
107   `https://www.example.com/.well-known/applinking.json`
108
109
110### Adding Code to the Ability of the Application to Handle the Passed-in Link
111
112Add code to the **onCreate()** or **onNewWant()** lifecycle callback of the ability (such as EntryAbility) of the application to handle the passed-in link.
113
114```ts
115import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
116import { url } from '@kit.ArkTS';
117
118export default class EntryAbility extends UIAbility {
119  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
120    // Obtain the input link information from want.
121    // For example, the input URL is https://www.example.com/programs?action=showall.
122    let uri = want?.uri
123    if (uri) {
124      // Parse the query parameter from the link. You can perform subsequent processing based on service requirements.
125      let urlObject = url.URL.parseURL(want?.uri);
126      let action = urlObject.params.get('action')
127      // For example, if action is set to showall, all programs are displayed.
128      if (action === "showall") {
129         // ...
130      }
131    }
132  }
133}
134```
135
136## Implementing Application Redirection (Required for the Caller Application)
137
138The caller application passes in the link of the target application through the **UIAbilityContext.openLink** API to start the target application.
139
140The **openLink** API provides two methods for starting the target application.
141
142  - Method 1: Open the application only in App Linking mode.
143
144    In this mode, **appLinkingOnly** is set to **true**. If a matching application is found, that application is directly opened. If no application matches, an exception is thrown.
145
146  - Method 2: Open the application preferentially in App Linking mode.
147
148    In this mode, **appLinkingOnly** is set to **false** or uses the default value. App Linking is preferentially used to start the target application. If a matching application is found, that application is directly opened. If no application matches, the system attempts to open the application in Deep Linking mode.
149
150This section describes method 1, in order to check whether the App Linking configuration is correct. The following is an example.
151
152```ts
153import common from '@ohos.app.ability.common';
154import { BusinessError } from '@ohos.base';
155
156@Entry
157@Component
158struct Index {
159  build() {
160    Button('start link', { type: ButtonType.Capsule, stateEffect: true })
161      .width('87%')
162      .height('5%')
163      .margin({ bottom: '12vp' })
164      .onClick(() => {
165        let context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
166        let link: string = "https://www.example.com/programs?action=showall";
167        // Open the application only in App Linking mode.
168        context.openLink(link, { appLinkingOnly: true })
169          .then(() => {
170            console.info('openlink success.');
171          })
172          .catch((error: BusinessError) => {
173            console.error(`openlink failed. error:${JSON.stringify(error)}`);
174          });
175      })
176  }
177}
178```
179
180If the target application is started, the App Linking configuration of the target application is correct.
181
182## FAQs
183
184
1851. What should I do when the value of **skills** in the **Modules.json5** file of the application is incorrect?
186
187   Ensure that the value of **host** is the domain name of the application.
188
1892. What should I do when the developer website server is incorrectly configured?
190
191   * Check the JSON configuration of the server and ensure that the value of **appIdentifier** is correct.
192   * Check whether the **applinking.json** file is stored in the correct directory (**.well-known**). Use a browser to access the JSON file address https://*your.domain.name*/.well-known/applinking.json and ensure that the file is accessible.
193
1943. What should I do when the system has not verified the domain name?
195
196   After installing the application on the device, wait for at least 20 seconds to ensure that asynchronous verification is complete.
197
1984. What is the mapping between applications and domain names?
199
200   They are in a many-to-many relationship. An application can be associated with multiple domain names, and a domain name can be associated with multiple applications.
201
2025. If a domain name is associated with multiple applications, which application will be started by domain name?
203
204   You can configure the **applinking.json** file to associate a domain name with multiple applications. If the **uris** field in the **module.json5** file of each application is set to the same value, the system displays a dialog box for users to select the application to start.
205
206   You can also use the **path** field to distinguish the applications to start. For example, use **https://www.example.com/path1** to start target application 1 and use **https://www.example.com/path2** to start target application 2.
207
208