【鸿蒙开发】第二十四章 AI -Intents Kit（意图框架服务）

目录

1 简介

1.1 Intents Kit优势

1.2 智慧分发

1.3 意图的运行逻辑

 2. Intents Kit接入流程

 3 习惯推荐方案

3.1 概述

3.2 场景体验

3.2.1 典型场景

3.2.2 卡片展示效果

3.3  接入方案

3.3.1 方案概述

3.3.2 意图注册

3.3.3 端侧意图共享

3.3.4 端侧意图调用

3.3.4.1 意图执行组件为uiAbility的意图调用

3.3.4.2 意图执行组件为form的意图调用

3.4 开发者测试

3.4.1 基础信息提供

3.4.2 环境准备

3.4.3 联调验证

3.4.4 端云结合的习惯推荐

4 事件推荐方案

4.1 概述

4.2 场景体验

4.2.1典型场景

4.3 接入方案

4.3.1 方案概述

4.3.2 流程图

4.3.3 意图注册

4.3.4 获取SID

4.3.5 云侧意图共享

4.3.5.1 服务上架配置

4.3.5.2 意图共享接口调用

4.3.5.3 事件撤销接口调用

4.3.4 端侧意图调用

4.4 开发者测试

4.4.1 基础信息提供

4.4.2 环境准备

4.4.3 联调验证

5 技能调用方案

5.1 概述

5.2 场景体验

5.2.1 典型场景

功能服务类

信息交互类

5.3 接入方案

5.3.1 方案概述

5.3.1.1 端侧意图注册

5.3.2 端侧前台意图调用

5.3.3 端侧前台窗口意图调用

6 本地搜索方案

6.1 概述

6.2 场景体验

6.2.1 典型场景

6.2.2 卡片展示效果

6.3 接入方案

6.3.1 方案概述

6.3.2 意图注册

6.3.3 端侧意图共享

6.3.4 端侧意图调用

7 意图框架上架配置指导

---

1 简介

Intents Kit（意图框架服务）是HarmonyOS级的意图标准体系 ，意图连接了应用/元服务内的业务功能。

意图框架能帮开发者将应用/元服务内的业务功能，智能分发到各系统入口，这个过程即智慧分发。其中系统入口包括：小艺对话、小艺搜索、小艺建议。

系统入口、意图框架、鸿蒙生态的关系如下：

1.1 Intents Kit优势

利用HarmonyOS的大模型、多维设备感知等AI能力，准确且及时地获取到用户显性、潜在意图，从而实现个性化、多模态、精准的智慧分发。

1.2 智慧分发

为方便开发者接入，智慧分发提供了多种特性类别，当前已开放习惯推荐、事件推荐、技能调用-语音、本地搜索，后续会陆续开放其他特性类别。每种特性类型支持的典型系统入口、分发逻辑见下表：

特性类型	系统入口	分发逻辑
习惯推荐	小艺建议	应用或元服务向系统共享意图，系统学习意图规律，在合适的时机推荐服务。比如向系统共享用户浏览资讯意图的数据，经过习惯规律性学习后，小艺建议会合适的时机给用户推荐合适的浏览资讯服务与内容。
事件推荐	小艺建议	应用或元服务向系统共享意图，系统提取意图内容中的事件，结合时间、位置等信息向用户推荐提醒服务。比如向系统共享用户购买的电影票订单数据，由系统提取订单数据中的关键特征如时间、位置等，小艺建议会在合适的时机给用户推荐观影提醒服务。
技能调用-语音	小艺对话	系统基于AI大模型对理解用户显示或隐性的输入，帮用户完成应用或元服务的功能调用。比如用户在小艺对话中询问“从深圳去北京的飞机要多少钱”，可以理解用户搜索机票的意图，调用应用或元服务提供的搜索机票意图获取机票数据并向用户呈现。
本地搜索	小艺搜索	应用或元服务向系统共享意图，系统对意图的实体内容构建本地索引，满足用户搜索的需求。比如向系统共享“华为开发者大会”相关报道资讯后，用户在该入口输入相关关键词，即可将应用或元服务内的资讯内容检索出来。

为了满足更细粒度的分发诉求，每类特性类别下提供多个具体特性，具体特性的分发系统入口、开发依赖见各垂域智慧分发特性列表。具体特性开发依赖的意图相关字段见各垂域意图Schema。

1.3 意图的运行逻辑

HarmonyOS、应用/元服务的交互中，意图运行方式分为意图调用和意图共享：

“意图”运行方式	发起者	定义
意图共享	应用/元服务	指应用/元服务主动向HarmonyOS共享意图，可用于HarmonyOS构建本地内容索引、学习用户的行为规律，以支持本地搜索和主动建议。 意图共享包含动作和实体两个部分，动作支持完成时和将来时两种机制。 完成时：用户意图已执行，共享的数据可用于本地搜索和系统建议。 将来时：意图是基于用户行为预测的，共享的数据可用于本地搜索。 意图框架还支持开发者向系统进行辅助实体共享，例如位置信息等，用于场景推荐和其他智慧分发功能的增强。
意图调用	HarmonyOS	指HarmonyOS主动调用应用/元服务的功能。 用户在系统入口输入信息或者系统主动推荐后，系统可向应用/元服务发起意图调用，例如播放音乐、查看旅游攻略、搜索视频等。

 2. Intents Kit接入流程

阶段	任务	任务描述	示例	指导文档
意向	选择特性确定意图	开发者在已发布的特性列表中根据想达成的用户体验选择特性，根据特性来确定需实现的意图。	开发者想实现“歌曲续听推荐”的特性，则根据智慧分发特性描述，需要实现“播放歌曲”意图。	歌曲续听推荐
开发	调试白名单申请	确定开发意向后，开发者发送邮件到邮箱（hagservice@huawei.com）或者联系华为意图框架接口同事，向华为提供测试应用的信息，用于申请调试白名单。	1. 应用名称：华为音乐。 2. AppID：1234567。 3. 申请接入意图：“播放歌曲”。 4. 调试设备ID：1234567。 ......	见各特性类型“开发者测试”方案
	端侧意图调用调试工具申请	华为可提供调试工具，用于开发者自验证端侧意图调用。若需申请工具使用，请开发者联系华为意图框架接口同事，向华为提供接收调试工具的公司人员信息。	1.公司全称：xxx技术有限公司 2.接收人姓名：张三 3.接收人邮箱：zhangsan@xxx.com	见各特性类型“开发者测试”方案
	意图声明文件中注册意图	在DevEco Studio中开发时，注册对应的意图。	注册“播放歌曲”意图。	意图注册
	开发实现意图调用/意图共享	开发应用/元服务的意图共享接口，使其可以通过HarmonyOS接口完成意图数据共享。	开发“播放歌曲”意图中的意图共享接口。	端侧意图共享
		开发应用/元服务的意图调用接口，使其可以通过HarmonyOS接口被正确调用。	开发“播放歌曲”意图中的意图调用接口。	端侧意图调用
验证	端到端验证特性	使用华为侧提供的测试能力完成目标特性的端到端联调测试，联调测试完成后，提交智慧分发配置至审核。	在设备上对应入口进行“华为音乐-歌曲续听推荐”的特性端到端测试，测试完成后点击提交智慧分发配置。	-
上架	应用市场上架软件包（应用/元服务）	开发完成并打包好软件包后，在应用市场上传软件包。	打包“华为音乐”软件包并通过应用市场上架。	应用市场上架流程
	意图框架注册	在小艺开放平台进行意图注册配置并提交审核。由华为工程师审核，一般情况在3个工作日内完成。	注册“播放歌曲”意图。	意图框架上架配置指导

 3 习惯推荐方案

