HarmonyOS 6碰一碰分享之App Linking跳转应用实战指导

一、引言

开发《智能带办》应用时，想在线下朋友或者亲人之间共享带办清单组，想到了使用碰一碰便捷的功能。一个用户生成清单后，通过连接碰一碰分享给另一个用户，两人一起操作清单提高效率。在研究碰一碰分享时发现了App Linking的能力，分享图片视频等文件相对容易，要实现碰一碰分享链接就避不开App Linking。

二、App Linking简介

我们在使用App Linking进行跳转时，系统会根据接口传入的uri信息（HTTPS链接）将用户引导至目标应用中的特定内容，无论应用是否已安装，用户都可以访问到链接对应的内容，跳转体验相比Deep Linking方式更加顺畅。

App Linking应用广泛，除了上面提到的碰一碰分享，还有“扫码直达”服务，接入App Linking后用户可通过控制中心扫一扫等系统级扫码入口，扫描应用的二维码、条形码并跳转到开发者应用对应服务页，实现一步直达的体验。

三、适用场景

App最主要的适用场景如下：

• 适用于应用的扫码直达、社交分享、沉默唤醒、广告引流等场景。
• 适用于对安全性要求较高的场景，避免出现被其它应用仿冒的问题。
• 适用于对体验要求较高的应用，不管目标应用是否安装，用户点击该链接都可以正常访问。

四、典型案例

官方给出最典型的App Linking案例如下：

（一）碰一碰视频分享

随着全场景智慧生活的不断演进，跨设备内容分享已成为用户的核心需求之一。传统分享方式普遍存在操作繁琐（需手动选择设备或应用）、依赖特定网络环境、传输效率低等问题，影响了用户体验。HarmonyOS提供的Share Kit（分享服务）结合App Linking Kit技术，能够实现内容的快速跨设备分享，直达目标应用，无需依赖第三方应用中转，提供高效、便捷、无缝的分享体验。

（二）游戏碰一碰快速组队

在《多乐中国象棋》这款组队竞技类游戏中，玩家只需轻轻碰触两台手机，即可实现秒速组队，省去了传统邀请流程中的繁琐操作，一步直达指定页面。与传统的通信软件分享视频相比，操作步骤减少了60%。

（三）通过扫码使服务快速触达用户

美团App结合App Linking技术，实现用户无需打开App，通过系统扫码即可直接解锁共享单车。在负一屏、控制中心、系统相机中均可解锁，操作入口增加了3倍，一步扫码直达，操作效率提升了30%以上。

五、实现原理

App Linking在Deep Linking基础上增加了域名校验环节，通过域名校验，可帮助用户消除歧义，识别合法归属于域名的应用，使链接更加安全可靠。

App Linking要求对于同一HTTPS网址，有应用和网页两种内容的呈现方式。当应用安装时则优先打开应用去呈现内容；当应用未安装时，则打开浏览器呈现Web版的内容。

这里要求开发者需要先在AppGallery Connecting 中注册https连接地址，https连接必须可访问，地址最终指向一个包含应用id的配置文件，安装应用后该配置会自动下载到手机。

六、开发指导概述

若要实现App Linking跳转体验，需目标方和拉起方的不同角色相互配合，共同完成。各个角色的分工如下：

（一）目标方

序号	角色	职责
1	云端开发	在AGC开通App Linking服务。
2	云端开发	在开发者网站上关联应用。
3	云端开发	在AGC创建关联的网址域名。
4	客户端开发	在module.json5中配置关联的网址域名。
5	客户端开发	处理传入的链接。
6	前端开发	开发链接对应的H5网页，应用未安装时呈现网页版内容。

（二）拉起方

序号	角色	职责
1	客户端开发	调用系统接口，触发链接跳转，具体请参见拉起方应用跳转实现。

七、目标方应用开发指导

（一）在AGC开通App Linking服务

请先参考“应用开发准备”完成基本准备工作，再继续进行以下开发活动：

1. 登录AppGallery Connect，点击“开发与服务”。
2. 在项目列表中点击您的项目。
3. 在左侧导航栏中选择“增长 > App Linking”，进入App Linking页面，点击“立即开通”。
4. 如果您的项目此时未设置数据处理位置，请在提示框内启用数据处理位置和设置默认数据处理位置，点击“确定”。

（二）在开发者网站上关联应用

