文章目录

1 -> 概述：什么是鸿蒙聚合链接？

在鸿蒙生态蓬勃发展的今天，如何高效、精准地将用户从各种渠道引导至应用内的指定页面，已成为开发者推广和运营的关键。鸿蒙6.0（API 12及以上）推出的聚合链接（App Linking）服务，正是为解决这一痛点而生。

简单来说，聚合链接是一种“智能”的HTTP/HTTPS链接。它不再只是一个简单的网页地址，而是一个具备业务分发能力的桥梁。当用户在HarmonyOS设备上点击聚合链接时，系统会根据预设的规则和用户当前的状态（是否已安装应用），将用户引导至最合适的目标页面。

这一能力深度集成于HarmonyOS系统层，不仅支持通过短信、邮件、社交分享等常规方式分发，还支持在应用内通过openLink接口或系统浏览器（包括集成ArkWeb的WebView）中直接拉起目标应用，真正实现了**“一处创建，多端智能分发”**。

2 -> 聚合链接的核心价值

相较于传统的深度链接，鸿蒙聚合链接在6.0版本中带来的提升尤为显著，其核心价值主要体现在以下几个方面：

  • 精准的用户引导：告别“是否打开应用”的通用弹窗。聚合链接能够根据应用安装状态，实现差异化跳转：已安装用户直接进入应用内指定内容页（深度链接）；未安装用户则被引导至应用市场详情页下载，或先展示一个精美的预览页再跳转，甚至可跳转至您指定的H5活动页面。 这种“一户一策”的引导策略，能最大程度地减少用户流失，提升下载转化率和用户体验。
  • 一站式的链接管理：开发者可以在AppGallery Connect（AGC）后台，一站式完成链接前缀申请、跳转行为配置、社交分享信息设置以及广告跟踪参数埋点。所有与链接相关的配置和数据分析都集中在一起，极大地简化了工作流程。
  • 跨平台能力的基础：聚合链接的设计理念是面向多平台的。虽然核心优势体现在HarmonyOS设备上，但它为同一个应用在iOS、Android等不同平台上的统一推广提供了可能。您可以为不同平台配置不同的深度链接，实现跨平台的统一跳转体验。
  • 安全可控的跳转：通过“网址允许清单”功能，开发者可以严格限定聚合链接允许重定向的网址格式（使用正则表达式）。这能有效防止恶意网址注入和网站诱骗，保障了用户和应用的链接安全。
  • 可追踪的运营效果：在创建链接时，可以方便地设置广告系列来源、媒介和名称等跟踪参数。这使得聚合链接可以与您的广告投放、活动推广系统无缝对接，方便您统计不同渠道的引流效果，为运营决策提供数据支持。

3 -> 开发实战：从创建配置到应用跳转

接下来，我们将通过一个完整的示例，详细介绍如何从零开始配置和使用聚合链接。假设您的应用包名为 com.example.myapplication，您希望创建一个链接，当用户点击时：

  • 如果已安装应用，则直接打开应用内的“商品详情页”。
  • 如果未安装，则先显示一个应用介绍预览页，然后引导用户前往华为应用市场下载。

3.1 -> 目标方应用配置（AGC后台）

在编写代码前，首先需要在AppGallery Connect（简称AGC）后台完成链接的创建和配置。

3.1.1 -> 申请链接前缀

链接前缀是您所有聚合链接的共用域名。

  1. 登录AGC，进入您的项目，选择“增长 > App Linking > 聚合链接”。
  2. 在“链接前缀”页签，点击“添加链接前缀”。
  3. 在华为提供的免费域名（如 drcn.agconnect.link）前，设置一个唯一的前缀字符串（仅支持小写字母和数字），例如 myapp-promo。完成后点击“下一步”并等待验证通过。

此时，就拥有了一个属于自己的链接前缀：https://myapp-promo.drcn.agconnect.link。

3.1.2 -> 添加网址允许清单

为防止跳转到非法网站，需要设置允许清单规则。

  1. 在“聚合链接”页面，选择“网址允许清单”页签，点击“添加允许清单规则”。
  2. 假设您只允许跳转到自己应用内的商品详情页和官网，可以使用正则表达式设置规则，例如：^https://myapp\.com/goods/.* 和 ^https://www\.myapp\.com$。设置完成后点击“发布”。

3.1.3 -> 创建聚合链接