3.1 概述

习惯推荐是HarmonyOS学习用户的行为习惯后做出的主动预测推荐。

1. 开发者将用户在应用/元服务内的使用行为向HarmonyOS共享，使得HarmonyOS可以基于共享的数据学习用户的行为习惯。
2. 在HarmonyOS学习到用户的行为习惯后，会给用户推荐相应功能，并且尝试补充详细功能参数，减少用户执行任务的步骤。

以听音乐为例，意图框架设计了统一的意图——播放歌单意图，该意图可以让应用/元服务与HarmonyOS交互。

当用户使用应用/元服务播放歌单时，应用/元服务可以向Intents Kit共享该意图，并提供一些用于学习的特征，例如播放开始/结束时间、播放时长、歌单名等。HarmonyOS会结合底层采集的时间、空间、设备状态等数据共同理解用户行为上下文。最后HarmonyOS结合应用/元服务历史上共享过的数据重建响应意图任务并进行预测推荐，例如在用户每天早上上车后，为其推荐“每日推荐”歌单卡片，用户点击实现一键播放。

3.2 场景体验

3.2.1 典型场景

当前习惯推荐可在小艺建议入口分发，在不同垂域中，填充功能详细参数或内容的逻辑不同，主要典型场景可分为常用接续、常用复访、常用推新三类。

以常看视频续播为例，系统预测当前用户使用华为视频的播放视频功能概率较高，会选择用户最近观看且还没看完的视频内容来补充功能细节，在小艺建议中以模板卡形式推荐展示，用户点击卡片后，实现一步跳转进应用的视频播放页。

3.2.2 卡片展示效果

意图框架提供各垂域习惯推荐在小艺建议中展示使用的标准模板卡片，开发者无需开发展示卡片。在展示模板上，会展示应用/元服务名称与logo和内容必要信息，比如音乐名、音乐图片，这类参数需要开发者共享到系统。

以下为播放歌曲-习惯推荐的卡片示例。

3.3  接入方案

3.3.1 方案概述

当用户在应用/元服务内使用功能时，开发者需要按照标准意图Schema向系统共享行为数据，并支持意图调用（空调用与传参调用），以实现用户点击模板卡后跳转回对应页面。

3.3.2 意图注册

以歌曲续听推荐特性为例，首先要注册播放歌曲意图（PlayMusic），其他意图见各垂域意图Schema。开发者需要编辑对应的意图配置 PROJECT_HOME/entry/src/main/resources/base/profile/insight_intent.json文件，实现意图注册。

{
  // 应用支持的意图列表
  // 必须声明应用支持插件包含的必选意图，应用上架时会进行校验
  "insightIntents": [
    {
      // 意图名称
      // 名称应当遵循意图框架规范，当前仅支持预置垂域意图，不允许自定义
      // 应用内意图名称唯一，不允许出现相同的名称定义
      "intentName": "PlayMusic",
      // 意图所属的垂域
      "domain": "MusicDomain",
      // 意图版本号
      // 插件引用意图时会校验该版本号，只有和插件定义的版本号一致才能正常调用
      "intentVersion": "1.0.1",
      // 意图调用逻辑入口
      "srcEntry": "./ets/entryability/InsightIntentExecutorImpl.ets",
      "uiAbility": {
        // 意图所在module、ability，以及代码相对路径入口
        "ability": "EntryAbility",
        // UIAbility支持前后台两种执行模式
        "executeMode": [
          "background",
          "foreground"
        ]
      }
    }
  ]
}

3.3.3 端侧意图共享

构建意图对象，并且调用shareIntent()，实现意图共享。可同时构建多个PlayMusic或PlayMusicList的意图对象。

import { insightIntent } from '@kit.IntentsKit';
import { BusinessError } from '@kit.BasicServicesKit';

let playMusicIntent1: insightIntent.InsightIntent;
let playMusicIntent2: insightIntent.InsightIntent;
// 共享数据接口  意图数组可以是更多的实体
// 根据实际代码上下文自行传入合适的context
insightIntent.shareIntent(context, [playMusicIntent1, playMusicIntent2]).then(() => {
  console.info('shareIntent succeed');
}).catch((err: BusinessError) => {
  console.error(`error.code: ${err?.code}, failed because ${err?.message}`);
});

PlayMusic的意图共享字段定义见各垂域意图Schema定义，代码示例如下：

import { insightIntent } from '@kit.IntentsKit';

let playMusicIntent: insightIntent.InsightIntent = {
  intentName: "PlayMusic",
  intentVersion: "1.0",
  identifier: "52dac3b0-6520-4974-81e5-25f0879449b5",
  intentActionInfo: {
    actionMode: "EXECUTED",
    executedTimeSlots: {
      executedStartTime: 1637393212000,
      executedEndTime: 1637393112000,
    },
    currentPercentage: 50,
  },
  intentEntityInfo: {
    entityName: "Music",
    entityId: "C10194368",
    entityGroupId: "C10194321312",
    displayName: "测试歌曲1",
    description: "NA",
    logoURL: "https://www-file.abc.com/-/media/corporate/images/home/logo/abc_logo.png",
    keywords: ["华为音乐", "化妆"],
    rankingHint: 99,
    expirationTime: 1637393212000,
    metadataModificationTime: 1637393212000,
    activityType: ["1", "2", "3"],
    artist: ["测试歌手1", "测试歌手2"],
    lyricist: ["测试词作者1", "测试词作者2"],
    composer: ["测试曲作者1", "测试曲作者2"],
    albumName: "测试专辑",
    duration: 244000,
    playCount: 100000,
    musicalGenre: ["流行", "华语", "金曲", "00后"],
    isPublicData: false,
  }
}

完整的意图共享示例如下所示，该示例构建了一个PlayMusic意图，并进行了shareIntent调用。

import { insightIntent } from '@kit.IntentsKit';
import { BusinessError } from '@kit.BasicServicesKit';

let playMusicIntent: insightIntent.InsightIntent = {
  intentName: "PlayMusic",
  intentVersion: "1.0",
  identifier: "52dac3b0-6520-4974-81e5-25f0879449b5",
  intentActionInfo: {
    actionMode: "EXECUTED",
    executedTimeSlots: {
      executedStartTime: 1637393212000,
      executedEndTime: 1637393112000,
    },
    currentPercentage: 50,
  },
  intentEntityInfo: {
    entityName: "Music",
    entityId: "C10194368",
    entityGroupId: "C10194321312",
    displayName: "测试歌曲1",
    description: "NA",
    logoURL: "https://www-file.abc.com/-/media/corporate/images/home/logo/abc_logo.png",
    keywords: ["华为音乐", "化妆"],
    rankingHint: 99,
    expirationTime: 1637393212000,
    metadataModificationTime: 1637393212000,
    activityType: ["1", "2", "3"],
    artist: ["测试歌手1", "测试歌手2"],
    lyricist: ["测试词作者1", "测试词作者2"],
    composer: ["测试曲作者1", "测试曲作者2"],
    albumName: "测试专辑",
    duration: 244000,
    playCount: 100000,
    musicalGenre: ["流行", "华语", "金曲", "00后"],
    isPublicData: false,
  }
}
// 共享数据接口  意图数组可以是更多的实体
// 根据实际代码上下文自行传入合适的context
insightIntent.shareIntent(context, [playMusicIntent]).then(() => {
  console.info('shareIntent succeed');
}).catch((err: BusinessError) => {
  console.error(`error.code: ${err?.code}, failed because ${err?.message}`);
});