在开发者的网站域名服务器上做如下配置。后续当您在AGC创建关联的网址域名时，AGC会通过此文件确认哪些应用才是合法归属于此域名的，使链接更加安全可靠。

1. 创建域名配置文件applinking.json，内容如下： { "applinking": { "apps": [ { "appIdentifier": "1234567" } ] } }其中appIdentifier填写创建应用时生成的APP ID。同一个网站域名可以关联多个应用，只需要在"apps"列表里放置多个"appIdentifier"元素即可，其中每个"appIdentifier"元素对应每个应用。
2. 将配置文件放在域名服务器的固定目录下：https://domain.name/.well-known/applinking.json
3. 例如：开发者的服务器域名为www.qingkouwei.com，则必须将applinking.json文件放在如下位置：https://www.qingkouwei.com/.well-known/applinking.json

（三）在AGC创建关联的网址域名

基于HarmonyOS应用链接能力，需要为HarmonyOS应用创建关联的网址域名。如果用户已安装HarmonyOS应用，则用户点击域名下网址链接后，系统会默认打开该HarmonyOS应用内的相关页面。操作步骤如下：

1. 登录AppGallery Connect，点击“开发与服务”。
2. 在项目列表中点击您的项目。
3. 在左侧导航栏中选择“增长 > App Linking”，选择“应用链接（API>=12适用）”页签，点击“创建”。
4. 说明：HarmonyOS应用开发者仅需关注“应用链接（API>=12适用）”页签，其他页签为元服务或其他系统适用的配置，无需关注。如果界面未展示“应用链接（API>=12适用）”页签，请在右侧的“自定义配置”中勾选。
5. 填写在开发者网站上关联应用的网址域名，例如：https://www.example.com。必须输入精确的域名，不可输入包含特殊字符的模糊网址。
6. 说明：不可以在域名后面添加/，即不支持“https://www.qingkouwei.com/”形式。
7. 设置完成后点击“发布”，AGC会对该网站域名的配置文件所包含的应用与本项目内的应用列表进行交集校验。
8. 说明：应用链接发布完成后，如果距离上次更新超过24小时，系统会去域名服务器上重新获取配置文件进行交集校验。比如我们在4月7日17:21创建了应用链接，系统会在4月8日17:30去域名服务器上重新获取配置文件，然后进行交集校验，更新发布状态。
9. 如果域名的配置文件中有应用存在本项目中，则发布成功，点击“查看”可显示该域名关联的应用信息。
10. 如果异步校验中，则状态为“发布中”。如果配置文件中没有任何应用在本项目中，则发布失败，点击“查看”可显示发布失败原因。
    

如果域名是不可访问的，则会导致发布失败。

（四）在module.json5中配置关联的网址域名

在应用的module.json5文件中进行如下配置，以声明应用关联的域名地址，并开启域名校验开关。

• “entities"列表中必须包含"entity.system.browsable”。
• “actions"列表中必须包含"ohos.want.action.viewData”。
• “uris"列表中必须包含"scheme"为"https"且"host"为域名地址的元素，可选属性包含"path”、“pathStartWith"和"pathRegex”，具体请参见“uris标签说明”。
• "domainVerify"设置为true，表示开启域名校验开关。

skills标签下默认包含一个skill对象，用于标识应用入口。应用跳转链接不能在该skill对象中配置，需要创建独立的skill对象。如果存在多个跳转场景，需要在skills标签下创建不同的skill对象，否则会导致配置无法生效。比如，声明应用关联的域名是www.qingkouwei.com，则需进行如下配置：

{
  "module": {
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "icon": "$media:icon",
        "label": "$string:EntryAbility_label",
        // 请将exported配置为true；如果exported为false，仅具有权限的系统应用能够拉起该应用，否则无法拉起应用
        "exported": true,
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:start_window_background",
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              // API19及以上版本须配置为"ohos.want.action.home"，API18及以下版本请配置为"action.system.home"
              "ohos.want.action.home"
            ]
          },
          {
            "entities": [
              // entities必须包含"entity.system.browsable"
              "entity.system.browsable"
            ],
            "actions": [
              // actions必须包含"ohos.want.action.viewData"
              "ohos.want.action.viewData"
            ],
            "uris": [
              {
                // scheme须配置为https
                "scheme": "https",
                // host须配置为关联的域名
                "host": "www.qingkouwei.com",
                // path可选，表示域名服务器上的目录或文件路径，例如www.qingkouwei.com/todo中的ptodo
                // 如果应用只能处理部分特定的path，则此处应该配置应用所支持的path，避免出现应用不能处理的path链接也被引流到应用中的问题
                "path": "todo"
              }
            ],
            // domainVerify须设置为true
           "domainVerify": true
          }
          // 若有其他跳转能力，如推送消息跳转、NFC跳转，可新增一个skill对象，防止与App Linking业务冲突
        ]
      }
    ]
  }
}

