【HarmonyOS】【进阶】鸿蒙原生实现应用间跳转之App Linking 原创

开发语言：ArkTs
开发工具：DevEco Studio 5.0.0 Release
API版本：API 12

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

本文演示A应用（拉起方）拉起B应用（被拉起方）。

B应用（被拉起方）开发

一、后端/云端开发：

1. 在AppGallery Connect开通App Linking服务。

① 登录AppGallery Connect，点击“我的项目”。
② 在项目列表中点击您的项目。
③ 在左侧导航栏中选择“增长 > App Linking”，进入App Linking页面，点击“立即开通”。

④ 如果您的项目此时未设置数据处理位置，请在提示框内启用数据处理位置和设置默认数据处理位置，点击“确定”。

⑤ 进入“项目设置 > 常规”页面，选择创建的HarmonyOS应用，查看应用的APP ID，后续开发需要使用该ID。

2. 在开发者网站上关联应用。

在开发者的网站域名服务器上做如下配置。后续当您配置该网站域名时，系统会通过此文件确认哪些应用才是合法归属于此域名的，使链接更加安全可靠。
① 创建域名配置文件applinking.json，内容如下：

1、appIdentifier填写创建应用时生成的APP ID。
2、同一个网站域名可以关联多个应用，只需要在apps列表里放置多个appIdentifier元素即可，其中每个appIdentifier元素对应每个应用。

{
 "applinking": {
   "apps": [
     {
       "appIdentifier": "5765880207854042357"
     }
   ]
 }
}

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

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

3. 在AppGallery Connect关联网址域名。

基于HarmonyOS应用链接能力，需要为HarmonyOS应用创建关联的网址域名。如果用户已安装HarmonyOS应用，则用户点击域名下网址链接后，系统会默认打开该HarmonyOS应用内的相关页面。
① 登录AppGallery Connect，点击“我的项目”。
② 在项目列表中点击您的项目。
③ 在左侧导航栏中选择“增长 > App Linking”，选择“应用链接（API>=12适用）”页签，点击“创建”。

④ 填写HarmonyOS应用关联的网址域名，即创建域名配置文件的网址，例如：https://www.blink.com。必须输入精确的域名，不可输入包含特殊字符的模糊网址。

不可以在域名后面添加/，即不支持https://www.example.com/形式。

⑤ 设置完成后点击“发布”，AGC会对该网站域名的配置文件所包含的应用与本项目内的应用列表进行交集校验。

二、客户端开发：

1. 在DevEco Studio中配置关联的网址域名。

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

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

{
  "module": {
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ts",
        "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": [
              "action.system.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.blink.com",
                // path可选，表示域名服务器上的目录或文件路径，例如www.blink.com/path1/中的path1
                // 如果应用只能处理部分特定的path，则此处应该配置应用所支持的path，避免出现应用不能处理的path链接也被引流到应用中的问题
                "path": "path1"
              }
            ],
            // domainVerify须设置为true
           "domainVerify": true
          }
          // 若有其他跳转能力，如推送消息跳转、NFC跳转，可新增一个skill对象，防止与App Linking业务冲突
        ]
      }
    ]
  }
}

2. 处理传入的链接。

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

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 {
    // 从want中获取传入的链接信息。
    // 如传入的url为：https://www.blink.com/open?action=scan
    let uri = want?.uri 
    if (uri) {
      // 从链接中解析query参数，拿到参数后，开发者可根据自己的业务需求进行后续的处理。
      let urlObject = url.URL.parseURL(want?.uri);
      let action = urlObject.params.get('action')
      // 例如，当action为scan时，打开扫一扫。
      if (action === "scan"){
         //...
      }
    }
  }

  // 热启动
  onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // 从want中获取传入的链接信息。
    // 如传入的url为：https://www.blink.com/open?action=scan
    let uri = want?.uri 
    if (uri) {
      // 从链接中解析query参数，拿到参数后，开发者可根据自己的业务需求进行后续的处理。
      let urlObject = url.URL.parseURL(want?.uri);
      let action = urlObject.params.get('action')
      // 例如，当action为scan时，打开扫一扫。
      if (action === "scan"){
         //...
      }
    }
  }
}

三、前端开发

开发链接对应的H5网页，应用未安装时呈现网页版内容。

A应用（拉起方）开发

一、客户端开发

1、判断B应用（被拉起方）是否安装

① 在entry模块的module.json5文件中配置querySchemes属性，声明想要查询的URL scheme。

{
  "module": {
    //...
    "querySchemes": [
      "blink"
    ]
  }
}

② 调用bundleManager.canOpenLink()接口。

let canOpen = bundleManager.canOpenLink(link);

2. 通过openLink接口拉起。

可根据业务需求选择合适的方式。

方式一： 仅以App Linking的方式打开应用。
将appLinkingOnly参数设为true，若有匹配的应用，则直接打开目标应用。若无App Linking匹配的应用，则抛异常给开发者进行处理。

方式二： 以App Linking优先的方式打开应用。
将appLinkingOnly参数设为false或者默认，则为App Linking优先的方式打开应用。若有App Linking匹配的应用，则直接打开目标应用。若无App Linking匹配的应用，则尝试以浏览器打开链接的方式打开应用。

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

@Entry
@Component
struct Index {
  build() {
    Button('start link', { type: ButtonType.Capsule, stateEffect: true })
      .width('87%')
      .height('5%')
      .margin({ bottom: '12vp' })
      .onClick(() => {
        let context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
        let link: string = "https://www.blink.com/open?action=scan";
        // 仅以App Linking的方式打开应用
        context.openLink(link, { appLinkingOnly: true })
          .then(() => {
            console.info('openlink success.');
          })
          .catch((error: BusinessError) => {
            console.error(`openlink failed. error:${JSON.stringify(error)}`);
          });
      })
  }
}

3. 通过系统浏览器或ArkWeb拉起。

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

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

验证应用被拉起效果

• 对应用进行手动签名。
• 编译打包，并安装应用至调试设备。
• 在A应用（拉起方）应用中通过App Linking拉起此应用，详细请参考“拉起方实现跳转指导”。
• 查看集成效果。

不能使用DevEco Studio的自动签名功能，必须使用手动签名，否则无法拉起应用。