3.3.4 端侧意图调用

3.3.4.1 意图执行组件为uiAbility的意图调用

如上文意图注册，当开发者注册的意图承载的运行组件为uiAbility时，开发者需要自己实现InsightIntentExecutor，并在对应回调实现打开落地页（点击推荐卡片跳转的界面）的能力，PlayMusic的意图调用字段定义见各垂域意图Schema。

步骤如下：

1. 继承InsightIntentExecutor。
2. 重写对应方法，例如目标拉起前台页面，则可重写onExecuteInUIAbilityForegroundMode方法。
3. 通过意图名称，识别播放歌曲意图（PlayMusic），在对应的方法中传递意图参数（param），并拉起对应落地页（如歌曲落地页）。

import { insightIntent, InsightIntentExecutor } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

/**
 * 意图调用样例
 */
export default class InsightIntentExecutorImpl extends InsightIntentExecutor {
  private static readonly PLAY_MUSIC = 'PlayMusic';
  /**
   * override 执行前台UIAbility意图
   *
   * @param name 意图名称
   * @param param 意图参数
   * @param pageLoader 窗口
   * @returns 意图调用结果
   */
  onExecuteInUIAbilityForegroundMode(name: string, param: Record<string, Object>, pageLoader: window.WindowStage):
    Promise<insightIntent.ExecuteResult> {
    // 根据意图名称分发处理逻辑
    switch (name) {
      case InsightIntentExecutorImpl.PLAY_MUSIC:
        return this.playMusic(param, pageLoader);
      default:
        break;
    }
    return Promise.resolve({
      code: -1,
      result: {
        message: 'unknown intent'
      }
    } as insightIntent.ExecuteResult)
  }
  /**
   * 实现调用播放歌曲功能
   *
   * @param param 意图参数
   * @param pageLoader 窗口
   */
  private playMusic(param: Record<string, Object>, pageLoader: window.WindowStage): Promise<insightIntent.ExecuteResult> {
    return new Promise((resolve, reject) => {
      let para: Record<string, string> = {
        'result': JSON.stringify(param)
      };
      let localStorage: LocalStorage = new LocalStorage(para);
      // TODO 实现意图调用，loadContent的入参为歌曲落地页路径，例如：pages/Index
      pageLoader.loadContent('pages/Index', localStorage)
        .then(() => {
          let entityId: string = (param.items as Array<object>)?.[0]?.['entityId'];
          // TODO 调用成功的情况，此处可以打印日志
          resolve({
            code: 0,
            result: {
              message: 'Intent execute succeed'
            }
          });
        })
        .catch((err: BusinessError) => {
          // TODO 调用失败的情况
          resolve({
            code: -1,
            result: {
              message: 'Intent execute failed'
            }
          })
        });
    })
  }
}

3.3.4.2 意图执行组件为form的意图调用

如上文意图注册，当开发者注册的意图承载的运行组件为form（运行组件FormExtensionAbility）时，则需要开发者在实现的FormExtensionAbility中从want中获取并解析意图名和执行参数，用于卡片展示。

步骤如下：

1. 在意图执行绑定FormExtensionAbility的onAddForm(want: Want)中获取运行态意图框架传入的意图名（预定义keyName为ohos.insightIntent.executeParam.name）和意图执行参数（预定义keyName为ohos.insightIntent.executeParam.param）；
2. 通过意图名称，识别播放歌曲意图(PlayMusic)，在对应的方法中传递意图参数（param），并加载对应数据用于卡片展示。

import { Want } from '@kit.AbilityKit';
import { formBindingData, FormExtensionAbility } from '@kit.FormKit';

/**
 * 卡片意图调用示例
 */
export default class LoadCardFormAbility extends FormExtensionAbility {
  onAddForm(want: Want): formBindingData.FormBindingData {
    if (want?.parameters?.['ohos.insightIntent.executeParam.name'] != undefined) {
      const intentName = want.parameters['ohos.insightIntent.executeParam.name']; //意图名
      //TODO: 根据意图名称分发处理逻辑，若仅一个卡片意图，则可以忽略
    }

    if (want?.parameters?.['ohos.insightIntent.executeParam.param'] != undefined) {
      const executeParameter = want.parameters['ohos.insightIntent.executeParam.param']; //意图执行参数
      //TODO: 从 executeParameter 中解析具体意图执行参数，用于卡片内容展示
    }

    let formData = ''; //TODO: 仅示例，根据具体逻辑封装
    return formBindingData.createFormBindingData(formData);
  }
}

3.4 开发者测试

意图框架向开发者提供真机测试能力，即开发者可连接设备进行调测。开发者完成代码开发之后，功能正式上架应用市场前，可以在HarmonyOS NEXT设备上面进行自验证，打磨体验。真机测试分为三个步骤：基础信息提供，环境准备，联调验证。

3.4.1 基础信息提供

达成开发意向后，开发者发送邮件到邮箱（hagservice@huawei.com）或者联系华为意图框架接口同事，向华为提供测试应用的信息。

序号	基础信息	描述
1	应用名称	应用市场上架的应用名称。
2	应用包名	应用市场上架的应用包名。
3	接入意图名称	开发者意向接入的意图名称（中英文）。
4	应用图标	应用的图标，具体要求如下： 图标背景：非透明。 比例&尺寸：1:1，72px*72px。 大小：不超过1M。 格式：png、jpg、jpeg。
5	APP ID	登录华为开发者联盟，在“我的项目 > 项目设置 > 常规 > 应用-APP ID”中获取。
6	Client ID	登录华为开发者联盟，在“我的项目 > 项目设置 > 常规 > 应用 > OAuth 2.0客户端ID(凭据) > Client ID”中获取。
7	华为账号（UID）	开发者用于调试的华为账号；登录华为开发者联盟，在“我的项目 > 项目设置 > 常规 > 开发者 > developer ID"中获取。
8	设备ID	开发者用于调试的设备ID；开启设备的意图框架测试开关(测试设备路径：设置 -> 系统 -> 开发者选项 -> 意图框架调试)，界面展示的意图框架测试ID。

3.4.2 环境准备

准备一台装有HarmonyOS Next版本的手机设备，系统版本最低要求为 Developer Beta 3。需要按照以下顺序依次执行，不能更换执行顺序。

1.  保持设备联网，并且设备时间和实际北京时间保持一致。

2.  点击桌面的小艺建议卡片。此时卡片显示的是“欢迎使用小艺建议”，点击卡片打开小艺的隐私页面，并选择“同意”。如果此前已经同意过小艺的隐私协议，此步骤可以跳过。

3. 打开开发者调试模式：进入设置 -> 机型 -> 关于手机，连续点击软件版本7次，弹出“开启“开发者模式””，点击“确认开启”。

4. 长按电源键唤醒小艺，将半屏态小艺向上拉升至全屏态，点击右上角的头像，点击“我的”页面里面的“设置”，打开“WLAN下自动更新”开关。

5.  在上一步页面中下滑，点击“个性化推荐”，进入后打开“个性化推荐”的开关。

6. 进入设置 -> 系统 -> 开发者选项 -> 意图框架调试，打开意图框架调试开关，如果下方显示已切换至真机模式并且测试应用包名在“本设备支持测试应用”下，则代表真机模式切换成功。 

【提示】如果出现意图框架调试打开后，设备长时间无法出现“已切换至真机模式”或者出现“已切换至真机模式”但没有包名的时候，可以尝试以下操作：

1. 登出华为账号，再登录之后重新开启意图框架调试开关。
2. 在设置-小艺-小艺建议-桌面卡片建议路径下关闭“桌面卡片建议”的开关，然后返回桌面重新点击小艺建议的卡片，将展示“欢迎使用小艺建议”的卡片刷新成有服务推荐的卡片，最后重新开启意图框架调试开关。

7. 完成以上所有步骤，即可进行联调。

3.4.3 联调验证

1. 意图共享：在测试应用当中成功触发意图共享。即通过测试应用内的操作触发shareIntent()接口的调用，并且意图共享成功。

   【举例】某音乐APP接入意图框架音乐续播的特性。通过播放某一首歌曲的用户操作，触发某音乐APP调用系统接口shareIntent()。某音乐APP的开发者通过日志确认shareIntent()接口调用成功，则可以认为某音乐APP本次意图共享是成功的。

2. 卡片渲染：点击桌面上的小艺建议卡片中任意服务，然后返回桌面，会触发小艺建议卡片强制刷新。刷新之后会展示前一步意图共享的数据所形成的模板卡片。具体卡片的样式可以参考具特性的场景说明文档。

   【提示】重复意图共享和卡片渲染两步，可以触发卡片上文字元素和图片元素的刷新。

3. 意图调用：点击小艺建议卡片中的模板卡片，能够跳转至测试应用的目标页面，则说明意图调用的过程是正确的。

   1. 【提示】意图调用的验证过程中，应当对测试应用的冷启动和热启动场景都进行验证，两个场景最终的跳转页面应当与预期的页面保持一致。
   2. 如果卡片没有正常渲染。可以尝试通过下列方法出卡：
      1. 检查个性化推荐开关是否开启，详见环境准备章节步骤5；检查意图框架测试开关是否开启，详见环境准备章节步骤6；检查完后重新执行卡片渲染步骤。
      2. 重新触发意图共享，并且在接口结果返回success之后。重新连接充电线，手机灭屏等待8分钟，再重新执行卡片渲染步骤。

3.4.4 端云结合的习惯推荐

涉及习惯推荐叠加上云搜索场景的开发者优先完成习惯推荐在设备上联调，确保测试应用的意图共享和意图调用的业务逻辑正确。后端接口开发完毕，需自行检查接口的出参是否满足意图框架云侧接口规范。以上两步完成之后，可联系华为意图框架接口同事提交后端接口文档，华为同事会配合开发者进行联调。

4 事件推荐方案

4.1 概述

事件推荐是应用/元服务有新的动态产生且满足推荐规则时给用户做出的主动推荐。实现事件推荐需要开发者将事件信息共享给意图框架，当满足事件推送规则时，会在小艺建议入口向指定用户推荐该事件提醒卡片，也支持通过对话或关键字搜索的方式查询事件内容状态。

事件根据是否指定用户ID可分为两种：用户事件和公共事件。

用户事件：由用户主动行为触发，根据用户标识对某一个指定用户ID单独进行推送或某一批指定用户ID批量进行推送。例如，附近优惠服务向智慧分发平台推送某用户购买了某优惠券的事件，意图框架在优惠券到期前X天提醒该用户优惠券即将到期。

公共事件：不指定用户ID推送的事件，将向同一画像的人群进行推送。例如，气象局将台风预警事件共享给意图框架，意图框架在台风到达前3天，将台风预警事件推送给可能受台风影响的用户群。公共事件包括灾害或故障警示警告、节目安排、赛事赛程等信息。

4.2 场景体验

4.2.1典型场景

事件推荐典型场景包括：

• 关注提醒事件（购物车降价、加追更新）
• 订单履行提醒事件（门票、机票、打车、外卖、挂号）
• 核销转化事件（会员、优惠券、话费余额）

各垂域也可根据垂域的实际情况定义具体的事件。

电影开场提醒为例，用户在应用/元服务中购买了电影票，在电影开场前半小时（具体生效时间将根据具体垂域的情况和用户最佳体验确定），用户可在小艺建议入口看到电影取票提醒的卡片，点击卡片可跳转到应用/元服务的订单详情页，用户可在该页面完成电影取票。

4.3 接入方案

4.3.1 方案概述

当开发者有事件想要通知到用户时，可通过应用/元服务的云侧服务器向智慧分发平台推送事件内容（意图共享）。系统通过智慧决策判断事件发生的条件，在满足条件时，向用户推荐事件提醒卡片，当用户点击卡片后，可跳转到应用/元服务的详情页查看事件详情（意图调用）。

4.3.2 流程图

1. 开发者获取云侧事件捐赠所需的SID（Service OpenID）。

1. 当用户有订单事件后，开发者云将事件内容和SID同步到业务云。
2. 华为内部会根据事件和具体场景制定事件服务推出规则和时机。
3. 在满足制定规则场景下展示对应用户事件，增加服务曝光率。

4.3.3 意图注册

以还款待办事件提醒特性为例，首先要注册查看还款意图（ViewRepayment），详见各垂域意图Schema。开发者需要编辑对应的意图配置#PROJECT_HOME/entry/src/main/resources/base/profile/insight_intent.json文件，实现意图注册。

{
  // 应用支持的意图列表
  // 必须声明应用支持插件包含的必选意图，应用上架时会进行校验
  "insightIntents": [
    {
      // 意图名称
      // 名称应当遵循意图框架规范，当前仅支持预置垂域意图，不允许自定义
      // 应用内意图名称唯一，不允许出现相同的名称定义
      "intentName": "ViewRepayment",
      // 意图所属的垂域
      "domain": "BankingDomain",
      // 意图版本号
      // 插件引用意图时会校验该版本号，只有和插件定义的版本号一致才能正常调用
      "intentVersion": "1.0.1",
      // 意图调用逻辑入口
      "srcEntry": "./ets/entryability/InsightIntentExecutorImpl.ets",
      "uiAbility": {
        // 意图所在module、ability，以及代码相对路径入口
        "ability": "EntryAbility",
        // UIAbility支持前后台两种执行模式
        "executeMode": [
          "background",
          "foreground"
        ]
      }
    }
  ]
}

4.3.4 获取SID

说明

API文档参见：意图框架API参考 > getSid。

云侧事件捐赠凭证SID（Service OpenID）优先从缓存获取，当缓存获取失败可以强制从云侧获取新的SID。

import { insightIntent } from '@kit.IntentsKit';
import { BusinessError } from '@kit.BasicServicesKit';

// 根据实际代码上下文自行传入合适的context
insightIntent.getSid(context, false) // 优先获取缓存SID，改为true则强制从云侧获取新SID
  .then((sid: string) => {
    // 获取SID成功
    console.info('getSid succeed!');
  }).catch((error: BusinessError) => {
  // 获取SID失败
  console.error(`getSid failed! error=${error.code} reason=${error.message}`);
});

4.3.5 云侧意图共享

4.3.5.1 服务上架配置

云侧意图需要服务承载，需要先在AppGallery Connect上架应用/元服务，然后在小艺开放平台配置意图，具体步骤如下：

1.  在AppGallery Connect中创建应用/元服务，具体操作步骤见应用开发准备，完成意图注册应用/元服务发布。应用/元服务中需包含意图注册声明文件。

2.  在AppGallery Connect上架后，通过华为开发者联盟>管理中心>智慧服务>小艺开放平台>进入小艺开放平台。

3.  选择待上架的意图，填写基本信息。

4.  选择“意图”页签，可以新增、修改、删除，并保存配置。

5.  选择“发布”页签，依次配置检查、测试。

6.  测试成功后提交审核，等待审核通过。

服务上架配置完成后，进入意图共享和意图调用环节。

4.3.5.2 意图共享接口调用

应用/元服务通过云侧意图共享接口，把对应意图的相关事件数据共享给Intents Kit，用于事件提醒服务。

