@xybplugins/xyb-agent

v0.0.20

Published

4 days ago

湘易办功能集成JSSDK

Downloads

1,357

0High
0Medium
0Low

dansemacabre

xybAgent SDK文档

最新版本：2.0.10

使用场景：

湘易办JSSDK为h5微应用/uni-app应用提供了数据追踪埋点等业务API（会持续扩展底层通用组件的适配能力），帮助开发者相关业务场景实现。此文档面向开发者介绍该JSSDK如何使用及相关注意事项。

兼容性说明：

适配环境名词说明

以下文中所指的环境释义
湘易办APP-小程序：湘易办APP内的小程序
湘易办APP-小程序-webview：湘易办小程序内通过webview嵌套的H5页面
湘易办APP-webview：湘易办APP通过webview嵌套的H5页面
三方小程序：微信/支付宝/百度/今日头条等其他小程序环境（包含其使用webview嵌套的H5）

范围说明

该JSSDK仅支持在湘易办小程序、湘易办小程序嵌套的H5、湘易办APP嵌套的H5中使用

| 环境名称 | 是否支持 | 最低版本号 | 备注 | |:-------------------|------|-------|------------| | 湘易办APP-小程序 | 是 | 1.1.4 | 完全支持 | | 湘易办APP-小程序-webview | 是 | 1.1.8 | 完全支持 | | 湘易办APP-webview | 是 | 2.0.0 | 部分支持，持续迭代中 | | 三方小程序 | 否 | -- | 不支持 |

注意事项：

SDK有使用ES6语法，若使用环境非uni-app的话，需支持babel等兼容工具，更建议项目切换到uni-app进行搭配使用
自动上报页面事项ID：在页面切换时，会自动进行页面事项ID上报；且需在调用时，将页面事项ID的路径映射关系传入SDK
插件初始化默认是测试环境，请根据实际情况进行修改；(development/production)
通过小程序webview嵌套的H5，可以直接使用该SDK进行原生能力调用，但小程序的webview需要按照SDK要求进行配置
如果有使用老版本的JSSDK-C2，可能湘易办PP-WEBVIEW的环境下出现异常问题，请注意甄别使用

准备工作：

工程化：在入口文件引入SDK文件，并挂载为全局变量（推荐）

import xybAgent from '/$path/xybAgent.$version.esm.js';

// Vue2 示例 - main.js
Vue.prototype.$xybAgent = xybAgent;

// Vue3 示例 - main.js / main.ts
app.config.globalProperties.$xybAgent = xybAgent;

// uni-app 示例 - App.vue，也可以在main.js中配置，参考Vue2/Vue3实现
<script>
  onLaunch() {
  this.globalData = {
    xybAgent: xybAgent
  }
}
</script>

非工程化：在index.html，添加script标签并执行引入；会自动挂载到window上；非浏览器环境不要使用这种方式


<script src="$path/xybAgent.$version.umd.js"></script>

API使用

初始化SDK-`init` (非浏览器环境无需执行此步骤)

此API是一个异步任务，可使用async await / promise结构调用；
也可直接进行初始化动作，SDK内部有进行埋码的堆栈，当有埋点时，会自动进行埋点上报。
H5环境必须执行init动作，否则会导致埋点/其它API无法使用

入参

| 参数名 | 类型 | 必填 | 可选值 | 默认值 | 描述 | |:--------|:---------|-----|-----------------------------|---------------|:---------------------------------| | envType | String | 否 | development/ production | development | 环境类型，默认为测试环境，H5用，小程序环境下可以不需要传递 |

出参

| 参数名 | 类型 | 描述 | |:-------|:----------|---------| | result | Boolean | 初始化是否完成 |

示例-async await

const res = await this.$xybAgent.init('development')
if (res) {
  // 初始化完成
}

示例-promise

this.$xybAgent.init('development').then(res => {
  if (res) {
    // 初始化完成
  }
})

执行埋点上报-`track`

环境适配说明

| 环境类型 | 是否适配 | 适配版本（最低) | |----------------|:----:|:---------| | 湘易办小程序 | 是 | 1.1.4 | | 湘易办小程序-webview | 是 | 1.1.8 | | 湘易办 - H5 | 是 | 2.0.0 | | 三方小程序 | 否 | -- |

入参

| 参数名 | 类型 | 必填 | 描述 | |:---------|----------|-----|------| | eventID | String | 是 | 事件ID | | eventPro | Object | 是 | 埋点参数 |

出参-无
示例

this.$xybAgent.track('xyb_ksj', {
  name: "",//服务名称
  code: "",//服务编码
  aff_city_code: "",//单位编码
  aff_city_name: "",//单位名称
  rel_matter_mode: "",//是否目录
  unit_code: "",
  unit_name: "",
  user_id: "",//用户 ID
});

注意事项

对应字段必须使用埋点规范文档中的字段及字段类型，否则会导致埋点数据无法成功落库！！！！

获取AccessLink值-`getAccessLink`

此API是一个异步任务，需使用async await / promise结构获取回调值

环境适配说明

入参-无
出参-仅列出返回体内的子参数，整体是一个Object对象

| 参数名称 | 参数类型 | 参数描述 | |:-----------|:----------|:------------| | accessLink | string | AccessLink值 | | isSuccess | Boolean | 是否获取成功 |

示例-async await

const {isSuccess, accessLink} = await getAccessLink();
if (isSuccess) {
  // 获取成功
}

示例-promise

getAccessLink().then(res => {
  const {isSuccess, accessLink} = res;
  if (isSuccess) {
    // 获取成功
  }
});

调用人脸识别-`authFace`

此API是一个异步任务，需使用async await / promise结构获取回调值

环境适配说明

入参

| 参数名 | 类型 | 必填 | 描述 | |:--------|:------------|:----|:-------------| | name | String | 是 | 姓名 | | certNo | String | 是 | 证件号 | | appId | String | 是 | 申请人脸能力的appID | | sign | String | 是 | 签名 | | created | timestamp | 是 | 创建时间戳 | | nonce | String | 是 | 32位的随机数 |

