目录

使用元服务链接跳转元服务

简介

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

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

使用场景

约束与限制

从5.0.0(12)版本开始，支持Phone、Tablet设备。

前提条件

接入元服务链接开发指导

[h2]创建元服务链接

  1. 登录HarmonyOS 开发者中心，进入“应用管理”页面。
  2. 选择目标元服务后，左侧导航选择“基础服务 > 元服务链接”，进入“元服务链接”页面，点击“立即使用”。

  3. 点击“元服务链接”首页右上角的“创建”。

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

    参数

    说明

    名称

    配置元服务链接的名称。

    链接URL

    配置元服务链接：

    前缀为平台固定域名，开发者不能修改或自定义；后缀字符串，默认自动生成，如需自行定义，应确保该字符串唯一且长度不超过100位。

    说明：

    后缀字符串只能包含英文字母（a-z、A-Z）、数字（0-9）、下划线“_”和连字符“-”。

    链接URL预览

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

    说明：

    （可选）开发者在使用元服务链接时，支持在链接URL后拼接动态自定义参数，用于精确定位到元服务指定页面。无需进行额外配置，直接拼接?加key=value键值对，多个键值对之间以“&”分隔。

    链接示例：https://hoas.drcn.agconnect.link/9P7g?key1=value1&key2=value2

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

    元服务

    需要配置链接的元服务的名称，支持复制。

    （可选）自定义参数

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

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

    是否关联二维码

    是否将元服务与普通链接二维码进行关联。

    本章节仅介绍如何使用元服务链接进行跳转，请选择“不关联”。

    说明：

    如果希望用户扫描普通链接二维码后跳转到元服务，请选择“关联”并参见使用普通链接二维码跳转元服务。

    链接有效期

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

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

开发者生成元服务链接后，可在链接URL的末尾添加动态自定义参数，从而精确定位到元服务指定页面。

链接示例：https://hoas.drcn.agconnect.link/9P7g?key1=value1&key2=value2

其中，?后为动态参数，由开发者自行拼接，无需在平台进行额外配置。

在通过系统浏览器或ArkWeb拉起元服务的场景中，不支持使用动态自定义参数。

代码示例：在元服务的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://hoas.drcn.agconnect.link/9P7g?action=showall
    let uri = want?.uri;
    if (uri) {
      // 从链接中解析query参数，拿到参数后，开发者可根据自己的业务需求进行后续的处理。
      try {
        let urlObject = url.URL.parseURL(uri);
        let action = urlObject.params.get('action');
        // 例如，当action为showall时，展示所有的节目。
        if (action === "showall"){
          // ...
        }
        // ...
      } catch (error) {
        hilog.error(0x0000, 'testTag', `Failed to parse url.`);
      }
    }
  }
}

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

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

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

[h2]查看元服务链接

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

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

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

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

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

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

[h2]删除元服务链接

仅“草稿态”和“已失效”的元服务链接支持删除，点击“操作”列的“删除”，在弹框中点击“确认”，即可删除元服务链接。

使用元服务链接拉起元服务

[h2]通过openLink接口拉起元服务

拉起方应用通过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 { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
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(() => {
            hilog.info(0x0000, 'testTag', '%{public}s', 'Succeeded in opening the link.');
          })
          .catch((error: BusinessError) => {
            hilog.error(0x0000, 'testTag', `Failed to open link, code: ${error.code}, message: ${error.message}`);
          })
      })
  }
}

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

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

context.openLink(link, { appLinkingOnly: true })
.then(() => {
  hilog.info(0x0000, 'testTag', '%{public}s', 'Succeeded in opening the link.');
})

[h2]通过系统浏览器或ArkWeb拉起元服务

ArkWeb深度集成了App Linking的能力，当用户在系统浏览器或者集成ArkWeb的元服务网页上点击某个链接时，若有链接匹配的元服务，系统会通过App Linking能力跳转至该元服务档案页，引导用户点击【打开元服务】，从而拉起目标元服务。

该场景不支持使用动态自定义参数。

[h2]报错场景

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

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