4.3.5.3 事件撤销接口调用

当应用/元服务共享的意图相关事件数据超过时效期，Intents Kit需要通过云侧事件撤销接口把相关事件数据撤销，以避免触发超过时效期的事件提醒。

4.3.4 端侧意图调用

开发者需要自己实现InsightIntentExecutor，并在对应回调实现打开落地页（点击推荐卡片跳转的界面）的能力，ViewRepayment的意图调用字段定义见对应垂域意图Schema定义表。

步骤如下：

1. 继承InsightIntentExecutor。
2. 重写对应方法，例如目标拉起前台页面，则可重写onExecuteInUIAbilityForegroundMode方法。
3. 通过意图名称，识别查看还款意图（ViewRepayment）。
4. 在对应的方法中传递意图参数（param），并拉起对应落地页（如还款页面）。

import { insightIntent, InsightIntentExecutor } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

/**
 * 意图调用样例 */
export default class InsightIntentExecutorImpl extends InsightIntentExecutor {
  private static readonly VIEW_REPAYMENT = 'ViewRepayment';
  /**
   * override 执行前台UIAbility意图
   *
   * @param name 意图名称
   * @param param 意图参数
   * @param pageLoader 窗口
   * @returns 意图调用结果
   */
  onExecuteInUIAbilityForegroundMode(intentName: string, param: Record<string, Object>, pageLoader: window.WindowStage):
    Promise<insightIntent.ExecuteResult> {
    // 根据意图名称分发处理逻辑
    switch (intentName) {
      case InsightIntentExecutorImpl.VIEW_REPAYMENT:
        return this.viewRepayment(param, pageLoader);
      default:
        break;
    }
    return Promise.resolve({
      code: -1,
      result: {
        message: 'unknown intent'
      }
    } as insightIntent.ExecuteResult)
  }

  /**
   * 实现调用查看还款功能
   *
   * @param param 意图参数
   * @param pageLoader 窗口
   */
  private viewRepayment(param: Record<string, Object>, pageLoader: window.WindowStage): Promise<insightIntent.ExecuteResult> {
    return new Promise((resolve, reject) => {
      let para: Record<string, string> = {
        'result': JSON.stringify(param)
      };
      let localStorage: LocalStorage = new LocalStorage(para);
      // TODO 实现意图调用，loadContent的入参为查看还款落地页路径，例如：'pages/Index'
      pageLoader.loadContent('pages/Index', localStorage)
        .then(() => {
          let entityId: string = (param.items as Array<object>)?.[0]?.['entityId'];
          // TODO 调用成功的情况，此处可以打印日志
          resolve({
            code: 0,
            result: {
              message: 'Intent execute succeed'
            }
          });
        })
        .catch((err: BusinessError) => {
          // TODO 调用失败的情况
          resolve({
            code: -1,
            result: {
              message: 'Intent execute failed'
            }
          })
        });
    })
  }
}

4.4 开发者测试

意图框架向开发者提供真机测试能力，即开发者可连接设备进行调测。开发者完成代码开发之后，功能正式上架应用市场前，可以在HarmonyOS NEXT设备上面进行自验证，打磨体验。真机测试分为三个步骤：基础信息提供，环境准备，联调验证。

4.4.1 基础信息提供

达成开发意向后，开发者发送邮件到邮箱（hagservice@huawei.com）或者联系华为意图框架接口同事，向华为提供测试应用的信息。

序号	基础信息	描述
1	应用名称	应用市场上架的应用名称。
2	应用包名	应用市场上架的应用包名。
3	接入意图名称	开发者意向接入的意图名称（中英文）。
4	应用图标	应用的图标，具体要求如下： 图标背景：非透明。 比例&尺寸：1:1，72px*72px。 大小：不超过1M。 格式：png、jpg、jpeg。
5	APP ID	登录华为开发者联盟，在“我的项目 > 项目设置 > 常规 > 应用-APP ID”中获取。
6	Client ID	登录华为开发者联盟，在“我的项目 > 项目设置 > 常规 > 应用 > OAuth 2.0客户端ID(凭据) > Client ID”中获取。
7	华为账号（UID）	开发者用于调试的华为账号；登录华为开发者联盟，在“我的项目 > 项目设置 > 常规 > 开发者 > developer ID"中获取。
8	设备ID	开发者用于调试的设备ID；开启设备的意图框架测试开关(测试设备路径：设置 -> 系统 -> 开发者选项 -> 意图框架调试)，界面展示的意图框架测试ID。

4.4.2 环境准备

准备一台装有HarmonyOS Next版本的手机设备，系统版本最低要求为 Developer Beta 3。需要按照以下顺序依次执行，不能更换执行顺序。

1. 保持设备联网，并且设备时间和实际北京时间保持一致。
2. 点击桌面的小艺建议卡片。此时卡片显示的是“欢迎使用小艺建议”，点击卡片打开小艺的隐私页面，并选择“同意”。如果此前已经同意过小艺的隐私协议，此步骤可以跳过。

1. 打开开发者调试模式：进入设置 -> 机型 -> 关于手机，连续点击软件版本7次，弹出“开启“开发者模式””，点击“确认开启”。

   

2. 长按电源键唤醒小艺，将半屏态小艺向上拉升至全屏态，点击右上角的头像，点击“我的”页面里面的“设置”，打开“WLAN下自动更新”开关。

   

3. 在上一步页面中下滑，点击“个性化推荐”，进入后打开“个性化推荐”的开关。

   

4. 进入设置 -> 系统 -> 开发者选项 -> 意图框架调试，打开意图框架调试开关，如果下方显示已切换至真机模式并且测试应用包名在“本设备支持测试应用”下，则代表真机模式切换成功。

   

   【提示】如果出现意图框架调试打开后，设备长时间无法出现“已切换至真机模式”或者出现“已切换至真机模式”但没有包名的时候，可以尝试以下操作：

   1. 登出华为账号，再登录之后重新开启意图框架调试开关。
   2. 在设置-小艺-小艺建议-桌面卡片建议路径下关闭“桌面卡片建议”的开关，然后返回桌面重新点击小艺建议的卡片，将展示“欢迎使用小艺建议”的卡片刷新成有服务推荐的卡片，最后重新开启意图框架调试开关。

5. 完成以上所有步骤，即可进行联调。

4.4.3 联调验证

1. 事件共享：开发者登录应用即可获取云侧事件捐赠的SID，然后触发事件推送，将事件内容同步到华为云，具体操作可参考开发者指南-事件推荐方案章节。

   【举例】某出行类APP接入意图框架航班提醒的特性。用户通过APP购买了机票，触发开发者云调用华为事件通知（service-events/notify）接口，将用户航班事件推送至华为云，接口响应成功。

2. 卡片渲染：点击桌面上的小艺建议卡片中任意服务，然后返回桌面，会触发小艺建议卡片强制上云刷新。出卡条件是以事件的生效时间进行偏移，具体出卡条件和卡片的样式可以参考具特性的场景说明文档（确定开发意向后由华为侧提供）。

   【举例】航班提醒是提前24小时提醒用户，如果用户航班起飞时间是8月15日20:00，则8月14号20:00起可查询到该事航班信息，在此之前无法查询到信息。

3. 意图调用：点击小艺建议卡片中的模板卡片，在测试应用冷启动或热启动的场景下都能够跳转至测试应用的目标页面，则说明意图调用的过程是正确的。

   【举例】点击小艺建议卡片中的模板卡片，会跳转至该用户的购票详情页面。

5 技能调用方案

5.1 概述

技能调用是意图框架依托系统AI多模态大模型能力做深度用户输入理解，并通过解析的用户意图对接应用或元服务内的功能和内容。

5.2 场景体验

用户通过对小艺对话进行自然语言输入实现内容查询，知识问答，以及通过对图片选定识别问答进行服务获取。技能调用场景分为两种：

• 功能服务类：端侧意图调用直接进入应用或元服务对应意图功能服务页面。
• 信息交互类：云侧意图调用进行内容查询后展示，端侧用户点击进行意图调用闭环。

5.2.1 典型场景

功能服务类

1. 跳转页面不带参数场景。例如打开付款码：语音对话输入“打开xx付款码”，即可弹窗对应付款码。
2. 跳转页面带参数场景。例如搜索商品带关键词：语音对话输入“打开xx应用搜一下xx品牌39码”，即可弹窗对应商品。
3. 功能执行并展示UIExtension。例如操控蓝牙开关：语音对话输入“打开蓝牙”，即可弹窗蓝牙设置，并打开蓝牙开关。

信息交互类

1. 内容展示场景。例如查找菜谱：语音对话输入“鱼香肉丝怎么做”，即可搜索到对应的菜谱。
2. 内容展示+AIGC（Artificial Intelligence Generated Content）生成场景。例如查公司：语音对话输入“xxx公司怎么样”，即可生成并展示关于xxx公司的信息。
3. 功能履约场景。例如订电影票：语音对话输入“买两张今天的电影票，xxx电影”，即可进行电影票购买选座。

5.3 接入方案

5.3.1 方案概述

开发者需要按照意图定义，进行意图注册并实现意图调用；用户通过对小艺对话进行自然语言输入，小艺理解语义转换成意图调用（含意图参数），执行意图调用实现对应交互体验。

5.3.1.1 端侧意图注册

以“搜索旅游攻略”特性为例，开发者首先要注册“查看旅游攻略”（ViewTravelGuides），其他意图见各垂域意图Schema。开发者需要编辑对应的意图配置PROJECT_HOME/entry/src/main/resources/base/profile/insight_intent.json文件，实现意图注册。

{
  "insightIntents": [
    {
      "intentName": "ViewTravelGuides",
      "domain": "TravelDomain",
      "intentVersion": "1.0.1",
      "srcEntry": "./ets/entryability/InsightIntentExecutorImpl.ets",
      "uiAbility": {
        "ability": "EntryAbility",
        "executeMode": [
          "background",
          "foreground"
        ]
      },
      "uiExtension": {
        "ability": "insightIntentUIExtensionAbility"
      }
    }
  ]
}

配置说明如下所示：

字段	说明	约束
insightIntents	应用支持的意图API列表	必须声明应用支持插件包含的必选API，应用上架时会进行校验。
intentName	意图API名称	名称应当遵循意图框架规范，当前仅支持预置意图API，不允许自定义。 应用内意图名称唯一，不允许出现相同的名称定义。
domain	意图所属的垂域	-
intentVersion	意图API版本号	意图引用API时会校验该版本号，只有和意图定义的版本号一致才能正常调用。具体版本定义参考预置意图API。
srcEntry	意图API入口代码文件相对路径	根据意图API实现业务文件填写。
uiAbility	UIAbility执行配置	提供意图执行的前台界面或后台无界面执行时需要进行声明配置。
uiExtension	InsightIntentUIExtensionAbility执行配置	提供意图执行的窗口化界面时需要进行声明配置。
ability	意图调用API所在ability名称	本意图API所在的实现ability名称，可根据实际业务命名。
executeMode	意图执行支持的模式	在UIAbility组件中特有属性，包含如下枚举值： background：后台执行，指UIAbility组件的后台执行（无界面）。 foreground：前台执行，指UIAbility组件的前台执行（界面）。

5.3.2 端侧前台意图调用

开发者需自己实现InsightIntentExecutor，并在对应回调实现打开落地页（点击推荐卡片跳转的界面，如旅游攻略落页面）的能力，ViewTravelGuides的意图调用字段定义见查看旅游攻略 （ViewTravelGuides）。

步骤如下：

1. 继承InsightIntentExecutor。
2. 重写对应方法，例如目标拉起前台页面，则可重写onExecuteInUIAbilityForegroundMode方法。
3. 通过意图名称，识别查看旅游攻略意图(ViewTravelGuides)，在对应的方法中传递意图参数（param），并拉起对应落地页（点击推荐卡片跳转的界面，如旅游攻略落页面）。

import { insightIntent, InsightIntentExecutor } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

/**
 * 意图调用样例 */
export default class InsightIntentExecutorImpl extends InsightIntentExecutor {
  private static readonly VIEW_TRAVEL_GUIDES = 'ViewTravelGuides';
  /**
   * override 执行前台UIAbility意图
   *
   * @param name 意图名称
   * @param param 意图参数
   * @param pageLoader 窗口
   * @returns 意图调用结果
   */
  onExecuteInUIAbilityForegroundMode(name: string, param: Record<string, Object>, pageLoader: window.WindowStage):
    Promise<insightIntent.ExecuteResult> {
    // 根据意图名称分发处理逻辑
    switch (name) {
      case InsightIntentExecutorImpl.VIEW_TRAVEL_GUIDES:
        return this.viewTravelGuides(param, pageLoader);
      default:
        break;
    }
    return Promise.resolve({
      code: -1,
      result: {
        message: 'unknown intent'
      }
    } as insightIntent.ExecuteResult)
  }
  /**
   * 实现调用查看旅游攻略功能
   *
   * @param param 意图参数
   * @param pageLoader 窗口
   */
  private viewTravelGuides(param: Record<string, Object>, pageLoader: window.WindowStage): Promise<insightIntent.ExecuteResult> {
    return new Promise((resolve, reject) => {
      // TODO 实现意图调用，loadContent的入参为旅游攻略落地页路径，例如：pages/TravelGuidePage
      pageLoader.loadContent('pages/TravelGuidePage')
        .then(() => {
          let entityId: string = (param.items as Array<object>)?.[0]?.['entityId'];
          // TODO 调用成功的情况，此处可以打印日志
          resolve({
            code: 0,
            result: {
              message: 'Intent execute succeed'
            }
          });
        })
        .catch((err: BusinessError) => {
          // TODO 调用失败的情况
          resolve({
            code: -1,
            result: {
              message: 'Intent execute failed'
            }
          })
        });
    })
  }
}

5.3.3 端侧前台窗口意图调用

开发者需自己实现InsightIntentExecutor，并在对应回调实现窗口页面内容加载的能力。

步骤如下：

1. 继承InsightIntentExecutor。
2. 重写对应方法，例如目标拉起前台窗口化页面，则可重写onExecuteInUIExtensionAbility方法。
3. 通过意图名称，识别打开蓝牙意图（LoadBluetoothCard）调用扩展意图，在对应的方法中传递意图参数（param），并拉起对应窗口化页面（如打开蓝牙窗口化页面）。

import { insightIntent, InsightIntentExecutor, UIExtensionContentSession } from '@kit.AbilityKit';

/**
 * 意图调用样例 */