出参-仅列出返回体内的子参数，整体是一个Object对象

| 参数名 | 类型 | 描述 | |:----------|-----------|------| | isSuccess | Boolean | 验证结果 | | certifyId | String | 认证ID | | portrait | base64 | 头像 | | errorMsg | String | 错误信息 |

示例-async await

const userInfo = {
  name: '张三',
  certNo: '123456789012345678',
  appId: 'xxxxxxx',
  sign: 'xxxxxx',
  created: new Date().getTime(),
  nonce: 'xxxxxxx'
}
const {isSuccess} = await this.$xybAgent.authFace(userInfo);
if (isSuccess) {
  // 验证成功
}

示例-promise

const userInfo = {
  name: '张三',
  certNo: '123456789012345678',
  appId: 'xxxxxxx',
  sign: 'xxxxxx',
  created: new Date().getTime(),
  nonce: 'xxxxxxx'
}
this.$xybAgent.authFace(userInfo).then(({isSuccess}) => {
  if (isSuccess) {
    // 验证成功
  }
})

获取当前定位信息-`getLocationInfo`

此API是一个异步任务，需使用async await / promise结构获取回调值

环境适配说明

入参-无
出参-仅列出返回体内的子参数，整体是一个Object对象

| 参数名 | 子参数名 | 类型 | 描述 | |:----------|:----------|-----------|-----------------------------| | location | | Object | 定位信息 | | | address | String | 详细位置信息 | | | district | String | 区级名称 | | | city | String | 市级名称 | | | province | String | 省级名称 | | | country | String | 国家名称 | | | adCode | String | 邮政编码 | | | cityCode | String | 城市编码 | | | latitude | Float | 纬度信息 | | | longitude | Float | 经度信息 | | isSuccess | | Boolean | 获取定位信息成功(true成功 false 失败) |

示例-async await

const {location, isSuccess} = await this.$xybAgent.getLocationInfo();
if (isSuccess) {
  // 获取定位信息成功
}

示例-promise

this.$xybAgent.getLocationInfo().then(({location, isSuccess}) => {
  if (isSuccess) {
    // 获取定位信息成功
  }
})

获取登录状态-`getLoginStatus`

此API是一个异步任务，需使用async await / promise结构获取回调值

环境适配说明

入参-无
出参-仅列出返回体内的子参数，整体是一个Object对象

| 参数名 | 类型 | 描述 | |:--------|-----------|--------------------------| | logined | Boolean | 登录状态(true登录 false 未登录) |

示例-async await

const {logined} = await this.$xybAgent.getLoginStatus();
if (logined) {
  // 已登录
}

示例-promise

this.$xybAgent.getLoginStatus().then(({logined}) => {
  if (logined) {
    // 已登录
  }
})

获取APP相关信息-`getAppInfo`

此API是一个异步任务，需使用async await / promise结构获取回调值

环境适配说明

入参-无
出参-仅列出返回体内的子参数，整体是一个Object对象

| 参数名 | 类型 | 描述 | |:--------------|----------|-------| | deviceModel | String | 设备型号 | | systemVersion | String | 系统版本 | | appVersion | String | app版本 | | platform | String | 平台名称 | | appName | String | app名称 | | appId | String | appId |

示例-async await

const res = await this.$xybAgent.getAppInfo();
if (res?.appId) {
  // APP相关信息
}

示例-promise

this.$xybAgent.getAppInfo().then(res => {
  if (res?.appId) {
    // APP相关信息
  }
});

二维码扫描-`scanCode`

此API是一个异步任务，需使用async await / promise结构获取回调值

环境适配说明

入参-无
出参-仅列出返回体内的子参数，整体是一个Object对象

| 参数名 | 类型 | 描述 | |:-------|----------|-------| | result | String | 二维码内容 |

示例-async await

const {result} = await this.$xybAgent.scanCode();
if (result) {
  // 二维码内容
}

示例-promise

this.$xybAgent.scanCode().then(({result}) => {
  if (result) {
    // 二维码内容
  }
});

选择图片-`chooseImg`

此API是一个异步任务，需使用async await / promise结构获取回调值

环境适配说明

入参

| 参数名 | 类型 | 必填 | 默认值 | 可选值 | 描述 | |:-------------|-----------|-----|------------------------------|------------------------------|---------------------------| | count | Number | 否 | 9 | 1-9 | 最多选择图片数量 | | sizeType | Array | 否 | ['original', 'compressed'] | ['original', 'compressed'] | 图片尺寸类型 | | sourceType | Array | 否 | ['album'] | ['album', 'camera'] | 图片来源 | | isCircleCrop | Boolean | 否 | false | true/false | 是否圆形裁剪 |

出参-仅列出返回体内的子参数，整体是一个Array对象

| 参数名 | 类型 | 描述 | |:---------|----------|------------| | fileName | String | 文件名 | | path | String | APP端本地文件路径 | | size | Number | 文件大小(字节) | | type | String | 文件类型 |

示例-async await

const res = await this.$xybAgent.chooseImg();
if (res.length > 0) {
  // 执行图片数据处理
}

示例-promise

this.$xybAgent.chooseImg().then(res => {
  if (res.length > 0) {
    // 执行图片数据处理
  }
})

注意事项

在湘易办APP-湘易办小程序-H5 中执行的选择图片，业务侧无法使用对应的临时文件路径执行上传动作（浏览器权限问题导致）
在湘易办APP-湘易办小程序-H5 中可结合使用this.$xybAgent.fileUpload 进行搭配上传；具体查阅当前文档

图片预览-`imgPreview`

环境适配说明

| 环境类型 | 是否适配 | 适配版本（最低) | |----------------|:----:|:---------| | 湘易办小程序 | 是 | 1.1.4 | | 湘易办小程序-webview | 是 | 1.1.8 | | 湘易办 - H5 | 否 | -- | | 三方小程序 | 否 | -- |