这是最核心的步骤，将配置链接的具体跳转行为。

  1. 在“聚合链接”页签，点击“创建聚合链接”。
  2. 设置短链接：选择您刚创建的链接前缀 myapp-promo.drcn.agconnect.link，并设置一个易记的短链接后缀，例如 summer-sale。那么最终的聚合链接就是 https://myapp-promo.drcn.agconnect.link/summer-sale。
  3. 设置深度链接：
    • 链接名称：填写“暑期大促链接”。
    • 深度链接地址（默认）：为其他平台（如Android）准备的链接，例如 https://myapp.com/goods/123。
    • HarmonyOS深度链接地址(api>=12)：为鸿蒙应用准备的链接，我们希望它打开应用内的指定页面，因此可以设置为自定义scheme的链接，例如 myapp://goods/123。注意：这个地址的域名部分（myapp.com）需要符合您在第3.1.2步设置的允许清单规则。
  4. 设置HarmonyOS链接行为：
    • 设置在HarmonyOS系统的链接行为(api>=12)：选择“在HarmonyOS应用中打开”。
    • 选择或添加需要配置深度链接地址的HarmonyOS应用：从列表中选择您的应用 com.example.myapplication。
    • 未安装应用时，则重定向到：选择“华为应用市场页面详情页”。（若选择“自定义网址”，则可输入如 https://www.myapp.com/download/ 的下载引导页）。
  5. （可选）设置社交分享标识：为了让链接在微信、微博等社交平台分享时更美观，可以在此设置分享的标题、图片URL和描述说明。
  6. （可选）设置预览页：
    • 勾选“显示预览页”。这样，在未安装应用的用户点击链接时，会先看到一个精美的预览页，再跳转到应用市场。
    • 预览页信息来源：可选择“分享标识内容”（使用上一步设置的社交分享信息构建预览页）或“应用市场应用信息”（使用AGC中配置的应用信息构建）。
  7. 全部设置完成后，点击右上角的“发布”。现在，您的聚合链接就正式生效了。

3.2 -> 目标方应用开发（客户端配置）

链接已创建，现在需要让您的HarmonyOS应用能够识别并响应这个链接。

3.2.1 -> 在module.json5中配置聚合链接

在您的应用工程中，找到 entry/src/main/module.json5 文件，在abilities中为接收聚合链接的Ability（通常是EntryAbility）添加一个新的skills对象。

关键点：

  • 必须创建一个独立的skills对象，与应用入口的skills（通常包含entity.system.home）分开。
  • entities中必须包含 "entity.system.browsable"。
  • actions中必须包含 "ohos.want.action.viewData"。
  • uris中配置的scheme为https，host为您在AGC申请的完整域名（例如myapp-promo.drcn.agconnect.link）。path是可选的，如果您的应用只处理特定的链接后缀（如/summer-sale），强烈建议在此配置，避免其他无效链接也试图拉起您的应用。
  • 必须将 "domainVerify" 设置为 true，开启域名校验。
// entry/src/main/module.json5
{
  "module": {
    // ... 其他配置
    "abilities": [
      {
        "name": "EntryAbility",
        // ... 其他配置
        "exported": true,
        "skills": [
          { // 原有的应用入口skill
            "entities": ["entity.system.home"],
            "actions": ["ohos.want.action.home"]
          },
          { // 新增的聚合链接处理skill
            "entities": ["entity.system.browsable"],
            "actions": ["ohos.want.action.viewData"],
            "uris": [
              {
                "scheme": "https",
                "host": "myapp-promo.drcn.agconnect.link",
                "path": "summer-sale" // 指定只处理 /summer-sale 这个链接
              }
            ],
            "domainVerify": true // 开启域名校验
          }
          // 如有其他跳转，可继续新增skill
        ]
      }
    ]
  }
}

3.2.2 -> 处理传入的链接

在Ability（如EntryAbility）中，重写onCreate()（首次启动）或onNewWant()（应用已在后台运行）方法，从Want参数中解析出链接信息，并进行相应的页面导航。

