HarmonyOS Next App Linking Development Guide: Achieving Seamless App Navigation Experience

I. Introduction to App Linking

App Linking is an app navigation technology provided by HarmonyOS, which directs users to specific content within a target app via HTTPS links. Whether the target app is installed or not, users can access the content corresponding to the link. Compared with traditional Deep Linking, App Linking offers a smoother navigation experience.

Typical Application Scenario: After developers integrate the "Scan to Go" service, users can scan the app's QR code or barcode through system-level scanning entrances (such as the Scan function in the Control Center) to directly jump to the corresponding service page of the developer's app, achieving a one-step direct user experience.

II. Applicable Scenarios and Advantages

Applicable Scenarios

• App's scan-to-go service
• Social sharing functions
• Silent app activation (re-engaging users via links)
• Advertising traffic conversion

Core Advantages

1. High Security: Suitable for scenarios with high security requirements, avoiding counterfeiting by other apps.
2. Superior Experience: Users can normally access the link whether the target app is installed or not.
3. Cross-platform Compatibility: When the app is not installed, it automatically degrades to a web-based experience.

III. Implementation Principle

App Linking adds a domain name verification process based on Deep Linking. This mechanism helps users eliminate ambiguity, identify apps legally belonging to specific domain names, and makes links more secure and reliable.

Workflow:

• The same HTTPS URL supports both app and web content presentation.
• When the app is installed: Prioritizes opening the app to present content.
• When the app is not installed: Opens the browser to present web-based content.

IV. Development Guidelines

Role Division

Responsibilities of the Target Party (App Developer)

1. Cloud Development
   • Enable the App Linking service in the AGC console.
   • Associate the app on the developer website.
   • Associate the URL domain name in the AGC console.
2. Client Development
   • Configure the associated URL domain name in DevEco Studio.
   • Process incoming links.
3. Front-end Development
   • Develop the H5 webpage corresponding to the link (presented when the app is not installed).

Responsibilities of the Launching Party (App Initiating Navigation)

1. Client Development
   • Call system interfaces to trigger link navigation.

V. Detailed Development Steps for the Target App

1. Enable the App Linking Service in the AGC Console

1. Log in to AppGallery Connect and click "My Projects".
2. Select the target project.
3. In the left navigation bar, select "Growth > App Linking", then click "Enable Now".
4. If the data processing location is not set, enable and set the default location as prompted.
5. Go to "Project Settings > General" to view the app's APP ID (required for subsequent development).

2. Associate the App on the Developer Website

Create a domain configuration file applinking.json:

{
 "applinking": {
   "apps": [
     {
       "appIdentifier": "1234567"  // Replace with the APP ID displayed in the AGC console
     }
   ]
 }
}

File deployment location:

https://domain.name/.well-known/applinking.json
// Example: https://www.example.com/.well-known/applinking.json

3. Associate the URL Domain Name in the AGC Console

1. Log in to AppGallery Connect and enter the project.
2. In the left navigation bar, select "Growth > App Linking", then go to the "App Links (for API >=12)" tab.
3. Click "Create", enter the exact URL domain name (e.g., https://www.example.com).
4. After setting, click "Publish", and the system will verify the domain configuration file.

Verification Mechanism:

• The configuration file will be re-fetched for verification within 24 hours after publication.
• Verification successful: Domain-associated app information is visible.
• Verification in progress: Status shows "Publishing".
• Verification failed: Status shows "Publishing Failed" with a reason.

4. Configure the Associated URL Domain Name in DevEco Studio

Add the following configuration to the app's module.json5 file:

{
  "module": {
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ts",
        "icon": "$media:icon",
        "label": "$string:EntryAbility_label",
        "exported": true,
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:start_window_background",
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "ohos.want.action.home"
            ]
          },
          {
            "entities": [
              "entity.system.browsable"
            ],
            "actions": [
              "ohos.want.action.viewData"
            ],
            "uris": [
              {
                "scheme": "https",
                "host": "www.example.com",
                "path": "path1"
              }
            ],
            "domainVerify": true
          }
        ]
      }
    ]
  }
}

