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.3/qingtui_jssdk.min.js,如需下载源文件,请右键此链接,点击“链接另存为”即可。
备注:支持使用 AMD/CMD 标准模块加载方法加载。
步骤二:加入config配置
必须在需要使用JS-SDK的每个页面加入config配置信息,且config必须在调用其他接口之前进行加载,这样config的一个过程就是鉴权。
qt.config({
debug: true,
appId: '1234567890',
timestamp: 1000000000,
nonceStr: 'randomstr',
signature: 'signature001',
jsApiList: []
鉴权流程:
前端页面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验证失败,也可以使用error接口
qt.error(function(res) {
alert(res.errMsg);
获取jsapi_ticket
请求方式: GET
请求地址: https://open.qingtui.com/js/ticket/get?access_token=ACCESS_TOKEN
参数说明:
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;
var version = res.version;
获取网络信息
qt.getNetworkType({
succes: function(res){
var networkType = res.networkType;
获取jsapi版本号
qt.getJsApiVersion({
success: function(res){
var jsApiVersion = res.jsApiVersion;
代发网络请求
由轻推客户端进行代发网络请求,用于解决跨域问题。仅在手机端支持,页面如果同时在PC和手机使用,请自行判断。
qt.ajax({
url: 'http://xxx',
header: {},
type: 'get' || 'post',
dataType: 'json',
data: {},
success: function(res){
var statusCode = res.statusCode;
var result = res.result;
可在网页中调用此方法,关闭轻推浏览器窗口。
qt.closeWindow()
拍照或从手机相册中选图
qt.chooseImage({
count: 1,
sizeType: ['original', 'compressed'],
sourceType: ['album', 'camera'],
success: function (res) {
var localIds = res.localIds;
qt.previewImage({
btns:["forward","download"],
current: '',
urls: []
qt.uploadImage({
localId: '',
isShowProgressTips: 1,
success: function(res) {
var serverId = res.serverId;
备注:上传的文件有效期为3天,可用服务器端media/download接口下载到自己的服务器,此处获得的 serverId 即 media_id
qt.downloadImage({
serverId: '',
isShowProgressTips: 1,
success: function(res) {
var localId = res.localId;
裁剪图片(票务)
选择并裁剪需要识别的图片,仅支持轻推V6.2.0以上版本,接口包含:1、裁剪需要识别的图片 2、仅识别税务发票上的二维码
qt.chooseCropOCRImage({
sourceType: ['album', 'camera'],
title: '',
type: 1 | 2,
success: function(res) {
var localId = res.localId;
var qrResult = res.QRResult;
识别图片(票务)
识别图片,仅支持轻推V6.2.0以上版本,接口包含:1、识别税务发票(识别除二维码的所有文本信息)2、识别火车票(识别除二维码的所有文本信息)
qt.ocrImage({
localId: '',
type: 1 | 2,
success: function(res) {
var serverId = res.serverId;
var result = res.result;
轻推扫一扫
qt.scanQRCode({
needResult: 1,
success: function(res) {
var result = res.resultStr;
console.log(result);
获取地理位置
qt.getLocation({
type: 'wgs84',
interval: 1000,
formatAddr: false
success: function (res) {
var latitude = res.latitude;
var longitude = res.longitude;
var precision = res.precision;
var addr = res.addr;
var id = res.id;
停止指定连续定位
qt.stopLocation({
id: id
停止所有连续定位
qt.stopLocation()
通讯录和会话
通讯录选人
qt.openContacts({
max: 9,
multiple: false,
selectAll: true,
filterGuest: false,
users: ['openid_1','openid_2'],
disabledUsers: ['openid_1','openid_2'],
allowClear: true,
theme: 0-7,
title: '我是自定义标题',
needSelf: false,
success: function(res) {
var data = res.data;
var id = res.data[0].id;
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'],
users: ['openid_1','openid_2'],
disabledUsers: ['openid_1','openid_2'],
max: 9,
title: '选择联系人',
multiple: false,
filterGuest: false,
allowClear: true,
theme: 0-7,
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']
disabledUsers: ['openid_1','openid_2'],
max: 9,
filterGuest: false,
users: ['openid_1','openid_2'],
orgs: ['orgid_1','orgid_2'],
title: '选择联系人',
allowClear: true,
theme: 0-7,
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,
fail: function(res) {
alert(res.errMsg)
console.log(res)
打开联系人详情
qt.openUserDetail({
id: OpenId,
fail: function(res) {
alert(res.errMsg)
console.log(res)
qt.startRecord();
qt.stopRecord({
success: function (res) {
var localId = res.localId;
监听录音自动停止
qt.onVoiceRecordEnd({
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;
qt.uploadVoice({
localId: '',
isShowProgressTips: 1,
success: function (res) {
var serverId = res.serverId;
备注:上传的文件有效期为3天,如需下载到自己的服务器,可参考附录4:下载JS-API临时文件接口,此处获得的 serverId 即 media_id
qt.downloadVoice({
serverId: '',
isShowProgressTips: 1,
success: function (res) {
var localId = res.localId;
qt.uploadFile({
localId: '',
isShowProgressTips: 1,
success: function (res) {
var serverId = res.serverId;
备注:上传的文件有效期为3天,如需下载到自己的服务器,可参考附录4:下载JS-API临时文件接口,此处获得的 serverId 即 media_id
qt.downloadFile({
serverId: '',
isShowProgressTips: 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,
success: function(res) {
alert('openElastic success');
fail: function(res) {
alert('openElastic fail');
备注:该接口只能用于iOS客户端
客户端弹窗提示
qt.toast({
content: '成功toast',
icon: 0,
time: 3000
附录1:JS-SDK权限签名算法
开发者在web页面使用轻推提供的JS-SDK时,需要验证调用权限,并以参数signature标识合法性。 同时,出于安全考虑,开发者必须在服务器端实现签名的逻辑。
签名生成的规则如下:
参与签名的参数有四个: noncestr(随机字符串), jsapi_ticket, timestamp(时间戳), url(当前网页的URL, 不包含#及其后面部分,如:https://abc.cn/#/xx/yy )
将这些参数使用URL键值对的格式 (即 key1=value1&key2=value2…)拼接成字符串str。
有两个注意点:1. 字段值采用原始值,不要进行URL转义;2. 必须严格按照如下格式拼接,不可变动字段顺序。String str="jsapi_ticket=JSAPITICKET&noncestr=NONCESTR×tamp=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";
String url = originUrl.split("#")[0];
String jsapi_ticket = "xxx";
String temp = "jsapi_ticket="+jsapi_ticket+"&noncestr="+nonceStr+"×tamp="+timestamp+"&url="+url;
String signature = Sha1Utils.getSha1(temp);
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.com/v1/media/download?access_token=ACCESS_TOKEN&media_id=MEDIA_ID
参数说明: