Harmony 鸿蒙:快速接入
ArkWeb 源码示例,需加入自己的宿主工程编译。
下载接入包
- Harmony 鸿蒙
ArkWeb API 12+ 页面和权限片段,需 DevEco 宿主工程编译;不含 HAR。
开始前准备
- 在“渠道 → 自建渠道 → 服务入口”创建专用 Web 入口,启用入口并绑定已发布智能体。需要渠道管理权限;没有入口时请企业管理员协助。
- 使用 DevEco / ArkWeb API12+ 工程,复制页面与 voice-permission-policy.ts;合并 INTERNET、MICROPHONE 及字符串资源片段,将 Ability 名改为宿主实际值。尚未发行 HAR。
从哪里取得入口参数
| 参数 | 填写内容 | 获取位置 |
|---|---|---|
| origin | 部署客服的公网 HTTPS 主机,不带 /support、路径或查询参数 | 从“服务入口 → 皮肤与代码”的入口链接提取协议和主机 |
| key / publicKey | 同一入口的公开 UUID key | 从该入口生成的链接或代码复制 key;Android 字段名为 publicKey |
| entryId | 同一入口的 ID | 从该入口生成的链接或代码复制 entryId,不填写智能体 ID |
客户端只填公开参数
管理 API Key、AppSecret 和登录 token 不得放入 App 源码或入口链接。公开 key 不是管理授权;本地会话编号也不代表可信会员身份。
安装与配置
- 下载本页客户端接入包,将 harmony/YunfuSupport.ets 及准备要求中的配套文件合并到宿主工程,不覆盖原有业务配置。
- 替换 HTTPS origin、公开 key 和 entryId,在用户点击后进入页面。网页请求语音时核对当前入口与精确来源,再申请系统麦克风;只 grant AUDIO_CAPTURE。
宿主接入示例
运行前
harmony/YunfuSupport.ets · ArkTS 页面文件 · 接入包 0.3.15
- 同目录加入 voice-permission-policy.ts,合并权限和字符串片段。
- 替换真实 Ability 名和公开参数,在 DevEco 页面列表注册;本示例按 API12+ 编写。
完整代码 · 95 行
harmony/YunfuSupport.etsTypeScript
import { webview } from '@kit.ArkWeb';
import { util } from '@kit.ArkTS';
import { abilityAccessCtrl, common } from '@kit.AbilityKit';
import { HostedAudioPermission, AudioPermissionRequest } from './voice-permission-policy';
// Explicit adapter keeps ArkTS nominal class/interface compatibility.
class ArkWebAudioRequest implements AudioPermissionRequest {
private value: PermissionRequest;
constructor(value: PermissionRequest) { this.value = value; }
getOrigin(): string { return this.value.getOrigin(); }
getAccessibleResource(): string[] { return this.value.getAccessibleResource(); }
grant(resources: string[]): void { this.value.grant(resources); }
deny(): void { this.value.deny(); }
}
// ArkWeb API 12+ source example. Register this page in the host route table.
// A new page instance creates a new isolated visitor. Remove the page before account changes.
@Entry
@Component
struct YunfuSupport {
private controller: webview.WebviewController = new webview.WebviewController();
private attached: boolean = false;
private clientSession: string = util.generateRandomUUID().toLowerCase();
private origin: string = 'https://YOUR_CUSTOMER_SERVICE_ORIGIN';
private key: string = 'YOUR_PUBLIC_KEY';
private entryId: string = 'YOUR_ENTRY_ID';
private audioPermission: HostedAudioPermission | undefined = undefined;
@State private supportUrl: string = '';
aboutToAppear(): void {
if (!/^https:\/\/[a-z0-9.-]+(:[0-9]{1,5})?$/.test(this.origin) ||
!/^[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(this.key) ||
!/^[-a-zA-Z0-9_]{1,100}$/.test(this.entryId)) {
throw new Error('Configure a published HTTPS support entry first');
}
this.supportUrl = this.origin + '/support?key=' + encodeURIComponent(this.key) +
'&entryId=' + encodeURIComponent(this.entryId) + '&surface=channel&clientSession=' + this.clientSession;
this.audioPermission = new HostedAudioPermission(this.origin, this.supportUrl,
ProtectedResourceType.AUDIO_CAPTURE, async (): Promise<boolean> => {
const context = getContext(this) as common.UIAbilityContext;
const result = await abilityAccessCtrl.createAtManager().requestPermissionsFromUser(
context, ['ohos.permission.MICROPHONE']);
return result.authResults.length === 1 && result.authResults[0] === 0;
});
}
private stopVoice(): void {
if (this.attached) {
this.controller.runJavaScript("window.dispatchEvent(new Event('yunfu:native-voice-stop'));")
.catch(() => {});
}
}
onPageHide(): void {
this.audioPermission?.setForeground(false);
this.stopVoice();
if (this.attached) this.controller.onInactive();
}
onPageShow(): void {
this.audioPermission?.setForeground(true);
if (this.attached) this.controller.onActive();
// Never reopen the microphone merely because the page became visible.
}
aboutToDisappear(): void {
this.audioPermission?.dispose();
this.stopVoice();
if (this.attached) this.controller.stop();
this.attached = false;
}
build() {
Column() {
if (this.supportUrl) {
Web({ src: this.supportUrl, controller: this.controller })
.onControllerAttached(() => { this.attached = true; })
.javaScriptAccess(true)
.domStorageAccess(true)
.fileAccess(false)
.mixedMode(MixedMode.None)
.onPageBegin((event) => { this.audioPermission?.navigate(event?.url || ''); })
.onOverrideUrlLoading((request: WebResourceRequest) => {
return request.getRequestUrl() !== this.supportUrl;
})
.onLoadIntercept((event) => {
return !event || event.data.getRequestUrl() !== this.supportUrl;
})
.onPermissionRequest((event) => {
if (!event) return;
if (!this.audioPermission) { event.request.deny(); return; }
this.audioPermission.request(new ArkWebAudioRequest(event.request)).catch(() => {});
})
.width('100%')
.height('100%')
}
}.width('100%').height('100%')
}
}聊天交互预览 · 本地示意
通用聊天交互示意,回复为固定演示内容;不执行此源码、不连接当前渠道或调用模型。
对应源码:harmony/YunfuSupport.ets。实际效果请在自己的宿主中按下方验收项核对。
预期结果:用户主动进入后显示渠道 UI;仅可信来源音频可申请授权,退出清理。完整原生编译和真机音频另行验收。
实际接待范围
容器承载现有 /support 页面:当前读取最近 100 条消息,尚未接线显式转人工按钮与更早历史翻页。人工接待沿服务端路由进入。页面能打开不代表宿主、文件与真实接待已验收。
本平台能力边界
提供前台网页语音授权流程,仍需 DevEco 编译和真机音频验收。API12 不使用 stopMicrophone;onInactive/停止加载不能代替停麦。文件选择、原生下载、后台通话和推送未接入。
怎样确认接入成功
- 从自己的 App 入口发送一条带唯一标记的测试问题,确认收到回复,并在接待台找到同一企业、入口和会话。仅页面打开或编译成功不能代替这一步。
- 验收实际允许/拒绝录音、授权中退出、AI 出声与打断、后台/锁屏释放、耳机、重拨及账号隔离。
- 退出 A 账号后用 B 账号重新进入,确认 B 看不到 A 的内容;挂断或离开页面后确认录音指示消失。
没有成功时先检查
| 现象 | 下一步 |
|---|---|
| 页面打不开 / 连接被拒绝 | 先核对 HTTPS 证书、origin 与同一入口的 key / entryId,再检查入口是否启用及来源限制;不要关闭安全校验绕过问题。 |
| 页面打开但没有回复 | 检查入口接待方案是否绑定已发布智能体、模型是否可用;在接待台按测试标记查找会话,确认是否已转人工。 |
| 文字可用,但无法语音 | 检查企业和入口是否开启语音、系统录音权限与网页授权是否都满足;由用户主动点击开始,分别确认实际收音、AI 出声和挂断释放。 |
继续接入与配置
官方原始接入文档
先按云蝠指南完成入口、智能体和服务配置,再按下列官方原文配置宿主权限或供应商资源。外部文档说明对应平台能力,不代表云蝠已开放其中全部接口;腾讯 SecretKey、签名密钥和管理 API Key 仅放服务端。参数、地域、类目和资费以官方当前页面及账号实际开通结果为准。
- OpenHarmony · ArkWeb onPermissionRequest ↗:核对网页音频授权事件与 grant/deny;文档主干会更新,本包 API12+ 示例仍须用目标 SDK 编译并真机验收。
- OpenHarmony · 声明应用权限 · 5.0 Release ↗:合并 MICROPHONE、用途字符串与实际 Ability 的 usedScene;清单声明不能代替运行时授权。
实现依据 · 仓库内路径
sdk/client-kit/harmony/YunfuSupport.etssdk/client-kit/README.md
文档描述当前源码能力;不等于你的宿主或生产环境已通过验收。