JS-SDK

优质

小牛编辑

172浏览

2023-12-01

轻推JS-SDK的所有接口（config除外），可通过qt对象(也可使用jQingTui对象)来调用，参数是一个对象，除了每个接口本身需要传的参数之外，还有以下通用参数：

1. success：接口调用成功时执行的回调函数。

2. fail：接口调用失败时执行的回调函数。

3. complete：接口调用完成时执行的回调函数，无论成功或失败都会执行。

4. cancel：用户点击取消时的回调函数，仅部分有用户取消操作的api才会用到。

以上几个函数都带有一个参数，类型为对象，其中除了每个接口本身返回的数据之外，还有一个通用属性errMsg，其值格式如下：

调用成功时："xxx:ok" ，其中xxx为调用的接口名

用户取消时："xxx:cancel"，其中xxx为调用的接口名

调用失败时：其值为具体错误信息

备注：企业内部和已认证轻应用/订阅号都可以使用JS-SDK。

步骤一：引入JS文件

在需要调用JS接口的页面引入如下JS文件：http://resource.qingtui.cn/open/libs/jssdk/2.3.1/qingtui_jssdk.min.js，如需下载源文件，请右键此链接，点击“链接另存为”即可。

备注：支持使用 AMD/CMD 标准模块加载方法加载。

步骤二：加入config配置

必须在需要使用JS-SDK的每个页面加入config配置信息，且config必须在调用其他接口之前进行加载，这样config的一个过程就是鉴权。

qt.config({
    debug: true, // 开启调试模式,调用的所有api的返回值会在客户端alert出来，若要查看传入的参数，可以在pc端打开，参数信息会通过log打出，仅在pc端时才会打印。
    appId: '1234567890', // 必填，轻应用/订阅号的唯一标识
    timestamp: 1000000000, // 必填，生成签名的时间戳
    nonceStr: 'randomstr', // 必填，生成签名的随机串
    signature: 'signature001',// 必填，签名
    jsApiList: [] // 必填，需要使用的JS接口列表
});

鉴权流程：

前端页面config的签名参数signature，必须由服务器端（后台）进行签名后返回，只有返回正确的值之后前端页面才能鉴权成功。同时，服务器端签名用的noncestr和timestamp必须与qt.config中的nonceStr和timestamp相同，所以，建议config的参数timestamp、nonceStr、signature均从服务器端返回。

appId，即轻应用/订阅号的AppID，可以参考“开发前必读->开始开发->查看AppID和AppSecret”方式进行查看，查看AppID
timestamp，生成签名的时间戳。服务器端生成方式如:long timestamp = System.currentTimeMillis()
nonceStr，生成随机字符串，服务器端生成方式如:String nonceStr = UUID.randomUUID().toString()
signature，生成签名，详见附录1：JS-SDK权限签名算法
jsApiList，需要调用的JS接口列表，仅添加用到的即可，详见附录2：所有JS接口列表。如：['getLocation', 'startGeoLocation']

备注：完整的JS-SDK使用说明以及服务端JAVA的签名示例，可以参考附录5：JS-SDK使用及服务端签名示例。

步骤三：ready接口说明

无论config成功失败都会执行ready函数里面的代码，开发者如果需要在页面加载时就调用JS-SDK的接口，则可以把相关接口放在ready函数中来实现成功调用。而对于需要用户主动触发时才调用的接口，则可以直接调用，无须放在ready函数中。

qt.ready(function(){
    //无论config成功失败都会执行里面的代码，可以保证config执行完成后才执行这里的函数。
});

同时，如果config验证失败，也可以使用error接口

qt.error(function(res) {
    alert(res.errMsg);//如果config信息验证失败会执行error函数，比如：返回错误信息。当然，也可以直接开启config的debug模式来进行查看。
});

获取jsapi_ticket

请求方式： GET

请求地址： https://open.qingtui.cn/js/ticket/get?access_token=ACCESS_TOKEN

参数说明：

参数	必须	说明
access_token	是	接口调用凭证（身份令牌）

正确返回结果示例：

{
"ticket": "cb4fad2f7b",
"expires_in": 7200
}

出错返回结果示例：

{
    "errcode": -1,
    "errmsg": "系统繁忙"
}

参数说明：

参数	说明
ticket	jsapi调用时签名所需的ticket
expires_in	ticket有效期，单位为秒
errcode	错误代号
errmsg	错误信息

备注：

jsapi_ticket的有效期为7200秒，需要通过access_token来获取（参考"开发前必读->开始开发->获取access_token"，获取access_token）。由于access_token以及jsapi_ticket的API调用次数非常有限，频繁刷新会影响自身业务，开发者必须在自己的服务全局缓存access_token和jsapi_ticket。
调用此接口后，之前调用此接口获取的ticket将失效。

获取设备信息

qt.getClientInfo({
    success: function(res) {
        var type = res.type; //设备类型：android->安卓客户端,iOS->iPhone客户端,pc->PC客户端,'not QT client'->非轻推客户端
        var version = res.version; // 客户端版本
    },
});

获取网络信息

qt.getNetworkType({
    succes: function(res){
        var networkType = res.networkType; //设备网络类型，WIFI、2G、3G、4G；
    }
})

获取jsapi版本号

qt.getJsApiVersion({
    success: function(res){
        var jsApiVersion = res.jsApiVersion; //jsapi版本号 
    }
})

代发网络请求

由轻推客户端进行代发网络请求，用于解决跨域问题。仅在手机端支持，页面如果同时在PC和手机使用，请自行判断。

qt.ajax({
    url: 'http://xxx',// 必须是完整的url地址
    header: {},// 需要附加的请求头，选填
    type: 'get' || 'post',// 请求方式
    dataType: 'json',// 响应数据类型，默认json，选填
    data: {},// 请求参数
    success: function(res){
        var statusCode = res.statusCode; // 状态码, 请求的状态码例如200，404，500等
        var result = res.result; // 返回结果，如果dataTyp为json，则会自动被序列化为对象
    }
});

关闭窗口

可在网页中调用此方法，关闭轻推浏览器窗口。

qt.closeWindow()

拍照或从手机相册中选图

qt.chooseImage({
    count: 1, // 默认9
    sizeType: ['original', 'compressed'], // 可以指定是原图还是压缩图，默认二者都有
    sourceType: ['album', 'camera'], // 可以指定来源是相册还是相机，默认二者都有
    success: function (res) {
        var localIds = res.localIds; // 返回选定照片的本地ID列表，localId可以作为img标签的src属性显示图片
    }
});

预览图片

qt.previewImage({
    btns:["forward","download"], // 界面按钮，forward转发按钮，download下载按钮
    current: '', // 当前显示图片的http链接
    urls: [] // 需要预览的图片http链接列表
});

上传图片

qt.uploadImage({
  localId: '',// 需要上传的图片的本地ID，由chooseImage接口获得
  isShowProgressTips: 1, // 默认为1，显示进度提示
  success: function(res) {
    var serverId = res.serverId;
  }
});

备注：上传的文件有效期为3天，可用服务器端media/download接口下载到自己的服务器，此处获得的 serverId 即 media_id

下载图片

qt.downloadImage({
    serverId: '', // 需要下载的图片的服务器端ID，由uploadImage接口获得
    isShowProgressTips: 1, //  默认为1，显示进度提示
    success: function(res) {
      var localId = res.localId;
    }
});

裁剪图片（票务）

选择并裁剪需要识别的图片，仅支持轻推V6.2.0以上版本，接口包含：1、裁剪需要识别的图片 2、仅识别税务发票上的二维码

qt.chooseCropOCRImage({
    sourceType: ['album', 'camera'], // 相册或者相机
    title: '', // 裁剪界面显示的title
    type: 1 | 2, // 1：增值税发票 2：火车票
    success: function(res) {
      var localId = res.localId; // 本地图片id
      var qrResult = res.QRResult; // type=1时才有值
    }
});

识别图片（票务）

识别图片，仅支持轻推V6.2.0以上版本，接口包含：1、识别税务发票（识别除二维码的所有文本信息）2、识别火车票（识别除二维码的所有文本信息）

qt.ocrImage({
    localId: '', // 本地图片id
    type: 1 | 2, // 1：增值税发票 2：火车票
    success: function(res) {
      var serverId = res.serverId; // 服务端图片id
      var result = res.result; // 识别结果，为json对象
    }
});

轻推扫一扫

qt.scanQRCode({
    needResult: 1, // 默认为0，扫描结果由微信处理，1则直接返回扫描结果，
    success: function(res) {
        var result = res.resultStr;// 当needResult 为 1 时，扫码返回的结果
        console.log(result);
    }
});

获取地理位置

qt.getLocation({
    type: 'wgs84', // 默认为wgs84的gps坐标，如果要返回直接给openLocation用的火星坐标，可传入'gcj02'
    interval: 1000, // 定位间隔，若该参数大于零则代表开启连续定位
    formatAddr: false // 是否返回格式化地址信息，默认为false不返回
    success: function (res) {
        var latitude = res.latitude; // 纬度，浮点数，范围为90 ~ -90
        var longitude = res.longitude; // 经度，浮点数，范围为180 ~ -180。
        var precision = res.precision; // 位置精度
        var addr = res.addr; // 格式化的地址信息，仅当formatAddr参数为true时返回
        var id = res.id; // 连续定位的队列id，仅当开启连续定位时返回，用于停止连续定位
    }
});

停止指定连续定位

qt.stopLocation({
    id: id // 连续定位的队列id,从获取地理位置接口返回值中获得
})

停止所有连续定位

qt.stopLocation() // 与停止指定连续定位相同，仅传递id参数即可，其他通用参数仍可传递（success/fail等）

通讯录选人

qt.openContacts({
    max: 9, //人数限制，当启用多选时生效，最大数量300
    multiple: false, // 是否开启多选，默认不开启
    selectAll: true, // 是否开启全选，默认开启
    filterGuest: false, //是否过滤访客，默认不过滤访客
    users: ['openid_1','openid_2'], // 默认选中的用户列表，最大数量300
    disabledUsers: ['openid_1','openid_2'], // 禁用的用户列表，最大数量300
    allowClear: true, // 默认true：选择时可以取消所有已选择项
    theme: 0-7, // 弹出框的主题色，可选范围从0到7，对应相应的轻推轻应用颜色规范，默认为0，轻推色
    title: '我是自定义标题', // 定义选择界面的标题可不传
    needSelf: false, // 选择的时候是否可以选择自己，默认不选择
    success: function(res) {
        var data = res.data; //返回选择用户的数组
        var id = res.data[0].id; //选择用户的openid
        var name = res.data[0].name; //选择用户在企业中的名称
        var avatar = res.data[0].avatar; //选择用户在企业中的头像
    },
    fail: function(re) {
        alert(re.errMsg)
        console.log(re)
    },
    cancel: function() {
        alert('用户取消了选择')
    }
});

备注： 传参无特殊说明则是非必传项

自定义通讯录选人

qt.openCustomContacts({
    candidateUsers: ['openid_1','openid_2'], //(必填项) 待选成员的openid列表，最大数量300
    users: ['openid_1','openid_2'], // 默认选中的用户列表，最大数量300
    disabledUsers: ['openid_1','openid_2'], // 禁用的用户列表，最大数量300
    max: 9, //人数限制，当启用多选时生效，最大数量300
    title: '选择联系人', // 定义选择界面的标题可不传
    multiple: false, // 是否开启多选，默认不开启
    filterGuest: false, //是否过滤访客，默认不过滤访客
    allowClear: true, // 默认true：选择时可以取消所有已选择项
    theme: 0-7, // 弹出框的主题色，可选范围从0到7，对应相应的轻推轻应用颜色规范，默认为0，轻推色
    success: function(res) {
        console.log(res);
        $('#resulte').text(JSON.stringify(res))
    },
    fail: function(re) {
        alert(re.errMsg)
        console.log(re)
    },
    cancel: function() {
        alert('用户取消了选择')
    }
})

备注： 传参无特殊说明则是非必传项

打开组织机构和联系人

qt.openOrgContacts({
    disableOrg: ['orgid_1','orgid_2'] // 不能操作的组织机构的id列表，最大数量300
    disabledUsers: ['openid_1','openid_2'], // 禁用的用户列表，最大数量300
    max: 9, //人数限制，当启用多选时生效，最大数量300
    filterGuest: false, //是否过滤访客，默认不过滤访客
    users: ['openid_1','openid_2'], // 默认选中的用户列表，最大数量300
    orgs: ['orgid_1','orgid_2'], // 默认已经选择的组织机构id列表，和users之和不超过300。
    title: '选择联系人', // 定义选择界面的标题可不传
    allowClear: true, // 默认true：选择时可以取消所有已选择项
    theme: 0-7, // 弹出框的主题色，可选范围从0到7，对应相应的轻推轻应用颜色规范，默认为0，轻推色
    success: function(res) {
        console.log(res);
        $('#resulte').text(JSON.stringify(res))
    },
    fail: function(re) {
        alert(re.errMsg)
        console.log(re)
    },
    cancel: function() {
        alert('用户取消了选择')
    }
})

备注： 传参无特殊说明则是非必传项

打开指定会话

qt.openSignChat({
    id: OpenId, // 会话窗口用户的openid
    fail: function(res) {
        alert(res.errMsg)
        console.log(res)
    }
})

打开联系人详情

qt.openUserDetail({
    id: OpenId, // 会话窗口用户的openid
    fail: function(res) {
        alert(res.errMsg)
        console.log(res)
    }
})

开启录音

qt.startRecord();

停止录音

qt.stopRecord({
    success: function (res) {
        var localId = res.localId;
    }
});

监听录音自动停止

qt.onVoiceRecordEnd({
    // 录音时间超过一分钟没有停止的时候会执行 complete 回调
    complete: function (res) {
        alert('录音超过1分钟' + res.localId);
        var localId = res.localId;
    }
});

播放录音

qt.playVoice({
    localId: localId
});

停止播放录音

qt.stopVoice({
    localId: localId
});

监听录音播放停止

qt.onVoicePlayEnd({
    success: function (res) {
        alert('录音' + localId + '播放结束');
        var localId = res.localId; // 返回音频的本地ID
    }
})

上传语音

qt.uploadVoice({
    localId: '', // 需要上传的语音的本地ID，由stopRecord接口获得
    isShowProgressTips: 1, // 默认为1，显示进度提示
    success: function (res) {
        var serverId = res.serverId;
    }
})

备注：上传的文件有效期为3天，如需下载到自己的服务器，可参考附录4：下载JS-API临时文件接口，此处获得的 serverId 即 media_id

下载语音

qt.downloadVoice({
    serverId: '', // 需要下载的语音的服务器端ID，由stopRecord接口获得
    isShowProgressTips: 1, // 默认为1，显示进度提示
    success: function (res) {
        var localId = res.localId;
    }
})

上传文件

qt.uploadFile({
    localId: '', // 需要上传的文件的本地ID
    isShowProgressTips: 1, // 默认为1，显示进度提示
    success: function (res) {
      var serverId = res.serverId;
    }
});

备注：上传的文件有效期为3天，如需下载到自己的服务器，可参考附录4：下载JS-API临时文件接口，此处获得的 serverId 即 media_id

下载文件

qt.downloadFile({
    serverId: '', // 需要下载的文件的服务器端ID
    isShowProgressTips: 1, // 默认为1，显示进度提示
    success: function (res) {
      var localId = res.localId;
    }
});

横屏

qt.landscapeView({
    success: function(res) {
        alert('landscapeView success');
    },
    fail: function(res) {
        alert('landscapeView fail');
    }
});

竖屏

qt.portraitView({
    success: function(res) {
        alert('portraitView success');
    },
    fail: function(res) {
        alert('portraitView fail');
    }
});

自动横竖屏

可通过在新开页面的链接中加上参数orientation，来控制页面横竖屏

window.location.href = "rotateView.html?orientation=landscape";//页面打开新链接横屏
window.location.href = 'rotateView.html';//页面打开新链接竖屏，默认为竖屏
window.location.href = 'rotateView.html?orientation=auto';//页面打开新链接自动模式，前提是必须打开手机自动横竖屏的模式

客户端webview弹性拉伸效果

qt.webviewElastic({
    elastic: 1, // 0: 关闭 1: 开启
    success: function(res) {
        alert('openElastic success');
    }
    fail: function(res) {
        alert('openElastic fail');
    }
});

备注：该接口只能用于iOS客户端

客户端弹窗提示

qt.toast({
    content: '成功toast', // 弹窗提示内容
    icon: 0, // 弹窗图标 0:成功，1:失败，2:警告
    time: 3000 // 弹窗消失时长，单位：毫秒
})

附录1：JS-SDK权限签名算法

开发者在web页面使用轻推提供的JS-SDK时，需要验证调用权限，并以参数signature标识合法性。同时，出于安全考虑，开发者必须在服务器端实现签名的逻辑。

