JSSDK 快速开始
JSSDK 快速开始
本篇是《莲信 JSSDK 开发文档》的总览。JSSDK 用于在莲信客户端内的 H5 页面调用客户端原生能力。
引入 SDK
在页面中引入平台交付的 jsapi.js（部署在莲信客户端可访问的地址）后，页面将获得全局对象 matrix。
<script src="/path/to/jsapi.js"></script>matrix 对象能力总表
| 方法 | 说明 | 是否需要 config |
|---|---|---|
matrix.config(params) |
配置初始化，注入签名与权限信息 | - |
matrix.ready(handler) |
config 校验通过后回调 | - |
matrix.error(handler) |
config 校验失败回调 | - |
matrix.getAuthCode(params) |
获取用户授权码（OAuth2 code） | 否 |
matrix.setNavBarVisible(params) |
控制导航栏显隐 | 是 |
matrix.setMenuItemsVisible(params) |
控制菜单项显隐 | 是 |
matrix.setWindowFloating(params) |
进入浮窗 | 是 |
matrix.closeApp(params) |
关闭当前页面 | 是 |
matrix.openInBrowser(params) |
在系统浏览器打开链接 | 是 |
matrix.getDeviceType(params) |
获取设备类型 | 是 |
matrix.getCurrentGroupId(params) |
获取当前群 ID | 是 |
matrix.getLocation(params) |
获取当前位置 | 是 |
matrix.openChat(params) |
打开聊天会话 | 是 |
matrix.chooseChat(params) |
从会话列表选择会话 | 是 |
matrix.on(name, handler) / off |
监听 / 取消监听客户端事件 | - |
通信机制
SDK 通过 MatrixJSSDK.postMessage 与客户端原生容器桥接，调用返回以 requestId 关联；客户端事件以 matrix:<事件名> CustomEvent 派发，可用 matrix.on / matrix.off 订阅。
统一错误结构
所有接口失败回调均收到统一错误对象：
{
"code": 10001,
"message": "错误描述",
"data": {}
}code：错误码，平台内部错误时可能为空message：错误描述data：附加数据（可能缺失）
config 初始化
配置初始化
matrix.config(params)
初始化 JSSDK 配置，验证签名并授权可调用的接口。配置成功后通过 matrix.ready() 回调获取结果。
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| appKey | String | 必填 | 应用标识 |
| timestamp | Number | 必填 | 时间戳（毫秒） |
| nonceStr | String | 必填 | 随机字符串 |
| signature | String | 必填 | 签名（由应用后端生成） |
| url | String | 必填 | 签名的页面 URL（不含 hash） |
| jsApiList | Array | 必填 | 需要授权的接口列表 |
调用示例
matrix.config({
appKey: 'your_app_key',
timestamp: 1234567890123,
nonceStr: 'random_string',
signature: 'generated_signature',
url: 'https://your-domain.com/page',
jsApiList: ['openChat', 'chooseChat', 'getLocation']
});
matrix.ready(function(data) {
console.log('配置成功', data);
// data.configuredJsApis: 授权的接口列表
// data.expiresAt: 配置过期时间戳
});