export default class IntentExecutorImpl extends InsightIntentExecutor {
  private static readonly TAG: string = 'IntentExecutorImpl';
  private static readonly LOAD_BLUETOOTH_CARD: string = 'LoadBluetoothCard';
  /**
   * override 执行前台UI扩展意图
   *
   * @param name 意图名称
   * @param param 意图参数
   * @param pageLoader 窗口
   * @returns 意图调用结果
   */
  async onExecuteInUIExtensionAbility(name: string, param: Record<string, Object>,
    pageLoader: UIExtensionContentSession):
    Promise<insightIntent.ExecuteResult> {
    console.info(IntentExecutorImpl.TAG, `onExecuteInUIExtensionAbility`);
    switch (name) {
      case IntentExecutorImpl.LOAD_BLUETOOTH_CARD:
        console.info(IntentExecutorImpl.TAG, `onExecuteInUIAbilityForegroundMode::ForegroundUiAbility intent`);
        return this.openLoadBluetoothCard(pageLoader);
      default:
        console.info(IntentExecutorImpl.TAG, `onExecuteInUIAbilityForegroundMode::invalid intent`);
        break;
    }

    let result: insightIntent.ExecuteResult = {
      code: -1,
      result: {
        message: 'onExecuteInUIExtensionAbility failed'
      }
    };
    return result;
  }

  /**
   * 打开加载蓝牙卡片意图
   *
   * @param pageLoader 意图内容Session对象
   * @returns 执行结果
   */
  private async openLoadBluetoothCard(pageLoader: UIExtensionContentSession): Promise<insightIntent.ExecuteResult> {
    pageLoader.loadContent('pages/UiExtensionPage');
    let result: insightIntent.ExecuteResult = {
      code: 0,
      result: {
        message: 'intent execute succeed'
      }
    }
    return result;
  }
}

6 本地搜索方案

6.1 概述

本地搜索是在HarmonyOS归一化搜索特性，开发者将应用/元服务内的功能和内容通过意图框架共享到HarmonyOS，即可实现“一步搜索，内容直达”。

6.2 场景体验

6.2.1 典型场景

以“音乐垂域”的“歌曲本地搜索”特性为例，当用户在使用音乐应用/元服务产生行为时，应用/元服务可以将音乐的数据通过意图框架API接口共享到HarmonyOS。这里的音乐数据可以是用户收听过的歌曲，也可以是应用/元服务预测用户感兴趣的歌曲，那么后续用户在小艺搜索入口中搜索歌名时，系统将会在应用/元服务共享的数据中检索对应内容，并使用卡片的形式展示内容结果，当用户点击对应卡片热区时，可以跳转进具体音乐播放页或者直接后台执行播放。

6.2.2 卡片展示效果

意图框架提供各垂域在小艺搜索展示使用的标准模板卡片，开发者无需开发展示卡片。模板卡片包含应用/元服务和内容必要信息，比如歌曲名称、歌曲封面图、歌曲描述，这类参数需要开发者共享到系统。各垂域适用的风格卡片不同，以实际特性场景要求为准。以下为歌曲本地搜索的模板卡样式的示例：

6.3 接入方案

6.3.1 方案概述

当用户使用应用/元服务时，开发者可以按照标准意图Schema（具体意图详见各垂域意图Schema）向系统共享数据，并支持意图调用（空调用与传参调用），以实现用户点击卡片后，可后台执行功能（例如播放指定歌曲）或跳转至指定内容页面（例如指定的歌曲播放页面）。

6.3.2 意图注册

以歌曲本地搜索特性为例，首先要注册播放歌曲意图（PlayMusic），其他意图见各垂域意图Schema。开发者需要编辑对应的意图配置PROJECT_HOME/entry/src/main/resources/base/profile/insight_intent.json文件，实现意图注册。

{
  // 应用支持的意图列表
  // 必须声明应用支持插件包含的必选意图，应用上架时会进行校验
  "insightIntents": [
    {
      // 意图名称
      // 名称应当遵循意图框架规范，当前仅支持预置垂域意图，不允许自定义
      // 应用内意图名称唯一，不允许出现相同的名称定义
      "intentName": "PlayMusic",
      // 意图所属的垂域
      "domain": "MusicDomain",
      // 意图版本号
      // 插件引用意图时会校验该版本号，只有和插件定义的版本号一致才能正常调用
      "intentVersion": "1.0.1",
      // 意图调用逻辑入口
      "srcEntry": "./ets/entryability/InsightIntentExecutorImpl.ets",
      "uiAbility": {
        // 意图所在module、ability，以及代码相对路径入口
        "ability": "EntryAbility",
        // UIAbility支持前后台两种执行模式
        "executeMode": [
          "background",
          "foreground"
        ]
      }
    }
  ]
}

6.3.3 端侧意图共享

构建意图对象，并且调用shareIntent()，实现意图共享。可同时构建多个PlayMusic或PlayMusicList的意图对象。

import { insightIntent } from '@kit.IntentsKit';
import { BusinessError } from '@kit.BasicServicesKit';

let playMusicIntent1: insightIntent.InsightIntent;
let playMusicIntent2: insightIntent.InsightIntent;
// 共享数据接口  意图数组可以是更多的实体
// 根据实际代码上下文自行传入合适的context
insightIntent.shareIntent(context, [playMusicIntent1, playMusicIntent2]).then(() => {
  console.info('shareIntent succeed');
}).catch((err: BusinessError) => {
  console.error(`error.code: ${err?.code}, failed because ${err?.message}`);
});

PlayMusic的意图共享字段定义见各垂域意图Schema定义，代码示例如下：

import { insightIntent } from '@kit.IntentsKit';

let playMusicIntent: insightIntent.InsightIntent = {
  intentName: "PlayMusic",
  intentVersion: "1.0",
  identifier: "52dac3b0-6520-4974-81e5-25f0879449b5",
  intentActionInfo: {
    actionMode: "EXECUTED",
    executedTimeSlots: {
      executedStartTime: 1637393212000,
      executedEndTime: 1637393112000,
    },
    currentPercentage: 50,
  },
  intentEntityInfo: {
    entityName: "Music",
    entityId: "C10194368",
    entityGroupId: "C10194321312",
    displayName: "测试歌曲1",
    description: "NA",
    logoURL: "https://www-file.abc.com/-/media/corporate/images/home/logo/abc_logo.png",
    keywords: ["华为音乐", "化妆"],
    rankingHint: 99,
    expirationTime: 1637393212000,
    metadataModificationTime: 1637393212000,
    activityType: ["1", "2", "3"],
    artist: ["测试歌手1", "测试歌手2"],
    lyricist: ["测试词作者1", "测试词作者2"],
    composer: ["测试曲作者1", "测试曲作者2"],
    albumName: "测试专辑",
    duration: 244000,
    playCount: 100000,
    musicalGenre: ["流行", "华语", "金曲", "00后"],
    isPublicData: false,
  }
}

完整的意图共享示例如下所示，该示例构建了一个PlayMusic意图，并进行了shareIntent调用。

import { insightIntent } from '@kit.IntentsKit';
import { BusinessError } from '@kit.BasicServicesKit';

let playMusicIntent: insightIntent.InsightIntent = {
  intentName: "PlayMusic",
  intentVersion: "1.0",
  identifier: "52dac3b0-6520-4974-81e5-25f0879449b5",
  intentActionInfo: {
    actionMode: "EXECUTED",
    executedTimeSlots: {
      executedStartTime: 1637393212000,
      executedEndTime: 1637393112000,
    },
    currentPercentage: 50,
  },
  intentEntityInfo: {
    entityName: "Music",
    entityId: "C10194368",
    entityGroupId: "C10194321312",
    displayName: "测试歌曲1",
    description: "NA",
    logoURL: "https://www-file.abc.com/-/media/corporate/images/home/logo/abc_logo.png",
    keywords: ["华为音乐", "化妆"],
    rankingHint: 99,
    expirationTime: 1637393212000,
    metadataModificationTime: 1637393212000,
    activityType: ["1", "2", "3"],
    artist: ["测试歌手1", "测试歌手2"],
    lyricist: ["测试词作者1", "测试词作者2"],
    composer: ["测试曲作者1", "测试曲作者2"],
    albumName: "测试专辑",
    duration: 244000,
    playCount: 100000,
    musicalGenre: ["流行", "华语", "金曲", "00后"],
    isPublicData: false,
  }
}
// 共享数据接口  意图数组可以是更多的实体
// 根据实际代码上下文自行传入合适的context
insightIntent.shareIntent(context, [playMusicIntent]).then(() => {
  console.info('shareIntent succeed');
}).catch((err: BusinessError) => {
  console.error(`error.code: ${err?.code}, failed because ${err?.message}`);
});

