使用App Linking实现应用间跳转-拉起指定应用-应用间跳转-Stage模型开发指导-Ability Kit（程序框架服务）-应用框架

简介

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

例如：当开发者使用App Linking接入“扫码直达”服务后，用户可通过控制中心扫一扫等系统级扫码入口，扫描应用的二维码、条形码并跳转到开发者应用对应服务页，实现一步直达的体验。

说明

该能力目前仅适用于API 12及以上版本的HarmonyOS应用，如果您开发的是元服务，请参考使用App Linking实现元服务跳转。

适用场景

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

实现原理

App Linking在Deep Linking基础上增加了域名校验环节，通过域名校验，可帮助用户消除歧义，识别合法归属于域名的应用，使链接更加安全可靠。
App Linking要求对于同一HTTPS网址，有应用和网页两种内容的呈现方式。当应用安装时则优先打开应用去呈现内容；当应用未安装时，则打开浏览器呈现Web版的内容。

开发指导概述

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

各个角色的分工如下。

目标方

展开

序号	⾓⾊	职责
1	云端开发	在AGC控制台开通App Linking服务。
2	云端开发	在开发者网站上关联应用。
3	云端开发	在AGC控制台关联网址域名。
4	客户端开发	在DevEco Studio中配置关联的网址域名。
5	客户端开发	处理传入的链接。
6	前端开发	开发链接对应的H5网页，应用未安装时呈现网页版内容。说明本指南侧重于HarmonyOS应用相关的开发指导，网页的开发不在本指导范围内，开发者请依据自己的业务需求自行实现。

拉起方
展开
序号

⾓⾊

职责

1

客户端开发

调用系统接口，触发链接跳转。

序号	⾓⾊	职责
1	客户端开发	调用系统接口，触发链接跳转。

目标方应用开发指导

在AGC控制台开通App Linking服务

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

登录AppGallery Connect，点击“我的项目”。
在项目列表中点击您的项目。
在左侧导航栏中选择“增长 > App Linking”，进入App Linking页面，点击“立即开通”。
如果您的项目此时未设置数据处理位置，请在提示框内启用数据处理位置和设置默认数据处理位置，点击“确定”。
进入“项目设置 > 常规”页面，选择创建的HarmonyOS应用，查看应用的APP ID，后续开发需要使用该ID。

在开发者网站上关联应用

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

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

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

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

在AGC控制台关联网址域名

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

登录AppGallery Connect，点击“我的项目”。
在项目列表中点击您的项目。
在左侧导航栏中选择“增长 > App Linking”，选择“应用链接（API>=12适用）”页签，点击“创建”。
说明
- HarmonyOS应用开发者仅需关注“应用链接（API>=12适用）”页签，其他页签为元服务或其他系统适用的配置，无需关注。
- 如果界面未展示“应用链接（API>=12适用）”页签，请在右侧的“自定义配置”中勾选。
填写HarmonyOS应用关联的网址域名，即创建域名配置文件的网址，例如：https://www.example.com。必须输入精确的域名，不可输入包含特殊字符的模糊网址。
说明
不可以在域名后面添加/，即不支持“https://www.example.com/”形式。
设置完成后点击“发布”，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标签说明”。
"domainVerify"设置为true，表示开启域名校验开关。

说明

skills标签下默认包含一个skill对象，用于标识应用入口。应用跳转链接不能在该skill对象中配置，需要创建独立的skill对象。

如果存在多个跳转场景，需要在skills标签下创建不同的skill对象，否则会导致配置无法生效。

例如，声明应用关联的域名是www.example.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": [
              "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.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的指定页面”。

验证应用被拉起效果

对应用进行手动签名。
说明
不能使用DevEco Studio的自动签名功能，必须使用手动签名，否则无法拉起应用。
编译打包，并安装应用至调试设备。
在拉起方应用中通过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的配置是否正确，选择方式一，示例如下。
```
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.example.com/programs?action=showall";
        // 仅以App Linking的方式打开应用
        context.openLink(link, { appLinkingOnly: true })
          .then(() => {
            console.info('openlink success.');
          })
          .catch((error: BusinessError) => {
            console.error(`openlink failed. error:${JSON.stringify(error)}`);
          });
      })
  }
}
```
在拉起方应用中执行上述代码，如果拉起方应用成功拉起目标应用，则成功配置App Linking。
通过系统浏览器或ArkWeb拉起。
ArkWeb深度集成了App Linking的能力，当用户在系统浏览器或者集成ArkWeb的应用的网页上点击某个链接时，若有链接匹配的应用，系统则会通过App Linking能力优先拉起目标应用，并在应用内展示相应的内容。此机制有如下限制：
1. 如果用户当前浏览的网页的域名与点击的App Linking链接的域名完全一致，则系统会继续在系统浏览器或ArkWeb中打开该链接，以维持连贯的用户浏览体验。
2. 如果域名不完全一致（例如example.com和app.example.com），则系统会通过App Linking能力优先拉起目标应用，并在应用内展示相应的内容。

FAQ

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

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

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

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

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

按照以下步骤排查：

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

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

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

hdc shell hidumper -s AppDomainVerifyManager

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

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

如果您看到client-error消息，请按照以下步骤排查：
1. 检查消息中的appIdentifier是否与AGC控制台的appid一致。
2. 检查AGC控制台配置的域名发布是否成功。
如果您看到http_unknown消息，请确保设备可以访问网络，并重新安装应用。
如果您看到其他消息，请联系技术支持获取帮助。

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

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

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

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

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

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

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

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