21、鸿蒙学习——使用App Linking实现应用间跳转

发布于：2025-07-05 ⋅ 阅读:(16) ⋅ 点赞:(0)

简介

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


实现原理

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

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

目标方应用开发指导

1、登录AppGallery Connect，点击“我的项目”。

2、选择「开发与服务」

3、在左侧导航栏中选择“增长->App Linking”，进入App Linking页面，点击“立即开通”。

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

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


 

在开发者网站上关联应用

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

1、创建域名配置文件applinking.json，内容如下：
 

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

说明：

  • appIdentifier填写在AGC控制台开通App Linking服务的步骤5展示的APP ID
  • 同一个网站域名可以关联多个应用，只需要在“apps”列表里放置多个“appIdentifier”元素即可，其中每个“appIdentifier”元素对应每个应用

2、将配置文件放在域名服务器固定的目录下：

https://domain.name/.well-known/applinking.json

例如：开发者的服务器域名为www.example.com，则必须将applinking.json文件放在如下位置：

https://www.example.com/.well-known/applinking.json


在AGC控制台关联网址域名

1、在左侧导航栏中选择”增长->App Linking",选择“应用链接（API>=12适用）”页签，点击“创建”

说明：

  • Harmony OS应用开发者仅需关注“应用链接（API>=12）”页签，其他页签为元服务或其他系统适用的配置，无需关注
  • 如果界面未展示“应用链接 （API>=12）”页签，请在右侧的“自定义配置”中勾选

2、填写在开发者网站上关联应用的网址域名，例如：https://www.baidu.com。必须输入精确的域名，不可输入包含特殊字符的模糊网址。

说明：
不可以在域名后面加/，即不支持“https://www.example.com/”形式


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

说明：应用链接发布完成后，如果距离上次更新超过24小时，系统会取域名服务器上重新获取配置文件进行校验。
例如：在4月7日17:21创建了应用链接，系统会在4月8日17:30去域名服务器上重新获取配置文件，然后进行交集校验，更新发布状态

如果域名的配置文件中有应用存在本项目中，则发布成功，点击“查看”可显示该域名关联的应用信息。

  • 如果异步校验中，则状态为“发布中”。
  • 如果配置文件中没有任何应用在本项目中，则发布失败，点击“查看”可显示发布失败的原因。

在DevEco Studio中配置关联的网站域名

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

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

说明：skills标签下默认包含一个skill对象，用于标识应用入口。应用跳转链接不能在该skill对象中配置，需要创建独立的skill对象，否则会导致配置无法生效。

例如，声明应用关联的域名是www.baidu.com，则需进行如下配置。

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

处理传入的链接

在应用的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.example.com/programs?action=showall
    let uri = want?.uri 
    if (uri) {
      // 从链接中解析query参数，拿到参数后，开发者可根据自己的业务需求进行后续的处理。
      let urlObject = url.URL.parseURL(want?.uri);
      let action = urlObject.params.get('action')
      // 例如，当action为showall时，展示所有的节目。
      if (action === "showall"){
         //...
      }
      //...
    }
  }
}

若要根据链接参数启动UIAbility的指定页面组件，请参考“启动UIAbility的指定页面”。
 

拉起方实现跳转指导

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

1、通过openLink接口拉起。

拉起方应用通过UIAbilityContext.openLink()接口，传入目标应用的链接，拉起目标应用。

openLink接口提供了两种拉起目标应用的方式，开发者可根据业务需求进行选择。

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

将appLinkingOnly参数设置为true，若有App Linking匹配的应用，则直接打开应用。若无App Linking匹配的应用，则抛异常该开发者进行处理。

适用于无法打开目标应用时，开发者做了相应的异常处理。例如：拉起方应用集成了ArkWeb，当目标应用不存在时，可通过ArkWeb打开链接。

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

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

适用于无法打开目标应用时，开发者未做任何处理。此时目标应用不存在时，会通过系统浏览器打开链接。

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.example.com/programs?action=showall";
        // 仅以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}`);
          });
      })
  }
}

2、通过系统浏览器或ArkWeb拉起

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

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

参考：文档中心 

网站公告

今日签到

点亮在社区的每一天
去签到

热门文章

最新发布