入参

| 参数名 | 类型 | 必填 | 描述 | |:--------|----------|-----|-------------| | url | Array | 是 | 图片预览的链接地址清单 | | current | String | 是 | 默认显示的图片链接地址 |

出参-无
示例

this.$xybAgent.imgPreview(dataInfo);

选择本地文件-`chooseLocalFile`

此API是一个异步任务，需使用async await / promise结构获取回调值

环境适配说明

入参-无
出参-仅列出返回体内的子参数，整体是一个Object对象

| 参数名 | 类型 | 描述 | |:---------|----------|-----------| | path | String | 选中的文件本地路径 | | size | Number | 文件大小(字节) | | type | String | 文件类型 | | fileName | String | 文件名 |

示例-async await

const res = await this.$xybAgent.chooseLocalFile();
if (res?.path) {
  // 执行文件数据处理
}

示例-promise

this.$xybAgent.chooseFile().then(res => {
  if (res?.path) {
    // 执行文件数据处理
  }
});

文件上传-`fileUpload`

此API是一个异步任务，需使用async await / promise结构获取回调值

环境适配说明

入参

| 参数名 | 子参数名 | 类型 | 必填 | 描述 | |:---------|------|-----------|-----|-----------------------------| | source | | String | 是 | 文件信息 | | | path | String | 是 | 文件的本地临时路径 | | | type | String | 是 | 文件类型 | | | size | Number | 是 | 文件大小 | | url | | String | 否 | 文件上传接口地址 | | headers | | Object | 否 | 文件上传时的自定义请求头 | | formdata | | Object | 否 | 文件上传时的额外参数（formData携带的额外参数） | | name | | String | 否 | 上传的文件对应的key名默认为file |

出参

| 参数名 | 子参数 | 类型 | 描述 | |-----------|-----|-----------|----------------------| | resultObj | | Object | 文件上传的结果（业务侧接口定义的返回体） | | isSuccess | | Boolean | 文件上传是否成功 | | errorMsg | | String | 错误信息 |

示例-async await

const dataInfo = {
  source: {
    path: 'xxxxxx',
    type: 'image/png', // 具体看业务侧选择的文件类型而定！！！！
    size: xxxxxx
  },
  url: 'https://www.xxx.xxx.com/xxxxxx',
  headers: {},
  formdata: {},
  name: 'file'
}
const res = await this.$xybAgent.fileUpload(dataInfo);
if (res?.isSuccess) {
  // 文件上传成功
}

示例-promise

const dataInfo = {
  source: {
    path: 'xxxxxx',
    type: 'image/png', // 具体看业务侧选择的文件类型而定！！！！
    size: xxxxxx
  },
  url: 'https://www.xxx.xxx.com/xxxxxx',
  headers: {},
  formdata: {},
  name: 'file'
}
this.$xybAgent.fileUpload(dataInfo).then(res => {
  if (res?.isSuccess) {
    // 文件上传成功
  }
});

文件下载-`fileDownload`

此API是一个异步任务，需使用async await / promise结构获取回调值

环境适配说明

入参

| 参数名 | 类型 | 必填 | 描述 | |:-----|----------|-----|---------------------| | url | String | 是 | 文件地址 | | name | String | 是 | 文件名 （必须包含文件后缀名） |

出参

| 参数名 | 子参数 | 类型 | 描述 | |-----------|------|-----------|----------| | resultObj | | Object | 文件下载结果 | | | path | String | 文件下载路径 | | isSuccess | | Boolean | 文件下载是否成功 | | errorMsg | | String | 错误信息 |

示例-async await

const dataInfo = {
  url: 'https://www.xxx.xxx.com/xxxx.pdf',
  name: 'xxxx.pdf'
};
const res = await this.$xybAgent.fileDownload(dataInfo);
if (res?.isSuccess) {
  // 文件下载成功
}

示例-promise

const dataInfo = {
  url: 'https://www.xxx.xxx.com/xxxx.pdf',
  name: 'xxxx.pdf'
};
this.$xybAgent.fileDownload(dataInfo).then(res => {
  if (res?.isSuccess) {
    // 文件下载成功
  }
});

注意事项：

只有pdf、图片、world等标准可查看文档才会显示在【湘易办APP】-【我的】-【我的服务】-【我的下载】中
zip等相关文件不会在【我的下载】中展示

文件预览-`filePreview`

该API为单向事件，无回调事件

环境适配说明

入参

| 参数名 | 类型 | 必填 | 描述 | |:----|----------|-----|-----------| | url | String | 是 | 文件预览的链接地址 |

出参-无
示例

const fileInfo = {
  url: 'http://localhost:8080'
}
this.$xybAgent.filePreview(fileInfo);

打开本地文件- `openLocalFile`

环境适配说明

入参

| 参数名 | 类型 | 必填 | 描述 | |:----------|----------|-----|------| | localPath | String | 是 | 文件路径 |

出参-无
示例

const fileInfo = {
  localPath: '/storage/emulated/0/Download/test.pdf'
}
this.$xybAgent.openLocalFile(fileInfo)

打开第三方文件-`openThirdFile`

环境适配说明

入参

| 参数名 | 类型 | 必填 | 描述 | |:-----|----------|-----|------| | path | String | 是 | 文件路径 |

出参-无
示例

const fileInfo = {
  path: '/storage/emulated/0/Download/test.pdf'
};
this.$xybAgent.openThirdFile(fileInfo);

上报页面事项ID-`sendMatterId`

环境适配说明

入参

| 参数名 | 类型 | 必填 | 描述 | |:----|----------|-----|------| | id | String | 是 | 事项ID |

出参-无
示例

const matterId = 'xxxxx';
this.$xybAgent.sendMatterId(matterId);

自动上报页面事项ID-`autoSendMatterId`

环境适配说明

入参