（五）处理传入的链接

在应用的Ability（如EntryAbility）的onCreate()或者onNewWant()生命周期回调中添加如下代码，以处理传入的链接。

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { url } from '@kit.ArkTS';
export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // 从want中获取传入的链接信息。
    // 如传入的url为：https://www.qingkouwei.com/todo?topic=d3sd3
    let uri = want?.uri;
    if (uri) {
      // 从链接中解析query参数，拿到参数后，开发者可根据自己的业务需求进行后续的处理。
      try {
        let urlObject = url.URL.parseURL(want?.uri);
        let topic = urlObject.params.get('topic');
        // 例如，当topic不为空时跳转到带办详情页
        if (topic){
          //...
        }
        //...
      } catch (error) {
        hilog.error(0x0000, 'testTag', `Failed to parse url.`);
      }
    }
  }
}

（六）验证应用被拉起效果

1. 对应用进行手动签名。说明：不能使用DevEco Studio的自动签名功能，必须使用手动签名，否则无法拉起应用。
2. 编译打包，并安装应用至调试设备。
3. 在拉起方应用中通过App Linking拉起此应用。

八、拉起方应用跳转实现

支持App Linking的应用可以通过如下方式被拉起：

（一）通过openLink接口拉起

拉起方应用通过UIAbilityContext.openLink()接口，传入目标应用的链接，拉起目标应用。openLink接口提供了两种拉起目标应用的方式，开发者可根据业务需求进行选择。

方式一：仅以App Linking的方式打开应用

将appLinkingOnly参数设为true，若有App Linking匹配的应用，则直接打开目标应用。若无App Linking匹配的应用，则抛异常给开发者进行处理。适用于无法打开目标应用时，开发者做了相应的异常处理。例如：拉起方应用集成了ArkWeb，当目标应用不存在时，可通过ArkWeb打开链接。

方式二：以App Linking优先的方式打开应用

将appLinkingOnly参数设为false或者不传，若有App Linking匹配的应用，则直接打开目标应用。若无App Linking匹配的应用，则尝试以浏览器打开链接的方式打开应用。适用于无法打开目标应用时，开发者未做任何处理。此时目标应用不存在时，会通过系统浏览器打开链接。

本文为了方便验证App Linking的配置是否正确，选择方式一，示例如下：

• 在“entry/src/main/ets/common”目录下添加GlobalContext.ets文件，开发初始化和获取应用上下文的接口。

import { common } from '@kit.AbilityKit';
export class GlobalContext {
  private static context: common.UIAbilityContext;
  public static initContext(context: common.UIAbilityContext): void {
    GlobalContext.context = context;
  }

  public static getContext(): common.UIAbilityContext {
    return GlobalContext.context;
  }
}

• 在“entry/src/main/ets/entryability/EntryAbility.ets”文件中导入GlobalContext，在onCreate方法中使用GlobalContext.initContext(this.context)初始化全局应用上下文。
• 在“entry/src/main/ets/pages/Index.ets”文件中，使用UIAbilityContext.openLink()接口打开应用。

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.qingkouwei.com/todo?topic=3dfd3";
        // 仅以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}`);
          })
      })
  }
}

（二）通过系统浏览器或ArkWeb拉起

ArkWeb深度集成了App Linking的能力，当用户在系统浏览器或者集成ArkWeb的应用的网页上点击某个链接时，若有链接匹配的应用，系统则会通过App Linking能力优先拉起目标应用，并在应用内展示相应的内容。此机制有如下限制：

• 如果用户当前浏览的网页的域名与点击的App Linking链接的域名完全一致，则系统会继续在系统浏览器或ArkWeb中打开该链接，以维持连贯的用户浏览体验。
• 如果域名不完全一致（例如example.com和app.example.com），则系统会通过App Linking能力优先拉起目标应用，并在应用内展示相应的内容。

九、App Linking常见问题

1. 应用的module.json5文件skills设置不正确，如何处理？

检查"host"字段中应用所对应的域名是否设置正确。

