小鹅通SDK-鸿蒙端接入文档

产品简介

在 HarmonyOS 应用中集成小鹅通 SDK H5 页面，提供账号打通、内容交付与分销、支付营销、直播课程、页面分享、外链处理以及图片和音频等 Web 交互能力。当前 App 内嵌 SDK 暂不支持直播连麦、直播浮窗和涨粉神器。

SDK 基本信息

项目	内容
SDK 名称	小鹅通SDK（鸿蒙端）
开发者	深圳小鹅网络技术有限公司
包名	`@xe/webcore`
最新版本	1.0.11
更新日期	2026-11-02
包体大小	112.2 KB（114,886 字节）
包体下载地址	https://ohpm.openharmony.cn/ohpm/@xe/webcore/-/webcore-1.0.11.har
使用说明	合规使用指南、个人信息保护政策、小鹅通SDK开发者声明

text

webcore-1.0.11.har 摘要
MD5:     389b993690b8141f2514272e0969aa1a
SHA-256: 20740217db4c9a2ae0e152a9501bc7f6dd2cc44fef0868062087c24cab37f419

更新说明：新增可选个人信息能力开关（相册选图、录音，默认开启，可在初始化时按需关闭），配置方式见合规使用指南；同时更新了 SDK 描述文档。

前置条件

接入前请准备以下信息：

已开通小鹅通店铺，并取得店铺 app_id。
已开通内嵌 SDK 服务，并取得 client_id。
已安装 DevEco Studio 和对应的 HarmonyOS SDK。

SDK 已在以下环境验证，其他版本请以实际测试结果为准：

DevEco Studio	HarmonyOS SDK	ROM
5.0.1 Beta3	5.0.1（API 13）	5.0.0.106

安装 SDK

在工程根目录执行：

bash

ohpm install @xe/webcore
# 或
ohpm i @xe/webcore

如果使用本地 HAR 包，可在 oh-package.json5 中配置本地依赖，或通过 DevEco Studio 导入 HAR。

参数与 URL

SDK 参数名词解释

参数名	说明	获取方式及备注
app_id	店铺 ID	小鹅通店铺的店铺 ID，在管理台获取。
client_id	SDK 客户端 ID（对应 Client ID）	开通内嵌 SDK 服务后在管理台获取。

初始化参数

参数	类型	必填	说明
appId	string	是	小鹅通店铺标识，即店铺 app_id。
clientId	string	是	内嵌 SDK 接入凭证，即 client_id。
showLog	boolean	否	是否输出 SDK 调试日志，默认 `false`。生产环境建议关闭。
optionalCapabilities	object	否	可选个人信息能力开关，包含相册选图与录音两项，默认均开启。字段见下表。

optionalCapabilities 字段：

字段	类型	默认值	说明
chooseImage	boolean	`true`	相册选图能力。关闭后页面调用选图会向用户提示「图片选择功能暂不可用」并返回失败，不拉起系统图片选择器；无需声明媒体文件读权限。
recordAudio	boolean	`true`	录音能力。关闭后页面调用录音会向用户提示「录音功能暂不可用」并返回失败，不申请麦克风权限、不启动录音；关闭时应从 `module.json5` 中移除 `ohos.permission.MICROPHONE`。

两项能力都只在最终用户主动操作后由页面调用时触发，SDK 不会主动拉起选择器或申请权限。宿主未使用对应功能时应关闭该项，配置说明见合规使用指南。

XESDK.init({
  appId: '从小鹅通获取的 app_id',
  clientId: '从小鹅通获取的 client_id',
  showLog: false,
  optionalCapabilities: {
    chooseImage: true,
    recordAudio: false
  }
})

SDK URL 链接配置规则

店铺首页 URL 格式为：

text

https://{app_id}.h5.xiaoeknow.com

例如店铺 app_id 为 apprnDA0ZDw4581，首页 URL 为：

text

https://apprnDA0ZDw4581.h5.xiaoeknow.com

店铺内其他页面请从小鹅通管理台复制链接。例如在“课程管理 - 图文 - 具体课程 - 分享 - 复制”中得到：

text

https://appidxxxxxx.h5.xiaoeknow.com/p/course/text/i_5e7f809dd6317_qSMuUoAi?type=2

SDK 用于展示时，需要将链接域名替换为当前店铺的 {app_id}.h5.xiaoeknow.com，并按业务实际页面参数确认链接。例如：

text

https://apprnDA0ZDw4581.h5.xiaoeknow.com/p/course/text/i_5e7f809dd6317_qSMuUoAi?type=2