签名生成的规则如下：

参与签名的参数有四个: noncestr（随机字符串）, jsapi_ticket, timestamp（时间戳）, url（当前网页的URL，不包含#及其后面部分，如：https://abc.cn/ ）
将这些参数使用URL键值对的格式（即 key1=value1&key2=value2…）拼接成字符串str。有两个注意点：1. 字段值采用原始值，不要进行URL转义；2. 必须严格按照如下格式拼接，不可变动字段顺序。
```
String str="jsapi_ticket=JSAPITICKET&noncestr=NONCESTR&timestamp=TIMESTAMP&url=URL";
```
对str进行sha1加密。

服务器端签名JAVA示例如下：

long timestamp = System.currentTimeMillis(); //时间戳服务器端本地生成
String nonceStr = UUID.randomUUID().toString(); //随机字符串，可以自行随机生成
String originUrl = "http://www.qingtui.cn/index.hmtl?someKey=someValue#xx/yy";//需要调用JS-SDK的网页的URL，不包含#及其后面部分（此处仅为示例，请根据实际情况填写）
String url = originUrl.split("#")[0];//保留#号以前的内容
String jsapi_ticket = "xxx"; //调用轻推JS-SDK接口的临时票据
String temp = "jsapi_ticket="+jsapi_ticket+"&noncestr="+nonceStr+"&timestamp="+timestamp+"&url="+url; //拼接字符串
String signature = Sha1Utils.getSha1(temp); //由Sha1工具类生成本地签名
System.out.println(signature);

备注：

jsapi_ticket是调用轻推JS-SDK接口的临时票据，通过access_token来获取，获取jsapi_ticket。
完整的JS-SDK使用说明以及服务端JAVA的签名示例，可以参考附录5：JS-SDK使用及服务端签名示例。

附录2：所有JS接口列表

获取设备信息 getClientInfo
获取网络信息 getNetworkType
获取jsapi版本号 getJsApiVersion
代发网络请求 ajax
关闭窗口 closeWindow
拍照或从手机相册中选图 chooseImage
预览图片 previewImage
上传图片 uploadImage
下载图片 downloadImage
裁剪图片 chooseCropOCRImage
识别图片 ocrImage
轻推扫一扫 scanQRCode
获取地理位置 getLocation 
停止定位 stopLocation
通讯录选人 openContacts
自定义通讯录选人 openCustomContacts
打开组织机构和联系人 openOrgContacts
打开指定会话 openSignChat
打开联系人详情 openUserDetail
开启录音 startRecord  
停止录音 stopRecord 
监听录音自动停止 onVoiceRecordEnd  
播放录音 playVoice
停止播放录音 stopVoice  
监听录音播放停止 onVoicePlayEnd
上传语音 uploadVoice
下载语音 downloadVoice
上传文件 uploadFile
下载文件 downloadFile
横屏 landscapeView
竖屏 portraitView
客户端webview弹性拉伸效果 webviewElastic
客户端弹窗提示 toast

附录3：JS-SDK权限认证常见错误说明

1.invalid url domain
当前页面不在安全域名内，或者是没有配置安全域名。

2.invalid signature
无效的签名，请检查是否严格按照签名算法得出签名，jsticket是否有效，

3.function not exist
当前客户端版本不支持该接口，请升级到新版体验

4.function not in the jsapilist
jsApiList未包含JSAPI

5.verify permission failed
由于权限导致的无法使用jsapi ，认证失败

附录4：下载JS-API临时文件接口

正确使用此接口，请结合JS-API的语音、文件接口

请求方式： GET

请求地址： https://open.qingtui.cn/v1/media/download?access_token=ACCESS_TOKEN&media_id=MEDIA_ID

参数说明：

参数	必须	说明
access_token	是	接口调用凭证
media_id	是	下载文件对应的media_id，来源于JS-API临时语音、文件上传后返回的serverid

正确返回结果示例：

正确返回结果为文件内容的字节流

出错返回结果示例：

{
    "errcode": 50003,
    "errmsg": "未授权的媒体数据"
}

参数说明：

参数	说明
errcode	错误代号
errmsg	错误信息

备注：仅用于下载JS-API接口上传的临时文件，包括语音和图片

附录5：JS-SDK使用及服务端签名示例

JS-SDK使用说明及服务端签名JAVA示例代码：sample.zip