2. 开发者网站服务器配置不正确，如何处理？

检查服务器的JSON配置，并确保appIdentifier的值正确无误。检查applinking.json是否放置在正确的目录（.well-known）下，通过浏览器等方式访问该json文件的地址：https://your.domain.name/.well-known/applinking.json，确保能正常访问。

3. 系统尚未完成域名校验，如何处理？

按照以下步骤排查：

1. 在设备上安装应用，需等待至少20秒，以确保系统完成域名校验的流程。
2. 系统进行域名校验时，如存在断网、弱网等情况，可能导致域名校验失败，域名校验失败后，系统将在24小时内重新进行域名校验。

4. 如何确认域名校验是否成功？

如需查看应用域名验证结果，请在DevEco Studio中打开终端，并使用以下命令查询验证结果：

hdc shell hidumper -s AppDomainVerifyManager

运行hidumper命令后，即可在控制台上看到success消息。

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

如果看到client-error消息，请按照以下步骤排查：

• 检查消息中的appIdentifier是否与AGC中的APP ID一致。
• 检查在AGC配置的域名发布是否成功。

如果您看到http_unknown消息，请确保设备可以访问网络，并重新安装应用。如果您看到其他消息，请联系技术支持获取帮助。

5. 设备首次启动，若无法通过App Linking拉起系统预装应用，如何处理？

设备首次启动后，系统将在20分钟内尝试对预装应用进行域名校验，若在20分钟内设备一直无法访问网络，则可能导致预装应用域名校验失败。若出现此类问题，请重启手机，或者等待24小时后重试。系统将在下次开机或24小时后对预装应用重新尝试进行域名校验。

6. 访问CDN时发现内容未及时更新，如何处理？

CDN缓存时间为10分钟，耐心等待一段时间后再次访问。

7. 应用和域名的对应关系如何？

应用和域名的关系是多对多的关系：一个应用可以关联多个不同的域名，同样地，一个域名也可以关联多个不同的应用。

8. 如果同一域名关联了多个应用，那么该域名的链接将拉起哪个应用？

开发者可以通过配置applinking.json以关联多个应用。如果每个应用的module.json5的uris字段配置的都是一样的，那么系统将弹出列表框供用户选择要拉起的目标应用。 为了更好的体验，开发者也可以通过链接的path去区分拉起的目标应用，如链接https://www.example.com/path1拉起目标应用1，链接https://www.example.com/path2拉起目标应用2。

9. 配置App Linking应用链接时提示“下载源JSON文件被拒，请确认安全策略是否符合要求”，如何处理？

配置文件需要放在域名服务器的固定目录下：https://domain.name/.well-known/applinking.json

例如：我们的服务器域名为www.qingkouwei.com，则必须将applinking.json文件放在如下位置：https://www.qingkouwei.com/.well-known/applinking.json

十、总结

App Linking 作为 HarmonyOS 6 中面向 API 12 及以上版本的核心跳转能力，通过 “域名校验 + HTTPS 链接关联” 的创新机制，彻底解决了传统跳转方式中存在的安全性不足、依赖应用安装状态、操作繁琐等痛点，为全场景智慧生活提供了高效、无缝的跨应用交互方案。

从实际应用价值来看，其核心优势体现在三方面：一是体验升级，无论目标应用是否安装，用户均可通过扫码、碰一碰、链接点击等方式直达指定内容，操作效率显著提升；二是安全可靠，域名校验环节有效规避了应用仿冒风险，保障开发者与用户的合法权益；三是灵活适配，支持应用与域名的多对多关联，可满足扫码直达、社交分享、广告引流等多样化业务场景。

在开发实践中，需重点把握 “目标方配置 + 拉起方实现” 的核心流程：目标方需完成 AGC 服务开通、域名关联、配置文件部署、应用内参数处理等关键步骤，拉起方则可通过 openLink 接口或系统浏览器 / ArkWeb 实现灵活跳转。同时，针对域名校验、配置生效、多应用关联等常见问题，可参考 FAQ 中的排查方案快速解决。

随着 HarmonyOS 全场景生态的持续完善，App Linking 将成为开发者提升应用触达效率、优化用户体验的重要工具，助力更多创新应用在跨设备、跨场景的交互中实现价值最大化。建议开发者结合自身业务场景，充分利用该能力打造一步直达、安全便捷的应用跳转体验，进一步释放全场景智慧生活的生态潜力。