| 参数名 | 类型 | 必填 | 描述 | |:-------|----------|-----|------| | idList | Object | 是 | 事项ID |

出参-无
示例

const matterIdList = {
  'page/index/index': 'xxxx',
  'page/index/details': 'xxx'
}
this.$xybAgent.autoSendMatterId(matterIdList);

注意事项

idList对象，内部是页面路径:页面事项ID
强烈建议在App.onLaunch生命周期中调用，否则会导致SDK无法执行自动上报
若页面路径业务侧未执行路径映射传递，SDK内部会自动上报空字符

主动打开APP评价弹窗/页面-`showComment`

此API是一个异步任务，需使用async await / promise结构获取回调值

环境适配说明

入参

| 参数名 | 类型 | 必填 | 描述 | |:---------|----------|-----|--------| | matterId | String | 是 | 页面事项ID |

出参-仅列出返回体内的子参数，整体是一个Object对象

| 参数名 | 类型 | 描述 | |:----------|-----------|---------------| | msg | String | 提示信息 | | isSuccess | Boolean | 是否成功打开评价弹窗/页面 |

示例-async await

const {isSuccess} = await this.$xybAgent.showComment(dataInfo);
if (isSuccess) {
  // 打开评价弹窗/页面成功
}

示例-promise

this.$xybAgent.showComment(dataInfo).then(({isSuccess}) => {
  if (isSuccess) {
    // 打开评价弹窗/页面成功
  }
})

切换APP屏幕常亮状态-`setScreenLight`

环境适配说明

入参

| 参数名 | 类型 | 必填 | 描述 | |:-----|-----------|-----|----------| | isOn | Boolean | 是 | 是否开启屏幕常亮 |

出参-无
示例

this.$xybAgent.setScreenLight(true);

禁止截屏-`forbidScreenShot`

环境适配说明

此API是一个异步任务，需使用async await / promise结构获取回调值

入参-无
出参-仅列出返回体内的子参数，整体是一个Object对象

| 参数名 | 类型 | 描述 | |:----------|-----------|----------| | isSuccess | Boolean | 是否成功禁止截屏 |

示例-async await

const {isSuccess} = await this.$xybAgent.forbidScreenShot();
if (isSuccess) {
  // 禁止截屏成功
}

示例-promise

this.$xybAgent.forbidScreenShot().then(({isSuccess}) => {
  if (isSuccess) {
    // 禁止截屏成功
  }
});

拨打电话-`callPhone`

环境适配说明

入参

| 参数名 | 类型 | 必填 | 描述 | |:------|----------|-----|--------| | phone | String | 是 | 拨号的手机号 |

出参-无
示例

const phone = 'xxxxxxxxxx';
this.$xybAgent.callPhone(phone);

获取APP缓存大小-`getCacheSize`

此API是一个异步任务，需使用async await / promise结构获取回调值

环境适配说明

入参-无
出参-仅列出返回体内的子参数，整体是一个Object对象

| 参数名 | 类型 | 描述 | |:----------|----------|------| | cacheSize | String | 缓存大小 |

示例-async await

const {cacheSize} = await this.$xybAgent.getCacheSize();
if (cacheSize) {
  // 执行缓存数据处理
}

示例-promise

this.$xybAgent.getCacheSize().then(({cacheSize}) => {
  if (cacheSize) {
    // 执行缓存数据处理
  }
});

复制指定文字到剪切板-`copyToClipboard`

环境适配说明

入参

| 参数名 | 类型 | 必填 | 描述 | |:-----|----------|-----|---------------| | text | String | 是 | 需要复制到剪切板的文字内容 |

出参-无
示例

const text = '需要复制到剪切板的文字内容';
this.$xybAgent.copyToClipboard(text);

发送消息给其他小程序-`postMsgToOtherApp`

此API是一个异步任务，需使用async await / promise结构获取回调值

环境适配说明

入参

| 参数名 | 类型 | 必填 | 描述 | |:----------|----------|-----|--------------| | toAppCode | String | 是 | 接收消息的小程序应用编码 | | appCode | String | 是 | 发送消息的小程序应用编码 | | extraData | Object | 否 | 消息数据内容 |

出参-仅列出返回体内的子参数，整体是一个Object对象

| 参数名 | 类型 | 描述 | |:----------|-----------|----------| | isSuccess | Boolean | 是否成功发送消息 | | msg | String | 成功/错误信息 |

示例-async await

const msgInfo = {
  toAppCode: 'xxxx',
  appCode: 'xxxx',
  extraData: {
    key: 'value'
  }
}
const {isSuccess} = await this.$xybAgent.postMsgToOtherApp(msgInfo);
if (isSuccess) {
  // 发送消息成功
}

示例-promise

const msgInfo = {
  toAppCode: 'xxxx',
  appCode: 'xxxx',
  extraData: {
    key: 'value'
  }
}
this.$xybAgent.postMsgToOtherApp(msgInfo).then(({isSuccess}) => {
  if (isSuccess) {
    // 发送消息成功
  }
});

接收其他小程序发来的消息-`uni.onNativeEventReceive`

此API是一个异步任务，需使用async await / promise结构获取回调值

环境适配说明

入参-无
出参-仅列出返回体内的子参数，整体是一个Object对象

| 参数名 | 类型 | 描述 | |:------|----------|--------| | event | Object | 事件来源 | | data | Object | 事件数据信息 |

示例-async await

const {event, data} = await uni.onNativeEventReceive();
if (event === 'NativeMessageFromMiniApp') {
  // 执行事件处理
}

示例-promise

uni.onNativeEventReceive().then(({event, data}) => {
  if (event === 'NativeMessageFromMiniApp') {
    // 执行事件处理
  }
});

注意事项

此API是UNI本身就拥有的API，具体用法可参考UNI官方文档
此API是一个监听消息事件的API，在组件销毁时，建议off销毁掉,不然可能存在内存泄露问题
监听建议放置到App.onLaunch生命周期处使用