Configuration Key Points:

• entities must include "entity.system.browsable".
• actions must include "ohos.want.action.viewData".
• uris must include an element with scheme as "https" and host as the domain address.
• Set domainVerify to true to enable domain name verification.

5. Process Incoming Links

Add link processing code in the Ability lifecycle callback (e.g., EntryAbility):

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { url } from '@kit.ArkTS';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    let uri = want?.uri;
    if (uri) {
      let urlObject = url.URL.parseURL(want?.uri);
      let action = urlObject.params.get('action');
      if (action === "showall"){
         // Process logic to display all programs
      }
      // Process other parameters...
    }
  }
}

VI. Navigation Guidance for the Launching Party

Use the openLink Interface to Launch the App

Method 1: Open the App Only via App Linking

// Implement in Index.ets
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { GlobalContext } from '../common/GlobalContext';

@Entry
@Component
struct Index {
  build() {
    Button('start link', { type: ButtonType.Capsule, stateEffect: true })
      .width('87%')
      .height('5%')
      .margin({ bottom: '12vp' })
      .onClick(() => {
        let context = GlobalContext.getContext();
        let link: string = "https://www.example.com/programs?action=showall";
        // Open the app only via App Linking
        context.openLink(link, { appLinkingOnly: true })
          .then(() => {
            hilog.info(0x0000, 'testTag', `Succeeded in opening link.`);
          })
          .catch((error: BusinessError) => {
            hilog.error(0x0000, 'testTag', `Failed to open link, code: ${error.code}, message: ${error.message}`);
          });
      })
  }
}

Method 2: Open the App with App Linking Priority

Simply set the appLinkingOnly parameter to false or omit it.

VII. Verification and Troubleshooting

Verify the App Launch Effect

1. Manually sign the app (automatic signing is not allowed).
2. Compile, package, and install it on the debugging device.
3. Test the navigation function via the launching app.

Common Issue Troubleshooting

1. Incorrect skills configuration in the app's module.json5 file

• Check if the domain name in the "host" field is correctly set.
• Ensure independent skill objects are created for different navigation scenarios.

2. Incorrect developer website server configuration

• Check if appIdentifier in applinking.json is correct.
• Confirm the file is located in the .well-known directory.
• Test accessibility by visiting https://your.domain.name/.well-known/applinking.json in a browser.

3. System has not completed domain name verification

• Wait at least 20 seconds after installing the app.
• Check network connection status (weak networks may cause verification failure).
• The system will automatically retry verification within 24 hours.

4. Confirm whether domain name verification succeeded

Use the following command to query the verification result:

hdc shell hidumper -s AppDomainVerifyManager

Success message example:

BundleName:
  appIdentifier:123456789
   domain verify status:
    https://www.example.com:success

Error message handling:

• client-error: Check appIdentifier and domain publication status.
• http_unknown: Ensure the device is connected to the network.
• Other errors: Contact technical support.

5. Pre-installed apps cannot be launched on the first device startup

• The system attempts verification within 20 minutes after the first startup.
• Failure may occur if there is no network connection during this period.
• Solution: Restart the device or wait 24 hours.

6. CDN content is not updated in a timely manner

• CDN caching time is 10 minutes; please be patient.

7. Correspondence between apps and domain names

• One app can be associated with multiple domains, and one domain can be associated with multiple apps.
• When multiple apps are associated with the same domain:
  • If each app has the same uris configuration, the system will display a selection list.
  • Target apps can be distinguished by configuring different paths.

VIII. Conclusion

HarmonyOS's App Linking technology provides developers with a powerful and flexible app navigation solution, offering strong support for enhancing user experience, achieving precise marketing, and improving app security. Through the detailed steps in this guide, developers can smoothly implement App Linking integration and create a seamless app navigation experience for users.