目录

使用App Linking实现元服务跳转

简介

元服务链接是专为开发者设计的密文URL服务，它可以被用户点击并直达拉起元服务任意页面，实现元服务的点击触达，即点即用。作为开发者，您可以为自己的元服务生成并配置专属的元服务链接，同时设置其有效期，精准把握用户访问的时效与范围，以将用户在时效内引导至元服务任意指定页面。

例如：当用户接收到“手机充值”的元服务链接后，他们可以通过点击该链接直接跳转至相应的元服务页面，实现一步直达的便捷体验。

元服务链接能力目前仅对HarmonyOS 5.0及以上版本的操作系统和HarmonyOS API 12及以上版本的元服务开放。

使用场景

元服务开发指导

[h2]前提条件

[h2]创建元服务链接

  1. 登录AppGallery Connect，点击“我的项目”。
  2. 在项目列表中点击您要创建链接的项目。
  3. 在左侧导航栏中选择“增长 > App Linking”，选择“元服务链接（API>=12适用）”页签，点击“创建”。
    • 元服务开发者仅需关注“元服务链接（API>=12适用）”页签，其他页签为HarmonyOS应用或其他系统适用的配置，无需关注。
    • 如果界面未展示“元服务链接（API>=12适用）”页签，请在右侧的“自定义配置”中勾选。

  4. 创建元服务链接，点击“保存”或者“发布”。

    参数

    说明

    名称

    配置元服务链接的名称。

    链接URL

    配置元服务链接：

    前缀为平台固定域名，开发者不能修改或自定义；

    后缀字符串，默认由AGC自动生成，如需自行定义，应确保该字符串唯一且长度不超过100位。

    链接URL预览

    预览完整的元服务链接，支持复制。

    选择元服务

    选择需要配置链接的元服务的名称。

    （可选）自定义参数

    用于精确定位到元服务指定页面。需要按key=value的键值对形式输入，多个键值对之间以“&”分隔。例如：key1=value1&key2=value2&key3=value3...

    具体请参见使用自定义参数跳转到指定的页面。

    链接有效期

    链接有效期生效时间段需在1~90天范围内；结束时间必须晚于当前时间。

[h2]（可选）使用自定义参数跳转到指定的页面

开发者在创建元服务链接时，可设置自定义参数来精确定位到元服务指定页面。使用场景有如下两种：

开发者跳转到指定页面，可以通过自定义参数，在运行时解析然后跳转到指定页面。跳转子页面实现示例：

[h2]查看元服务链接

  1. 查看元服务链接列表。

    在元服务链接页面的搜索框内，输入链接名称或网址可以进行模糊查询。

  2. 查看元服务链接信息详情。

    点击目标元服务链接“操作”列的“查看”，即可查看元服务链接的基本信息。

[h2]修改草稿态元服务链接

点击“操作”列的“编辑”，进入编辑界面进行内容修改，完成后选择“保存”或者“发布”。

[h2]删除元服务链接

点击“操作”列的“删除”，在弹框中点击“确认”，即可删除元服务链接。

[h2]修改发布态元服务链接

如果您的元服务链接状态为“已生效”，且已经配置了元服务标签，则支持编辑操作。

  1. 点击“操作”列的“编辑”，进入编辑界面。

  2. 修改元服务链接相关内容，完成后不可保存，只支持点击“发布”，发布后立即生效。

拉起方实现跳转开发指导

拉起方应用通过UIAbilityContext.openLink()接口，传入目标元服务链接，从而拉起目标元服务。

openLink接口提供“以App Linking打开元服务”的方式进行目标元服务页跳转，开发者可根据业务需求进行编译。

若有匹配的元服务，则直接打开目标元服务；否则，抛异常给开发者进行处理。

为验证元服务链接的配置是否正确，请参照如下示例代码：

  1. 在“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;
  }
}
  2. 在“entry/src/main/ets/entryability/EntryAbility.ets”文件中导入GlobalContext，在onCreate方法中使用GlobalContext.initContext(this.context)初始化全局应用上下文。
  3. 在“entry/src/main/ets/pages/Index.ets”文件中，使用UIAbilityContext.openLink()接口打开元服务。
    import { common } from '@kit.AbilityKit';
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();
        // link 可替换成开发者自行配置的元服务链接
        let link: string = "https://hoas.drcn.agconnect.link/9P7g";
        context.openLink(link)
          .then(() => {
            console.info('openlink success.');
          })
          .catch((error: BusinessError) => {
            console.error(`openlink failed. error:${JSON.stringify(error)}`);
          });
      })
  }
}

以“手机充值”元服务为例，代码中link为该元服务首页的链接，当拉起方应用成功触发链接，弹窗提示“‘应用名’是否打开元服务”，点击“打开”则成功实现链接跳转元服务功能。

接口openLink还可以设置appLinkingOnly参数：

context.openLink(link, { appLinkingOnly: true })
.then(() => {
  console.info('openlink success.');
})

[h2]报错场景

  1. 元服务链接过期失效后，系统提示报错如下：
    • 当appLinkingOnly参数设为true时：点击链接会跳转失败，抛出openlink failed的错误码"16000019"。
    • 当appLinkingOnly参数设为false或者默认时：会使用浏览器打开链接地址，展示异常错误页面。

  2. 输入链接检测为非元服务链接，如应用链接或无效链接等，系统提示报错如下：
    • 当appLinkingOnly参数设为true时：首先会判别是否为应用链接，如果为应用链接则会跳转至本地预安装的应用服务页面；否则在点击链接时会跳转失败，系统抛出openlink failed的错误码"16000019"。
    • 当appLinkingOnly参数设为false或者默认时：首先会判别是否为应用链接，如果为应用链接，就跳转至本地预安装的应用服务页面；否则尝试浏览器网页打开。