只替换域名部分，不要替换路径中的课程 ID；链接应使用 HTTPS。

权限配置

SDK 权限清单中的权限名称、使用场景和申请时机，应与接入方隐私政策及合规使用指南保持一致。当店铺页面使用录音、视频通话或拍摄功能时，还需要在宿主工程中申请对应的系统权限。

初始化 SDK

建议在 EntryAbility 的 onCreate 中初始化，并在展示 Web 页面前完成初始化：

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'
import { XESDK } from '@xe/webcore'

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    XESDK.init({
      appId: '从小鹅通获取的 app_id',
      clientId: '从小鹅通获取的 client_id',
      showLog: false
    })
  }
}

展示 Web 页面

XEWeb 的必填参数为：

url：要加载的小鹅通页面 URL。
controller：XeWebViewController 实例，用于处理返回、分享和 JS 回调。
eventDelegate：XeWebEventClient 实例，用于接收 ArkWeb 页面事件。
webOption：可选的 XEWebOptions，用于配置 Web 组件属性。

XEWebOptions 常用配置

未设置的属性使用 SDK 默认值：

属性	默认值	说明
renderMode	`RenderMode.ASYNC_RENDER`	Web 页面渲染模式。
javaScriptAccess	`true`	是否允许执行 JavaScript。
domStorageAccess	`true`	是否允许 DOM Storage。
fileAccess	`true`	是否允许页面访问文件资源。
imageAccess、onlineImageAccess	`true`	是否加载本地图片和网络图片。
mixedMode	`MixedMode.All`	是否允许 HTTP/HTTPS 混合内容。
geolocationAccess	`true`	是否允许网页获取地理位置。
mediaPlayGestureAccess	`true`	有声媒体是否需要用户手势后播放。
multiWindowAccess	`false`	是否允许 Web 页面创建多窗口。开启后需实现窗口事件回调。
horizontalScrollBarAccess、verticalScrollBarAccess	`false`	是否显示横向和纵向滚动条。

如需调整配置，请从公共入口导入并修改实例，不要引用 SDK 的内部文件路径：

import { XEWebOptions } from '@xe/webcore'

const webOption = new XEWebOptions()
webOption.fileAccess = true
webOption.mediaPlayGestureAccess = false

处理 SDK 回调

import {
  JsCallbackResponse,
  JsInteractType,
  XeWebViewController,
  XESDK,
  XEToken
} from '@xe/webcore'

export class ShopController extends XeWebViewController {
  override onJsInteract(
    actionType: JsInteractType,
    response: JsCallbackResponse
  ): void {
    switch (actionType) {
      case JsInteractType.LOGIN_ACTION:
        // 业务后台换取最新 token 后同步给 SDK。
        // tokenKey、tokenValue 的获取方式由业务服务端定义。
        const tokenKey = 'token_key'
        const tokenValue = '从业务后台获取的 token_value'
        XESDK.sync(new XEToken(tokenKey, tokenValue))
        break
      case JsInteractType.LOGOUT_ACTION:
        XESDK.syncNot()
        break
      case JsInteractType.SHARE_ACTION:
        // 分享数据通常为 JSON 字符串，由宿主应用自行展示分享面板。
        const sharePayload = response.getResponseData()
        // JSON.parse(sharePayload) 后可读取 share_title、share_content、
        // share_image、share_link 等字段。
        console.info(`share payload: ${sharePayload}`)
        break
      case JsInteractType.NOTICE_OUT_LINK_ACTION:
        // SDK 通知宿主应用打开外链，外链地址从回调数据中获取。
        const externalUrl = response.getResponseData()
        console.info(`external url: ${externalUrl}`)
        break
      default:
        break
    }
  }
}

处理 Web 页面事件

import { XeWebEventClient, XeWebViewController } from '@xe/webcore'

export class ShopEventDelegate extends XeWebEventClient {
  override onControllerAttached(controller: XeWebViewController): void {
    super.onControllerAttached(controller)
  }

  override onPageBegin(url: string): void {
    console.info(`page begin: ${url}`)
  }

  override onPageEnd(url: string): void {
    console.info(`page end: ${url}`)
  }

  override onProgressChange(progress: number): void {
    console.info(`page progress: ${progress}`)
  }

  override onErrorReceive(event: OnErrorReceiveEvent): void {
    console.error(`web error: ${event.error.getErrorInfo()}`)
  }
}

页面组件示例

import {
  XEWeb,
  XEWebOptions,
  XeWebEventClient,
  XeWebViewController
} from '@xe/webcore'