// entry/src/main/ets/entryability/EntryAbility.ets
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { url } from '@kit.ArkTS';
import { router } from '@kit.ArkUI'; // 导入路由模块

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // 处理通过聚合链接启动的情况
    this.handleAppLinking(want);
  }

  onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // 当应用已在后台，通过聚合链接再次启动时，在此处理
    this.handleAppLinking(want);
  }

  private handleAppLinking(want: Want): void {
    let incomingUri = want?.uri;
    hilog.info(0x0000, 'AppLinkingDemo', `Received URI: ${incomingUri}`);

    if (incomingUri) {
      try {
        let urlObject = url.URL.parseURL(incomingUri);
        // 根据不同的链接后缀，跳转到不同的应用内页面
        if (urlObject.pathname === '/summer-sale') {
          // 跳转到商品详情页，并传递商品ID
          router.pushUrl({
            url: 'pages/GoodsDetailPage',
            params: {
              goodsId: '123' // 可以从URL中解析参数，例如从 query 中获取
            }
          });
        } else if (urlObject.pathname === '/user-profile') {
          // 跳转到个人主页
          router.pushUrl({ url: 'pages/UserProfilePage' });
        }
        // ... 其他业务逻辑
      } catch (error) {
        hilog.error(0x0000, 'AppLinkingDemo', `Failed to parse url. ${error}`);
      }
    }
  }
}

3.3 -> 拉起方应用开发（如何触发跳转）

除了用户直接在浏览器点击链接，您也可以在自己的应用中主动触发聚合链接的跳转。

3.3.1 -> 通过openLink接口拉起

鸿蒙提供了UIAbilityContext.openLink()接口，方便应用内部打开一个链接，并指定以App Linking优先的方式处理。

首先，创建一个全局类来持有UIAbilityContext。

// entry/src/main/ets/common/GlobalContext.ets
import { common } from '@kit.AbilityKit';

export class GlobalContext {
  private static instance: GlobalContext;
  private context?: common.UIAbilityContext;

  public static getInstance(): GlobalContext {
    if (!GlobalContext.instance) {
      GlobalContext.instance = new GlobalContext();
    }
    return GlobalContext.instance;
  }

  public setContext(context: common.UIAbilityContext) {
    this.context = context;
  }

  public getContext(): common.UIAbilityContext {
    return this.context!;
  }
}

在EntryAbility的onCreate中初始化这个全局Context。

// entry/src/main/ets/entryability/EntryAbility.ets
import { GlobalContext } from '../common/GlobalContext';
// ... 其他导入

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    GlobalContext.getInstance().setContext(this.context);
    // ... 其他代码
  }
  // ...
}

最后，在您的页面组件中（例如一个Button的点击事件），调用openLink接口。

// entry/src/main/ets/pages/Index.ets
import { GlobalContext } from '../common/GlobalContext';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct Index {
  build() {
    Column() {
      Button('打开暑期大促商品页')
        .onClick(() => {
          let context = GlobalContext.getInstance().getContext();
          // 这是我们在AGC创建的聚合链接
          let appLinking: string = "https://myapp-promo.drcn.agconnect.link/summer-sale";

          context.openLink(appLinking, { appLinkingOnly: false })
            .then(() => {
              hilog.info(0x0000, 'AppLinkingDemo', 'openLink 成功');
            })
            .catch((error: BusinessError) => {
              hilog.error(0x0000, 'AppLinkingDemo', `openLink 失败, code: ${error.code}, message: ${error.message}`);
            });
        })
    }
    .width('100%')
    .height('100%')
  }
}

当点击这个按钮时，系统会优先尝试以App Linking的方式处理。如果目标应用已安装，则直接拉起并跳转到/summer-sale对应的页面；如果未安装，则遵循您在AGC后台配置的规则（显示预览页后跳转应用市场）。

4 -> 总结

鸿蒙6.0推出的聚合链接服务，为开发者和运营人员提供了一套强大、灵活且安全的跨平台应用跳转解决方案。它不仅解决了传统跳转方式中体验割裂、转化率低的问题，更通过与AGC的深度集成，实现了从链接创建、行为配置、效果追踪到客户端解析的完整闭环。

对于开发者而言，掌握聚合链接技术意味着能够构建更流畅的用户体验。通过本文的实战步骤，您可以快速为自己的应用接入这一能力，无论是用于精准的营销活动推广，还是作为应用内社交分享的基础设施，聚合链接都将成为您鸿蒙生态工具箱中不可或缺的一员。随着鸿蒙生态的不断壮大，善用此类系统级能力，必将为您的应用带来更多的增长机会。

感谢各位大佬支持！！！

互三啦！！！
# harmonyos # 华为 # 开发语言
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

鸿蒙App内存排查与监控全链路实战（工具+方案）

avatar HarmonyOS开发者社区
cover

HarmonyOS混合开发：WebView与原生交互深度优化

avatar HarmonyOS开发者社区
cover

HarmonyOS鸿蒙开发 | ArkUI组件与布局

avatar HarmonyOS开发者社区