打开某个APP（第三方）-`openApp`

此API是一个异步任务，需使用async await / promise结构获取回调值

环境适配说明

入参

| 参数名 | 类型 | 必填 | 描述 | |:----|----------|-----|-----------| | url | String | 是 | 打开APP的url |

出参-仅列出返回体内的子参数，整体是一个Object对象

| 参数名 | 类型 | 描述 | |:----------|-----------|---------------------------------------| | isSuccess | Boolean | 是否成功打开APP(true 打开app，false 没有安装app) |

示例-async await

const dataInfo = {
  url: 'https://www.baidu.com'
}
const {isSuccess} = await this.$xybAgent.openApp(dataInfo);
if (isSuccess) {
  // 打开第三方APP成功
}

示例-promise

const dataInfo = {
  url: 'https://www.baidu.com'
}
this.$xybAgent.openApp(dataInfo).then(({isSuccess}) => {
  if (isSuccess) {
    // 打开第三方APP成功
  }
});

打开湘易办内指定的小程序-`openXybApp`

环境适配说明

入参

| 参数名 | 类型 | 必填 | 描述 | |:----------|----------|-----|---------------------------| | appCode | String | 是 | 小程序的APPCode，不是uni开头的APPID | | pageUrl | String | 是 | 小程序指定页面路径 | | extraData | Object | 否 | 携带到另外一个小程序的额外数据信息 |

出参-无
示例

this.$xybAgent.openXybApp({
  appCode: 'xxxxx', // 在小程序发布系统注册的时候填写的编码
  pageUrl: '/pages/index/index', // 目标小程序的页面路径
  extraData: {} // 额外携带过去的参数信息
});

注意事项

需要接收其他小程序携带过来的数据信息时，需要在App.onLaunch生命周期中添加监听事件来处理对应的数据信息，示例代码如下：

App({
  onLaunch: function (options) {
    uni.onNativeEventReceive((event, data) => {
      // 执行对应的判断和数据处理
    })
  }
});

小程序webview嵌套的H5调用SDK能力指南

SDK提供了一个API，供小程序webview嵌套的H5调用，具体配置说明如下：

小程序的webview配置：


<template>
  <web-view id="webview" src="yourPageUrl" @message="formatMessageInfo"></web-view>
</template>

<script>
  export default {
    methods: {

      /**
       * @description: 处理webview页面传递过来的消息内容
       */
      formatMessageInfo(event) {
        this.$xybAgent.initMessage(event, this.$xybAgent, this)
      }
    }
  }
</script>

参数说明

| 参数名 | 类型 | 描述 | |:---------|:-------|:--------------| | event | Object | 原生事件信息 | | xybAgent | Object | SDK对象实例 | | this | Object | 当前webview实例对象 |

注意事项

web-view 组件一定要有 id 而且 id 必须是 webview，否则会导致小程序嵌套的H5无法正常调用jssdk

控制胶囊按钮的下拉菜单显示-`menuBtnConfig`

此API是一个异步任务，需使用async await / promise结构获取回调值

环境适配说明

入参

| 参数名 | 子参数 | 类型 | 默认值 | 必填 | 描述 | |:---------|----------|-----------|-----------------|-----|----------------------------------| | share | | Object | {show: false} | 否 | 分享按钮配置信息 | | | show | Boolean | false | 否 | 是否显示分享按钮 | | | code | String | -- | 否 | 页面/专区/事项编码 (show=true时必填) | | | matterID | String | -- | 否 | 页面/专区/事项编码 (show=true时必填) | | type | String | -- | 否 | 事项-4；小程序-5 (show=true时必填) | | comment | | Object | {show: false} | 否 | 评论按钮配置信息 | | | show | Boolean | false | 否 | 是否显示评论按钮 | | | code | String | -- | 否 | 页面/专区/事项编码 (show=true时必填) | | | matterID | String | -- | 否 | 页面/专区/事项编码 (show=true时必填) | | type | String | -- | 否 | 事项-4；小程序-5 (show=true时必填) | | favorite | | Object | {show: true} | 否 | 收藏按钮配置信息 | | | show | Boolean | true | 否 | 是否显示收藏按钮 |

返回值

仅列出返回体内的子参数，整体是一个Object对象

| 参数名 | 类型 | 描述 | |:----------|-----------|----------------| | isSuccess | Boolean | 更改胶囊按钮下拉菜单是否成功 |

示例-async await

const {isSuccess} = await this.$xybAgent.menuBtnConfig({
  share: {
    show: true,
    type: 4,
    code: 'xxxxxx'
  },
  comment: {
    show: true,
    type: 4,
    code: 'xxxxxx'
  },
  favorite: {
    show: true
  }
})
if (isSuccess) {
  // 配置成功
}

示例-promise

this.$xybAgent.menuBtnConfig({
  share: {
    show: true,
    type: 4,
    code: 'xxxxxx'
  },
  comment: {
    show: true,
    type: 4,
    code: 'xxxxxx'
  },
  favorite: {
    show: true
  }
}).then(({isSuccess}) => {
  if (isSuccess) {
    // 配置成功
  }
})

接口请求-`request`

SDK提供了一个用于接口请求的方法，使用方式与uni.request一致，但是增加了请求拦截器、请求头公共配置

环境适配说明

示例-promise

this.$xybAgent.request({
  url: '/api/v1/user/info',// 若未配置公共请求基础URI，需要设置完整的请求地址
  method: 'POST',
  data: {
    name: '张三'
  },
  headers: {
    'ClientID': 'xxx' // 若接口有设置自定义headers，会与公共配置的请求头进行叠加，若有配置项与公共请求头一致时，才会执行覆盖操作
  },
  ignore: true, // 忽略请求拦截器
}).then(res => {
  // 请求成功
}).catch(e => {
  console.log(e)
});

示例-async/await