6.3.4 端侧意图调用

开发者需要自己实现InsightIntentExecutor，并在对应回调实现打开落地页（点击推荐卡片跳转的界面）或后台执行的能力，PlayMusic的意图调用字段定义见各垂域意图Schema。

步骤如下：

1. 继承InsightIntentExecutor。
2. 重写对应方法，例如目标拉起前台页面，则可重写onExecuteInUIAbilityForegroundMode方法。
3. 通过意图名称，识别播放歌曲意图（PlayMusic），在对应的方法中传递意图参数（param），并拉起对应落地页（如播放歌曲落地页）或后台执行（播放歌曲）。

import { insightIntent, InsightIntentExecutor } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

/**
 * 意图调用样例
 */
export default class InsightIntentExecutorImpl extends InsightIntentExecutor {
  private static readonly PLAY_MUSIC = 'PlayMusic';
  /**
   * override 执行前台UIAbility意图
   *
   * @param name 意图名称
   * @param param 意图参数
   * @param pageLoader 窗口
   * @returns 意图调用结果
   */
  onExecuteInUIAbilityForegroundMode(name: string, param: Record<string, Object>, pageLoader: window.WindowStage):
    Promise<insightIntent.ExecuteResult> {
    // 根据意图名称分发处理逻辑
    switch (name) {
      case InsightIntentExecutorImpl.PLAY_MUSIC:
        return this.playMusic(param, pageLoader);
      default:
        break;
    }
    return Promise.resolve({
      code: -1,
      result: {
        message: 'unknown intent'
      }
    } as insightIntent.ExecuteResult)
  }
  /**
   * 实现调用播放歌曲功能
   *
   * @param param 意图参数
   * @param pageLoader 窗口
   */
  private playMusic(param: Record<string, Object>, pageLoader: window.WindowStage): Promise<insightIntent.ExecuteResult> {
    return new Promise((resolve, reject) => {
      let para: Record<string, string> = {
        'result': JSON.stringify(param)
      };
      let localStorage: LocalStorage = new LocalStorage(para);
      // TODO 实现意图调用，loadContent的入参为歌曲落地页路径，例如：pages/Index
      pageLoader.loadContent('pages/Index', localStorage)
        .then(() => {
          let entityId: string = (param.items as Array<object>)?.[0]?.['entityId'];
          // TODO 调用成功的情况，此处可以打印日志
          resolve({
            code: 0,
            result: {
              message: 'Intent execute succeed'
            }
          });
        })
        .catch((err: BusinessError) => {
          // TODO 调用失败的情况
          resolve({
            code: -1,
            result: {
              message: 'Intent execute failed'
            }
          })
        });
    })
  }
}

7 意图框架上架配置指导

开发者完成开发者测试后需在小艺开放平台进行意图注册配置并提交审核，审核通过后完成意图的正式上线。意图注册配置之前，APP需要先在AppGallery Connect（以下简称AGC）完成应用上架，具体操作步骤参见应用开发准备。意图注册配置操作步骤如下：

1. 通过“华为开发者联盟> 管理中心 > 生态服务 > 智慧服务 > 小艺开放平台（原HarmonyOS服务开放平台）”，即可找到小艺开放平台入口，注意需使用与应用上架相同的账号登录。

   

2. 在“小艺开放平台”首页“我的意图注册记录”中可以自动生成一条草稿态的记录，无需手动注册意图。若没有生成记录，请检查在AGC中提交上架的APP软件包中是否存在意图配置文件。若意图注册名称显示"$string:xxxxxx"乱码，请检查软件包中/entry/src/main/resources/base/element/string.json和/entry/src/main/resources/zh_CN/element/string.json文件中EntryAbility_label属性值是否引用了entry目录以外的定义，建议不做引用或者引用同目录下的定义。

   

3. 点击对应的意图注册记录“编辑”按钮，进入基本信息编辑页面，开发者补充完基本信息后点击“保存”即可。此处的版本号和版本描述为智慧分发配置的版本信息，用于开发者记录和识别智慧分发配置版本变更，与APP软件包版本无关。

   

4. 选择“意图”页签，点击“保存”会触发刷新，检查接入特性所依赖的全量意图是否在此页面都已列出，特性依赖意图见各垂域智慧分发特性列表。其中，“端云类型”涉及端的意图需在APP软件包中定义，此处会自动呈现；“端云类型”仅涉及云的意图需要需手动添加该意图；可参照如下步骤检查：
   1. 如果特性依赖的所有意图都已列出，检查意图名称、意图调用配置和意图共享配置等是否正确，正确则点击“保存”，进入下一步。
   2. 如果特性依赖的所有意图未全部列出，检查是否依赖“端云类型”仅涉及云的意图，若有则需要点击“新增”手动添加该意图。以“端云类型”仅为云的意图调用配置为例，首先从列表中选择对应意图后点击“确定”，若没有找到对应意图可联系华为工程师，检查是否未配置该意图。

      

      

   3. 添加完成后，需录入接口信息配置，具体信息如下：
      1. API：即开发者的URL地址信息，供华为侧服务器进行云侧意图调用。
      2. 认证方式：如果涉及接口鉴权，则选择认证方式（例如AK/SK认证）并配置密钥信息；如果不涉及则选择不认证。

         

      3. 个人数据授权：该信息是指华为侧服务器携带对应信息访问开发者服务器，当有个性化推荐诉求时需要填写，默认不填写；比如选中“用户授权的用户唯一标识”（即SID），则华为侧服务器访问开发者服务器时会携带SID，开发者服务器则可以识别用户返回个性化的数据用户推荐展示。

         

   4. 如果仍未全部列出，检查软件包中意图注册配置文件是否漏配，若漏配则在意图配置文件中补充配置后重新在AppGallery Connect完成应用上架/升级，然后在小艺开放平台进行意图注册。
   5. 如果提示声明意图不存在，则说明华为意图框架后台未配置该意图。开发者可以继续点击保存走完本次流程，但相应意图和关联特性不会生效；也可以联系华为工程师，检查是否未配置该意图。

      

5. 选择“发布”页签，进入配置检查页面。
   1. 点击“开始检查”，检查接入特性和其关联的意图是否正确，如下图所示。生成特性时会同时生成abilityId，若开发者接入特性的方案涉及此参数，则事件推荐请求字段abilityId参数需要填写当前界面的abilityId值。若提示特性undefined，则联系华为工程师，检查是否未配置该特性。

      

   2. 配置检查完成则进入“提交”页面，点击“提交审核”。

   

6. 提交审核后，在“小艺开放平台（原HarmonyOS服务开放平台） > 我的意图注册记录中”，该条记录状态变为“上架审核中”，一般审核周期为3个工作日，审核通过后状态变为“已上架”，至此意图注册及特性选择已完成。

   

   

7. 若开发者有新意图上架，可在同一条记录上进行编辑后提交，操作流程同上述步骤，未提交审核不影响已经注册的意图。