• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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
39> **NOTE**
40>
41> By default, the **skills** field contains a **skill** object, which is used to identify the application entry. Application redirection links should not be configured in this object. Instead, separate **skill** objects should be used. If there are multiple redirection scenarios, create different **skill** objects under **skills**. Otherwise, the configuration does not take effect.
42
43
44For example, the configuration below declares that the application is associated with the domain name www.example.com.
45
46```json
47{
48  "module": {
49    // ...
50    "abilities": [
51      {
52        // ...
53        "skills": [
54          {
55            "entities": [
56              "entity.system.home"
57            ],
58            "actions": [
59              "action.system.home"
60            ]
61          },
62          {
63            "entities": [
64              // entities must contain "entity.system.browsable".
65              "entity.system.browsable"
66            ],
67            "actions": [
68              // actions must contain "ohos.want.action.viewData".
69              "ohos.want.action.viewData"
70            ],
71            "uris": [
72              {
73                // scheme must be set to https.
74                "scheme": "https",
75                // host must be set to the associated domain name.
76                "host": "www.example.com",
77                // path is optional. To distinguish between applications that are associated with the same domain name, you are advised to configure this field.
78                "path": "path1"
79              }
80            ],
81            // domainVerify must be set to true.
82           "domainVerify": true
83          } // Add a skill object for redirection. If there are multiple redirection scenarios, create multiple skill objects.
84        ]
85      }
86    ]
87  }
88}
89```
90
91### Associating the Application on the Developer Website
92
93Perform the following operations on the developer website to associate the application:
94
951. Create the domain name configuration file **applinking.json**.
96
97   The content is as follows:
98
99   ```json
100   {
101    "applinking": {
102      "apps": [
103        {
104          "appIdentifier": "1234"
105        }
106      ]
107    }
108   }
109   ```
110
111   **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).
112
1131. Place the domain name configuration file in a fixed directory on the DNS.
114
115   The fixed directory is as follows:
116
117   > https://*your.domain.name*/.well-known/applinking.json
118
119   For example, if the domain name is www.example.com, place the **applinking.json** file in the following directory:
120   `https://www.example.com/.well-known/applinking.json`
121
122
123### Adding Code to the Ability of the Application to Handle the Passed-in Link
124
125Add code to the **onCreate()** or **onNewWant()** lifecycle callback of the ability (such as EntryAbility) of the application to handle the passed-in link.
126
127```ts
128import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
129import { url } from '@kit.ArkTS';
130
131export default class EntryAbility extends UIAbility {
132  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
133    // Obtain the input link information from want.
134    // For example, the input URL is https://www.example.com/programs?action=showall.
135    let uri = want?.uri
136    if (uri) {
137      // Parse the query parameter from the link. You can perform subsequent processing based on service requirements.
138      let urlObject = url.URL.parseURL(want?.uri);
139      let action = urlObject.params.get('action')
140      // For example, if action is set to showall, all programs are displayed.
141      if (action === "showall") {
142         // ...
143      }
144    }
145  }
146}
147```
148
149## Implementing Application Redirection (Required for the Caller Application)
150
151The caller application passes in the link of the target application through the **UIAbilityContext.openLink** API to start the target application.
152
153The **openLink** API provides two methods for starting the target application.
154
155  - Method 1: Open the application only in App Linking mode.
156
157    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.
158
159  - Method 2: Open the application preferentially in App Linking mode.
160
161    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.
162
163This section describes method 1, in order to check whether the App Linking configuration is correct. The following is an example.
164
165```ts
166import common from '@ohos.app.ability.common';
167import { BusinessError } from '@ohos.base';
168
169@Entry
170@Component
171struct Index {
172  build() {
173    Button('start link', { type: ButtonType.Capsule, stateEffect: true })
174      .width('87%')
175      .height('5%')
176      .margin({ bottom: '12vp' })
177      .onClick(() => {
178        let context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
179        let link: string = "https://www.example.com/programs?action=showall";
180        // Open the application only in App Linking mode.
181        context.openLink(link, { appLinkingOnly: true })
182          .then(() => {
183            console.info('openlink success.');
184          })
185          .catch((error: BusinessError) => {
186            console.error(`openlink failed. error:${JSON.stringify(error)}`);
187          });
188      })
189  }
190}
191```
192
193If the target application is started, the App Linking configuration of the target application is correct.
194
195## FAQs
196
197
1981. What should I do when the value of **skills** in the **Modules.json5** file of the application is incorrect?
199
200   Ensure that the value of **host** is the domain name of the application.
201
2022. What should I do when the developer website server is incorrectly configured?
203
204   * Check the JSON configuration of the server and ensure that the value of **appIdentifier** is correct.
205   * 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.
206
2073. What should I do when the system has not verified the domain name?
208
209   After installing the application on the device, wait for at least 20 seconds to ensure that asynchronous verification is complete.
210
2114. What is the mapping between applications and domain names?
212
213   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.
214
2155. If a domain name is associated with multiple applications, which application will be started by domain name?
216
217   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.
218
219   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.
220
221