try {
  const res = await this.$xybAgent.request({
    url: '/api/v1/user/info', // 若未配置公共请求基础URI，需要设置完整的请求地址
    method: 'POST',
    data: {
      name: '张三'
    },
    headers: {
      'ClientID': 'xxx' // 若接口有设置自定义headers，会与公共配置的请求头进行叠加，若有配置项与公共请求头一致时，才会执行覆盖操作
    },
    ignore: true, // 忽略请求拦截器
  });
  if (res) {
    // 请求成功
  }
} catch (e) {
  console.log(e);
}

请求拦截器-`interceptor`

请求拦截器，主要服务于xybAgent.request，用于拦截请求，对请求参数进行修改，对请求返回数据进行预处理。若配置不是函数式对象，SDK内部不会调用该拦截器配置，请勿配置非函数式对象无需执行请求拦截的接口，可以在请求时，增加字段ignore:true

环境适配说明

示例-request

在main.js 全局配置方案

import xybAgent from './$DIR/xybAgent-$VERSION.esm.js';

xybAgent.interceptor.request = (config) => {
  if (!config.headers.token) {
    return false;
  }
  return config;
}

示例-response

在main.js 全局配置方案

import xybAgent from './$DIR/xybAgent-$VERSION.esm.js';

xybAgent.interceptor.response = (res) => {
  const {data, statusCode} = res?.data || {};
  if (statusCode === 401) {
    return false;
  }
  if (statusCode === 200) {
    return data || true;
  }
}

请求公共配置信息-`defaults`

此API主要用于配置公共请求的基础URI&请求头等信息

环境适配说明

示例-baseURL

xybAgent.defaults.baseURL = 'https://www.baidu.com';

示例-headers

xybAgent.defaults.headers = {
  'Content-Type': 'application/json',
  'Authorization': 'xxxx'
}

打开微信小程序-`openWechatMiniApp`

此API是一个异步任务，需使用async await / promise结构获取回调值

环境适配说明

入参

| 参数名 | 类型 | 默认值 | 必填 | 描述 | |:----------------|----------|-----|-----|-----------------------| | miniProgramType | Number | -- | 是 | 小程序类型（0：正式 1：开发 2：体验） | | userName | String | -- | 是 | 小程序的账号原始ID，gh_开头的ID值 | | path | String | -- | 否 | 打开的页面路径 |

出参-仅列出返回体内的子参数，整体是一个Object对象

| 参数名 | 类型 | 描述 | |:----------|-----------|-----------------------| | isSuccess | Boolean | 打开小程序是否成功 | | code | String | 小程序返回的错误码(-1表示未安装客户端) |

示例-async await

const {isSuccess, code} = await this.$xybAgent.openWechatMiniApp({
  miniProgramType: 0,
  userName: 'gh_xxxxxx',
  path: '/pages/index/index'
})
if (isSuccess) {
  // 打开小程序成功
}

示例-promise

this.$xybAgent.openWechatMiniApp({
  miniProgramType: 0,
  userName: 'gh_xxxxxx',
  path: '/pages/index/index'
}).then(({isSuccess, code}) => {
  if (isSuccess) {
    // 打开小程序成功
  }
})

打开支付宝小程序-`openAlipayMiniApp`

此API是一个异步任务，需使用async await / promise结构获取回调值

环境适配说明

入参

| 参数名 | 类型 | 默认值 | 必填 | 描述 | |:-----|----------|-----|-----|:--------| | path | String | -- | 否 | 打开的页面路径 |

出参

示例-async await

const {isSuccess, code} = await this.$xybAgent.openAlipayMiniApp('/pages/index/index')
if (isSuccess) {
  // 打开小程序成功
}

示例-promise

this.$xybAgent.openAlipayMiniApp('/pages/index/index').then(({isSuccess, code}) => {
  if (isSuccess) {
    // 打开小程序成功
  }
})

目的地导航 - `startNavigation`

该任务是一个单向任务，无回调值信息
该任务主要用于湘易办小程序/湘易办内嵌的H5页面，给用户提供快捷导航能力

环境适配说明

| 环境类型 | 是否适配 | 适配版本（最低) | |----------------|:----:|:---------| | 湘易办小程序 | 是 | 2.0.0 | | 湘易办小程序-webview | 是 | 2.0.0 | | 湘易办 - H5 | 是 | 2.0.0 | | 三方小程序 | 否 | -- |

入参

| 参数名 | 类型 | 必填 | 描述 | |:-----------|----------|-----|--------------------------------------| | lat | String | 是 | 纬度 | | lng | String | 是 | 经度 | | address | String | 是 | 目的地地址信息 | | dinateType | String | 是 | 坐标系类型，默认值：GCJ02，可选值：BD09、WGS84 |

出参 - 无
示例

this.$xybAgent.startNavigation({
  lat: '22.542',
  lng: '113.942',
  address: '广东省深圳市西南部深圳湾',
  dinateType: 'GCJ02'
});

是否自动恢复胶囊按钮默认配置 - `autoUpdate`

该任务是一个单向任务，无回调值信息
该任务主要用于湘易办小程序/湘易办内嵌的H5页面，用于恢复胶囊按钮的默认配置信息

环境适配说明

| 环境类型 | 是否适配 | 适配版本（最低) | |----------------|:----:|:---------| | 湘易办小程序 | 是 | 2.0.9 | | 湘易办小程序-webview | 是 | 2.0.9 | | 湘易办 - H5 | 否 | -- | | 三方小程序 | 否 | -- |

入参

| 参数名 | 类型 | 必填 | 默认值 | 描述 | |:-----------|----------|-----|--------|-------------------------| | autoUpdate | Number | 否 | true | 是否自动恢复默认配置（小程序不建议更改此配置） |

出参 - 无
示例

// 页面切换时恢复默认配置
xybAgent.autoUpdate = true;

// 页面切换时保留现有配置
xybAgent.autoUpdate = false;

注意事项

小程序不建议更改此配置，否则引起的一切问题，SDK不予以处理；推荐仅用于uni-app开发的H5项目使用

