【HarmonyOS 6.0】聚合链接（App Linking）实战：从创建配置到应用跳转
文章目录
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 -> 申请链接前缀
链接前缀是您所有聚合链接的共用域名。
- 登录AGC，进入您的项目，选择“增长 > App Linking > 聚合链接”。
- 在“链接前缀”页签，点击“添加链接前缀”。
- 在华为提供的免费域名（如
drcn.agconnect.link）前，设置一个唯一的前缀字符串（仅支持小写字母和数字），例如myapp-promo。完成后点击“下一步”并等待验证通过。
此时，就拥有了一个属于自己的链接前缀：https://myapp-promo.drcn.agconnect.link。
3.1.2 -> 添加网址允许清单
为防止跳转到非法网站，需要设置允许清单规则。
- 在“聚合链接”页面，选择“网址允许清单”页签，点击“添加允许清单规则”。
- 假设您只允许跳转到自己应用内的商品详情页和官网，可以使用正则表达式设置规则，例如：
^https://myapp\.com/goods/.*和^https://www\.myapp\.com$。设置完成后点击“发布”。
3.1.3 -> 创建聚合链接
这是最核心的步骤，将配置链接的具体跳转行为。
- 在“聚合链接”页签，点击“创建聚合链接”。
- 设置短链接：选择您刚创建的链接前缀
myapp-promo.drcn.agconnect.link，并设置一个易记的短链接后缀，例如summer-sale。那么最终的聚合链接就是https://myapp-promo.drcn.agconnect.link/summer-sale。 - 设置深度链接：
- 链接名称：填写“暑期大促链接”。
- 深度链接地址（默认）：为其他平台（如Android）准备的链接，例如
https://myapp.com/goods/123。 - HarmonyOS深度链接地址(api>=12)：为鸿蒙应用准备的链接，我们希望它打开应用内的指定页面，因此可以设置为自定义scheme的链接，例如
myapp://goods/123。注意：这个地址的域名部分（myapp.com）需要符合您在第3.1.2步设置的允许清单规则。
- 设置HarmonyOS链接行为：
- 设置在HarmonyOS系统的链接行为(api>=12)：选择“在HarmonyOS应用中打开”。
- 选择或添加需要配置深度链接地址的HarmonyOS应用：从列表中选择您的应用
com.example.myapplication。 - 未安装应用时，则重定向到：选择“华为应用市场页面详情页”。（若选择“自定义网址”，则可输入如
https://www.myapp.com/download/的下载引导页）。
- （可选）设置社交分享标识：为了让链接在微信、微博等社交平台分享时更美观，可以在此设置分享的标题、图片URL和描述说明。
- （可选）设置预览页：
- 勾选“显示预览页”。这样，在未安装应用的用户点击链接时，会先看到一个精美的预览页，再跳转到应用市场。
- 预览页信息来源：可选择“分享标识内容”（使用上一步设置的社交分享信息构建预览页）或“应用市场应用信息”（使用AGC中配置的应用信息构建）。
- 全部设置完成后，点击右上角的“发布”。现在，您的聚合链接就正式生效了。
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.etsimport{ AbilityConstant, UIAbility, Want }from'@kit.AbilityKit';import{ hilog }from'@kit.PerformanceAnalysisKit';import{ url }from'@kit.ArkTS';import{ router }from'@kit.ArkUI';// 导入路由模块exportdefaultclassEntryAbilityextendsUIAbility{onCreate(want: Want, launchParam: AbilityConstant.LaunchParam):void{// 处理通过聚合链接启动的情况this.handleAppLinking(want);}onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam):void{// 当应用已在后台，通过聚合链接再次启动时，在此处理this.handleAppLinking(want);}privatehandleAppLinking(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 中获取}});}elseif(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.etsimport{ common }from'@kit.AbilityKit';exportclassGlobalContext{privatestatic instance: GlobalContext;private context?: common.UIAbilityContext;publicstaticgetInstance(): GlobalContext {if(!GlobalContext.instance){ GlobalContext.instance =newGlobalContext();}return GlobalContext.instance;}publicsetContext(context: common.UIAbilityContext){this.context = context;}publicgetContext(): common.UIAbilityContext {returnthis.context!;}}在EntryAbility的onCreate中初始化这个全局Context。
// entry/src/main/ets/entryability/EntryAbility.etsimport{ GlobalContext }from'../common/GlobalContext';// ... 其他导入exportdefaultclassEntryAbilityextendsUIAbility{onCreate(want: Want, launchParam: AbilityConstant.LaunchParam):void{ GlobalContext.getInstance().setContext(this.context);// ... 其他代码}// ...}最后，在您的页面组件中（例如一个Button的点击事件），调用openLink接口。
// entry/src/main/ets/pages/Index.etsimport{ 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的深度集成，实现了从链接创建、行为配置、效果追踪到客户端解析的完整闭环。
对于开发者而言，掌握聚合链接技术意味着能够构建更流畅的用户体验。通过本文的实战步骤，您可以快速为自己的应用接入这一能力，无论是用于精准的营销活动推广，还是作为应用内社交分享的基础设施，聚合链接都将成为您鸿蒙生态工具箱中不可或缺的一员。随着鸿蒙生态的不断壮大，善用此类系统级能力，必将为您的应用带来更多的增长机会。
感谢各位大佬支持！！！
互三啦！！！
