• 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              "ohos.want.action.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
92### Associating the Application on the Developer Website
93
94Perform the following operations on the developer website to associate the application:
95
961. Create the domain name configuration file **applinking.json**.
97
98   The content is as follows:
99
100   ```json
101   {
102    "applinking": {
103      "apps": [
104        {
105          "appIdentifier": "1234"
106        }
107      ]
108    }
109   }
110   ```
111
112   **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).
113
1141. Place the domain name configuration file in a fixed directory on the DNS.
115
116   The fixed directory is as follows:
117
118   > https://*your.domain.name*/.well-known/applinking.json
119
120   For example, if the domain name is www.example.com, place the **applinking.json** file in the following directory:
121   `https://www.example.com/.well-known/applinking.json`
122
123
124### Adding Code to the Ability of the Application to Handle the Passed-in Link
125
126Add code to the **onCreate()** or **onNewWant()** lifecycle callback of the ability (such as EntryAbility) of the application to handle the passed-in link.
127
128```ts
129import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
130import { url } from '@kit.ArkTS';
131
132export default class EntryAbility extends UIAbility {
133  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
134    // Obtain the input link information from want.
135    // For example, the input URL is https://www.example.com/programs?action=showall.
136    let uri = want?.uri
137    if (uri) {
138      // Parse the query parameter from the link. You can perform subsequent processing based on service requirements.
139      let urlObject = url.URL.parseURL(want?.uri);
140      let action = urlObject.params.get('action')
141      // For example, if action is set to showall, all programs are displayed.
142      if (action === "showall") {
143         // ...
144      }
145    }
146  }
147}
148```
149
150## Implementing Application Redirection (Required for the Caller Application)
151
152The caller application passes in the link of the target application through the **UIAbilityContext.openLink** API to start the target application.
153
154The **openLink** API provides two methods for starting the target application.
155
156  - Method 1: Open the application only in App Linking mode.
157
158    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.
159
160  - Method 2: Open the application preferentially in App Linking mode.
161
162    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.
163
164This section describes method 1, in order to check whether the App Linking configuration is correct. The following is an example.
165
166```ts
167import common from '@ohos.app.ability.common';
168import { BusinessError } from '@ohos.base';
169
170@Entry
171@Component
172struct Index {
173  build() {
174    Button('start link', { type: ButtonType.Capsule, stateEffect: true })
175      .width('87%')
176      .height('5%')
177      .margin({ bottom: '12vp' })
178      .onClick(() => {
179        let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
180        let link: string = "https://www.example.com/programs?action=showall";
181        // Open the application only in App Linking mode.
182        context.openLink(link, { appLinkingOnly: true })
183          .then(() => {
184            console.info('openlink success.');
185          })
186          .catch((error: BusinessError) => {
187            console.error(`openlink failed. error:${JSON.stringify(error)}`);
188          });
189      })
190  }
191}
192```
193
194If the target application is started, the App Linking configuration of the target application is correct.
195
196## FAQs
197
198
1991. What should I do when the value of **skills** in the **Modules.json5** file of the application is incorrect?
200
201   Ensure that the value of **host** is the domain name of the application.
202
2032. What should I do when the developer website server is incorrectly configured?
204
205   * Check the JSON configuration of the server and ensure that the value of **appIdentifier** is correct.
206   * 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.
207
2083. What should I do when the system has not verified the domain name?
209
210   After installing the application on the device, wait for at least 20 seconds to ensure that asynchronous verification is complete.
211
2124. What is the mapping between applications and domain names?
213
214   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.
215
2165. If a domain name is associated with multiple applications, which application will be started by domain name?
217
218   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.
219
220   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.
221
222