是否需要进行胶囊按钮自动化配置 - `autoConfigMenuBtn`

该任务是一个单向任务，无回调值信息
该任务主要用于湘易办小程序/湘易办内嵌的H5页面，用于自动执行胶囊按钮的配置
SDK会自动获取地址栏上的事项编码，若无事项编码，会恢复成默认配置

环境适配说明

入参

| 参数名 | 类型 | 必填 | 默认值 | 描述 | |:------------------|----------|-----|--------|-----------------| | autoConfigMenuBtn | Number | 否 | true | 是否需要进行胶囊按钮自动化配置 |

出参 - 无
示例

// 页面切换时，默认需要进行胶囊按钮自动化配置
xybAgent.autoConfigMenuBtn = true;

// 页面切换时，不需要自动化配置胶囊按钮配置
xybAgent.autoConfigMenuBtn = false;

注意事项

此配置不能与autoUpdate=false进行组合使用，推荐都为默认值（true)，否则由此造成的一切损失，由业务侧自行承担结果

添加日历日程 - `addCalendarEvent`

该任务是一个异步任务，有回调值信息
该任务主要用于湘易办小程序/湘易办内嵌的H5页面，用于添加日历日程信息

环境适配说明

入参

| 参数名 | 类型 | 必填 | 描述 | |:-------------|-------------|-- | ---|----------------| | title | String | 是 | 行程标题 | | startTime | timeStamp | 是 | 开始时间 (时间戳) | | endTime | timeStamp | 是 | 结束时间 (时间戳) | | reminderTime | Number | 否 | 即距开始时间提前x分钟提醒，不填时，默认为不提醒 |

出参

| 参数名 | 类型 | 描述 | |:----------|-----------|----------| | isSuccess | Boolean | 创建行程是否成功 | | errorMsg | String | 错误消息内容 | | eventID | String | 行程ID |

示例 - async、await 模式

const res = await this.$xybAgent.addCalendarEvent({
  title: '日历行程标题',
  startTime: new Date('2026/01/01 00:00:00').getTime(),
  endTime: new Date(`2026/01/01 00:05:00`).getTime(),
  reminderTime: 5
});
if (res?.isSuccess) {
  // 添加日历日程信息完成
}

示例 - promise 模式

this.$xybAgent.addCalendarEvent({
  title: '日历行程标题',
  startTime: new Date('2026/01/01 00:00:00').getTime(),
  endTime: new Date(`2026/01/01 00:05:00`).getTime(),
  reminderTime: 5
}).then(res => {
  if (res?.isSuccess) {
    // 添加日历日程信息完成
  }
});

查看日历日程信息 - `queryCalendarEvent`

该任务是一个异步任务，有回调值信息
该任务主要用于湘易办小程序/湘易办内嵌的H5页面，用于添加日历日程信息

环境适配说明

入参

| 参数名 | 类型 | 必填 | 描述 | |:--------|----------|-----|------| | eventID | String | 是 | 日程ID |

出参

| 参数名 | 子参数名 | 类型 | 描述 | |:----------|--------------|-------------|----------------| | items | | | | | | itemID | String | 日程ID | | | title | String | 日程标题 | | | startTime | Timestamp | 开始时间 (时间戳) | | | endTime | Timestamp | 结束时间 (时间戳) | | | reminderTime | Number | 距离开始时间x分钟提醒 | | isSuccess | | Boolean | 创建行程是否成功 | | errorMsg | | String | 错误消息内容 |

示例 - async、await 模式

const res = await this.$xybAgent.queryCalendarEvent({
  eventID: 'xxx'
});
if (res?.isSuccess) {
  // 查询日历日程信息完成
}

示例 - promise 模式

this.$xybAgent.addCalendarEvent({
  eventID: 'xxx'
}).then(res => {
  if (res?.isSuccess) {
    // 查询日历日程信息完成
  }
});

删除日历日程信息 - `deleteCalendarEvent`

该任务是一个异步任务，有回调值信息
该任务主要用于湘易办小程序/湘易办内嵌的H5页面，用于删除日历日程信息

环境适配说明

入参

| 参数名 | 类型 | 必填 | 描述 | |:--------|----------|-----|------| | eventID | String | 是 | 日程ID |

出参

| 参数名 | 类型 | 描述 | |:----------|-----------|----------| | isSuccess | Boolean | 创建行程是否成功 | | errorMsg | String | 错误消息内容 |

示例 - async、await 模式

const res = await this.$xybAgent.deleteCalendarEvent({
  eventID: 'xxx'
});
if (res?.isSuccess) {
  // 删除日历日程信息完成
}

示例 - promise 模式

this.$xybAgent.deleteCalendarEvent({
  eventID: 'xxx'
}).then(res => {
  if (res?.isSuccess) {
    // 删除日历日程信息完成
  }
});

更新日志

`2.0.10`

最后更新时间：2025/12/09
更新内容：

增加日历行程添加API
增加日历行程查看API
增加日历行程删除API
优化部分事件的内部逻辑

文件

xybAgent-2.0.10 点击下载

`2.0.9`

最后更新时间：2025/12/01
更新内容：

优化IOS下执行文件下载时，无法获取到多次回调的情况

文件

xybAgent-2.0.9 点击下载

`2.0.8`

最后更新时间：2025/11/24
更新内容：

增加胶囊按钮自动化配置功能 - 当地址栏存在xybModuleCode参数，SDK内部会自动上报事项的分享、评价配置（默认开启）
增加胶囊按钮自动化配置开关功能 - 通过配置 xybAgent.autoConfigMenuBtn = true / false 来控制是否需要完成自动化配置（默认值true)

文件

xybAgent-2.0.8 点击下载

`2.0.7`

最后更新时间：2025/11/20
更新内容：

优化鸿蒙下获取位置信息时，可能因系统底层差异导致返回的数据结构与API文档不一致的问题
优化H5埋点数据上报时的日志信息打印，会准确告知用户侧是否上报到生产环境
修复屏蔽胶囊按钮自动重置的BUG，默认把重置功能给屏蔽了的问题