@Component
export struct ShopPage {
  private controller: ShopController = new ShopController()
  private eventDelegate: ShopEventDelegate = new ShopEventDelegate()
  private webOption: XEWebOptions = new XEWebOptions()
  private url: string = 'https://your-app-id.h5.xiaoeknow.com'

  build() {
    Column() {
      XEWeb({
        url: this.url,
        controller: this.controller,
        eventDelegate: this.eventDelegate,
        webOption: this.webOption
      })
        .width('100%')
        .height('100%')
    }
    .onBackPressed(() => this.controller.mBackward())
  }
}

mBackward() 会先退出 Web 全屏状态；未处于全屏时，如果 Web 页面存在历史记录则返回上一页，并返回 true 表示已处理返回事件。

登录态同步

预同步

如果宿主应用已经有有效 token，建议在首次展示 XEWeb 前调用：

XESDK.preSync(new XEToken('token_key', 'token_value'))

该方法会等待 ArkWeb 初始化完成后同步 Cookie。

同步和刷新

const success: boolean = XESDK.sync(
  new XEToken('token_key', 'token_value')
)

在收到 LOGIN_ACTION 时重新从业务后台获取 token 并调用 sync。如果业务需要立即刷新当前页面，可在同步成功后调用 controller.refresh()。

清除登录态

用户退出登录、切换账号或 token 失效时调用：

await XESDK.syncNot()

清除登录态后再展示其他账号页面，避免不同账号之间串用 Cookie。

页面分享

调用控制器的 share() 获取当前页面分享信息：

this.controller.share()

SDK 随后通过 JsInteractType.SHARE_ACTION 回调分享数据。分享数据通常包含以下字段：

json

{
  "share_title": "小鹅通分享标题",
  "share_content": "小鹅通分享描述",
  "share_image": "分享图片链接",
  "share_link": "分享页面链接"
}

分享面板、目标应用选择和实际分发由宿主应用实现。并非所有页面都支持分享；没有收到回调时表示当前页面不可分享。

外链处理

收到 JsInteractType.NOTICE_OUT_LINK_ACTION 后，从 response.getResponseData() 获取 URL，并由宿主应用使用系统能力打开。若业务后台配置的外链需要 SDK 通知宿主处理，请在链接中增加 needoutlink=1：

text

https://example.com/path?needoutlink=1

已有查询参数时使用 &needoutlink=1。

日志开关

初始化时通过 showLog 控制 SDK 日志：

XESDK.init({
  appId: 'your_app_id',
  clientId: 'your_client_id',
  showLog: true
})

开发和联调阶段可开启日志，生产环境建议关闭。日志会输出到系统 Hilog，标签为 @xe/webcore。

常见问题

Q：页面打开后没有登录态怎么办？

确认 XESDK.init 已在创建 XEWeb 前调用，appId、clientId 和 token 均有效，并在首次展示前使用 preSync 或 sync。收到 LOGIN_ACTION 后必须重新同步最新 token。

Q：切换账号后仍显示上一个账号的内容怎么办？

切换账号或退出登录时先执行 await XESDK.syncNot()，再为新账号调用 XESDK.sync，然后刷新或重新创建 Web 页面。

Q：为什么点击分享没有回调？

部分页面不支持分享。只有当前页面支持分享且 H5 返回数据时，才会触发 SHARE_ACTION。

Q：如何处理系统返回键？

在页面容器的 onBackPressed 中调用 controller.mBackward()。返回 true 表示 SDK 已处理全屏退出或 Web 历史回退，返回 false 时再交给宿主页面栈处理。

小鹅通SDK-鸿蒙端接入文档 ​

产品简介 ​

SDK 基本信息 ​

前置条件 ​

安装 SDK ​

参数与 URL ​

SDK 参数名词解释 ​

初始化参数 ​

SDK URL 链接配置规则 ​

权限配置 ​

初始化 SDK ​

展示 Web 页面 ​

XEWebOptions 常用配置 ​

处理 SDK 回调 ​

处理 Web 页面事件 ​

页面组件示例 ​

登录态同步 ​

预同步 ​

同步和刷新 ​

清除登录态 ​

页面分享 ​

外链处理 ​

日志开关 ​

常见问题 ​

小鹅通SDK-鸿蒙端接入文档

产品简介

SDK 基本信息

前置条件

安装 SDK

参数与 URL

SDK 参数名词解释

初始化参数

SDK URL 链接配置规则

权限配置

初始化 SDK

展示 Web 页面

XEWebOptions 常用配置

处理 SDK 回调

处理 Web 页面事件

页面组件示例

登录态同步

预同步

同步和刷新

清除登录态

页面分享

外链处理

日志开关

常见问题