HarmonyOS 鸿蒙Next App Linking：无缝拉起应用，实现一步直达的极致体验

HarmonyOS 鸿蒙Next App Linking：无缝拉起应用，实现一步直达的极致体验 在移动应用生态中，如何让用户从外部（如网页、二维码、其他应用）一步直达应用内的特定页面，是提升用户体验的关键。HarmonyOS 提供的 App Linking（应用链接） 能力，正是为此而生。它基于安全的 HTTPS 链接，无论目标应用是否安装，都能为用户提供顺畅的跳转体验，是实现“服务找人”理念的重要桥梁。

一、 什么是 App Linking？

App Linking 是一种增强型的深度链接技术。与传统的 Deep Linking 相比，它通过域名校验机制，确保了链接的安全性与合法性，帮助用户识别并信任来自合法域名的应用。

其核心工作原理如下：

• 应用已安装：用户点击一个 HTTPS 链接（如 https://www.example.com/product/123），系统会优先打开已安装的对应应用，并直接跳转到商品详情页。
• 应用未安装：系统将自动打开浏览器，呈现为该链接开发的 H5 网页内容，确保用户始终能访问到目标信息。

一个典型的场景是“扫码直达”：用户通过控制中心的扫一扫功能，扫描一个商品二维码，即可一步跳转到电商应用的商品页，无需先打开应用再手动搜索。

二、 核心优势与约束

• 安全可靠：基于域名的所有权验证，防止恶意应用劫持链接。
• 无缝体验：覆盖应用安装与未安装两种状态，跳转流程无断点。
• 系统级集成：可通过系统浏览器、ArkWeb或任何调用 openLink 接口的应用拉起。

注意：该能力目前仅适用于 API 12 及以上版本的 HarmonyOS 应用，支持手机、平板、PC及TV等设备。

三、 开发全流程：从配置到拉起

实现 App Linking 需要目标方应用（被拉起的应用）和拉起方应用协同完成。

目标方应用配置（四步走）

第一步：服务器域名配置

在您的域名服务器（如 www.example.com）的 /.well-known/ 目录下，放置一个 applinking.json 文件，声明与此域名关联的应用。

{
  "applinking": {
    "apps": [
      {
        "appIdentifier": "您的应用APP ID" // 从AGC应用信息中获取
      }
    ]
  }
}

文件可通过 https://www.example.com/.well-known/applinking.json 被公开访问。

第二步：AGC平台关联

在 AppGallery Connect 后台的“增长 > App Linking”中，创建应用链接，填写您的完整域名（如 https://www.example.com）。AGC 会自动校验服务器配置，发布成功后即完成关联。

第三步：应用工程配置

在应用的 module.json5 文件中，声明应用关联的域名，并开启域名校验。

{
  "module": {
    "abilities": [
      {
        "name": "EntryAbility",
        "exported": true, // 必须为true
        "skills": [
          // ... 应用主入口skill配置
          {
            "entities": [
              "entity.system.browsable" // 必须包含
            ],
            "actions": [
              "ohos.want.action.viewData" // 必须包含
            ],
            "uris": [
              {
                "scheme": "https", // 必须为https
                "host": "www.example.com", // 您的域名
                "path": "products" // (可选)限制只处理特定路径
              }
            ],
            "domainVerify": true // 开启域名校验
          }
        ]
      }
    ]
  }
}

第四步：处理传入的链接

在 Ability 的 onCreate 或 onNewWant 生命周期中，解析传入的 Want 对象，获取链接参数，并据此跳转到指定页面。

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; // 例如: https://www.example.com/products?action=detail&id=1001
    if (uri) {
      let urlObject = url.URL.parseURL(uri);
      let productId = urlObject.params.get('id');
      // 根据 productId 跳转到商品详情页
      // ...
    }
  }
}

拉起方应用实现

拉起方应用只需一行核心代码，通过 openLink 接口即可触发跳转。

import { BusinessError } from '@kit.BasicServicesKit';

// 获取UIAbilityContext
let context = ...; 

let targetLink: string = "https://www.example.com/products?action=detail&id=1001";

// 方式一：仅尝试通过App Linking拉起应用，失败则进入catch块
context.openLink(targetLink, { appLinkingOnly: true })
  .then(() => {
    console.info('跳转成功');
  })
  .catch((error: BusinessError) => {
    console.error(`跳转失败，错误码: ${error.code}`);
    // 可以在这里降级处理，例如用ArkWeb打开链接
  });

// 方式二：优先拉起应用，失败则自动降级到浏览器
context.openLink(targetLink) // 或 { appLinkingOnly: false }
  .then(() => {
    console.info('跳转成功');
  });

四、 常见问题（FAQ）排查

1. 链接无法拉起应用？
   • 检查 module.json5 中的 host 是否与AGC配置的域名完全一致。
   • 确保服务器的 applinking.json 可公开访问且内容正确。
   • 应用安装后，系统需要约20秒完成域名校验，请耐心等待。
2. 如何验证域名校验是否成功？

在 DevEco Studio 终端中执行命令：hdc shell hidumper -s AppDomainVerifyManager。查看输出中对应域名的状态是否为 success。

1. 一个域名可以关联多个应用吗？

可以。系统会弹出列表让用户选择。开发者也可以通过配置不同的 path 来精确指向特定应用。

五、 总结

HarmonyOS App Linking 通过一套安全、标准的流程，将 Web 与原生应用无缝衔接，极大地丰富了应用的分发与触达场景。无论是扫码直达、营销分享还是跨应用跳转，它都为开发者提供了强大的技术支撑。遵循上述配置与开发步骤，你就能轻松构建出“一步直达”的下一代智慧化应用体验。

欢迎大家来一起学习：https://developer.huawei.com/consumer/cn/training/classDetail/9d5d34e77df44f55bb7d2bd83ed8dd94?type=1?ha_source=hmosclass&ha_sourceId=89000248