文件

xybAgent-2.0.7 点击下载

`2.0.5`

最后更新时间：2025/11/03
更新内容：

增加配置项，屏蔽整个应用的胶囊按钮自动重置的动作（只适用于基于uni-app开发的H5应用，且整个应用只有一个事项编码时使用）

文件

xybAgent-2.0.5 点击下载

`2.0.4`

最后更新时间：2025/11/03
更新内容：

修复鸿蒙下的湘易办小程序无法与Webview嵌套的H5进行数据通信的问题
修正部分业务可能因withCredentials导致接口跨域的问题

文件

xybAgent-2.0.4 点击下载

`2.0.1`

最后更新时间：2025/10/15
更新内容：

优化逻辑，修复小程序与H5进行事件通讯时，部分事件失效的问题
优化事件调用的效率

文件

xybAgent-2.0.1 点击下载

`2.0.0`

最后更新时间：2025/09/26
更新内容：

增加目的地导航-startNavigation能力
优化埋点上报-track事件，SDK内部直接集成部分参数处理
增加湘易办APP-H5直接调用SDK能力
优化逻辑，修复小程序webview环境调用SDK能力时，获取到的结果可能存在错乱的问题

文件

xybAgent-2.0.0 点击下载

`1.1.8`

最后更新时间：2025/09/02
更新内容：

支持湘易办向程序与小程序通过webview嵌套的H5进行数据通讯、数据交互
支持打开指定微信小程序并跳转至对应页面
支持打开支付宝小程序/微信小程序并跳转至对应页面
优化webview页面的数据回调，避免因短时间内多次调用导致的数据回传异常问题

文件

xybAgent-1.1.8 点击下载

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

xybAgent SDK文档

使用场景：

兼容性说明：

适配环境名词说明

范围说明

注意事项：

准备工作：

API使用

初始化SDK-init (非浏览器环境无需执行此步骤)

执行埋点上报-track

获取AccessLink值-getAccessLink

调用人脸识别-authFace

获取当前定位信息-getLocationInfo

获取登录状态-getLoginStatus

获取APP相关信息-getAppInfo

二维码扫描-scanCode

选择图片-chooseImg

图片预览-imgPreview

选择本地文件-chooseLocalFile

文件上传-fileUpload

文件下载-fileDownload

文件预览-filePreview

打开本地文件- openLocalFile

打开第三方文件-openThirdFile

上报页面事项ID-sendMatterId

自动上报页面事项ID-autoSendMatterId

主动打开APP评价弹窗/页面-showComment

切换APP屏幕常亮状态-setScreenLight

禁止截屏-forbidScreenShot

拨打电话-callPhone

获取APP缓存大小-getCacheSize

复制指定文字到剪切板-copyToClipboard

发送消息给其他小程序-postMsgToOtherApp

接收其他小程序发来的消息-uni.onNativeEventReceive

打开某个APP（第三方）-openApp

打开湘易办内指定的小程序-openXybApp

小程序webview嵌套的H5调用SDK能力指南

控制胶囊按钮的下拉菜单显示-menuBtnConfig

接口请求-request

请求拦截器-interceptor

请求公共配置信息-defaults

打开微信小程序-openWechatMiniApp

打开支付宝小程序-openAlipayMiniApp

目的地导航 - startNavigation

是否自动恢复胶囊按钮默认配置 - autoUpdate

是否需要进行胶囊按钮自动化配置 - autoConfigMenuBtn

添加日历日程 - addCalendarEvent

查看日历日程信息 - queryCalendarEvent

删除日历日程信息 - deleteCalendarEvent

更新日志

2.0.10

2.0.9

2.0.8

2.0.7

2.0.5

2.0.4

2.0.1

2.0.0

1.1.8

初始化SDK-`init` (非浏览器环境无需执行此步骤)

执行埋点上报-`track`

获取AccessLink值-`getAccessLink`

调用人脸识别-`authFace`

获取当前定位信息-`getLocationInfo`

获取登录状态-`getLoginStatus`

获取APP相关信息-`getAppInfo`

二维码扫描-`scanCode`

选择图片-`chooseImg`

图片预览-`imgPreview`

选择本地文件-`chooseLocalFile`

文件上传-`fileUpload`

文件下载-`fileDownload`

文件预览-`filePreview`

打开本地文件- `openLocalFile`

打开第三方文件-`openThirdFile`

上报页面事项ID-`sendMatterId`

自动上报页面事项ID-`autoSendMatterId`

主动打开APP评价弹窗/页面-`showComment`

切换APP屏幕常亮状态-`setScreenLight`

禁止截屏-`forbidScreenShot`

拨打电话-`callPhone`

获取APP缓存大小-`getCacheSize`

复制指定文字到剪切板-`copyToClipboard`

发送消息给其他小程序-`postMsgToOtherApp`

接收其他小程序发来的消息-`uni.onNativeEventReceive`

打开某个APP（第三方）-`openApp`

打开湘易办内指定的小程序-`openXybApp`

控制胶囊按钮的下拉菜单显示-`menuBtnConfig`

接口请求-`request`

请求拦截器-`interceptor`

请求公共配置信息-`defaults`

打开微信小程序-`openWechatMiniApp`

打开支付宝小程序-`openAlipayMiniApp`

目的地导航 - `startNavigation`

是否自动恢复胶囊按钮默认配置 - `autoUpdate`

是否需要进行胶囊按钮自动化配置 - `autoConfigMenuBtn`

添加日历日程 - `addCalendarEvent`

查看日历日程信息 - `queryCalendarEvent`

删除日历日程信息 - `deleteCalendarEvent`

`2.0.10`

`2.0.9`

`2.0.8`

`2.0.7`

`2.0.5`

`2.0.4`

`2.0.1`

`2.0.0`

`1.1.8`