快速开始
本文档介绍如何快速接入轻推JSAPI，完成基础配置并开始调用接口。
轻推JSAPI的所有接口（config除外），可通过qt对象（也可使用jQingTui对象）来调用，参数是一个对象，除了每个接口本身需要传的参数之外，还有以下通用参数：
1. success：接口调用成功时执行的回调函数。
2. fail：接口调用失败时执行的回调函数。
3. complete：接口调用完成时执行的回调函数，无论成功或失败都会执行。
4. cancel：用户点击取消时的回调函数，仅部分有用户取消操作的api才会用到。
5. progress: 接口进度的回调函数
以上几个函数都带有一个参数，类型为对象，其中除了每个接口本身返回的数据之外，还有一个通用属性errMsg，其值格式如下：
- 调用成功时：
"xxx:ok"，其中xxx为调用的接口名 - 用户取消时：
"xxx:cancel"，其中xxx为调用的接口名 - 调用失败时：其值为具体错误信息
**备注：**企业内部和已认证轻应用/订阅号都可以使用JSAPI。
步骤一：引入JS文件
在需要调用JS接口的页面引入如下JS文件：https://static.qingtui.com/open/libs/jssdk/7.12.0/qingtui_jssdk.js，如需下载源文件，请右键此链接，点击"链接另存为"即可。
**备注：**支持使用 AMD/CMD 标准模块加载方法加载。
步骤二：加入config配置
必须在需要使用JSAPI的每个页面加入config配置信息，且config必须在调用其他接口之前进行加载，这样config的一个过程就是鉴权。
qt.config({
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"方式进行查看
- timestamp，生成签名的时间戳。服务器端生成方式如:
long timestamp = System.currentTimeMillis()- nonceStr，生成随机字符串，服务器端生成方式如:
String nonceStr = UUID.randomUUID().toString()- signature，生成签名，详见附录：JSAPI权限签名算法
- jsApiList，需要调用的JS接口列表，仅添加用到的即可，详见JSAPI总览。如：
['getLocation', 'startGeoLocation']
**备注：**完整的JSAPI使用说明以及服务端JAVA的签名示例，可以参考示例代码
步骤三：ready接口说明
无论config成功失败都会执行ready函数里面的代码，开发者如果需要在页面加载时就调用JSAPI的接口，则可以把相关接口放在ready函数中来实现成功调用。而对于需要用户主动触发时才调用的接口，则可以直接调用，无须放在ready函数中。
qt.ready(function () {
//无论config成功失败都会执行里面的代码，可以保证config执行完成后才执行这里的函数。
});
同时，如果config验证失败，也可以使用error接口
qt.error(function (res) {
alert(res.errMsg); //如果config信息验证失败会执行error函数，比如：返回错误信息。当然，也可以直接开启config的debug模式来进行查看。
});
附录
附录1：链接参数
可通过在链接中加上参数orientation，来控制页面横竖屏
"rotateView?orientation=landscape"; //页面打开新链接横屏
"rotateView"; //页面打开新链接竖屏，默认为竖屏
"rotateView?orientation=auto"; //页面打开新链接自动模式，前提是必须打开手机自动横竖屏的模式
可通过在链接中加上参数hideNavBar=1，来控制隐藏导航栏
"rotateView?hideNavBar=1"; //页面打开新链接隐藏导航栏
"rotateView"; //页面打开新链接默认显示导航栏
可通过在链接中加上参数immersiveNavigationBar=open，来控制隐藏导航栏和状态栏
"rotateView?immersiveNavigationBar=open"; //页面打开新链接隐藏导航栏和状态栏
"rotateView"; //页面打开新链接默认显示导航栏
可通过在链接中加上参数default_browser_phone=1，来控制外部应用打开
"rotateView?default_browser_phone=1"; //会使用外部浏览器打开网页
可通过在链接中加上参数openFile=文件id(默认1)，来控制iOS客户端打开文件。传入准确的文件id，可以在客户端缓存文件，方便二次打开。
"rotateView?openFile=1"; //打开文件，每次打开都会先下载后打开
"rotateView?openFile=唯一id"; //打开文件，每次打开会先判断本地是否存在，存在则打开，否则先下载后打开
附录2：权限签名算法
开发者在web页面使用轻推提供的JSAPI时，需要验证调用权限，并以参数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";//需要调用JSAPI的网页的URL，不包含#及其后面部分（此处仅为示例，请根据实际情况填写）
String url = originUrl.split("#")[0];//保留#号以前的内容
String jsapi_ticket = "xxx"; //调用轻推JSAPI接口的临时票据
String temp = "jsapi_ticket="+jsapi_ticket+"&noncestr="+nonceStr+"×tamp="+timestamp+"&url="+url; //拼接字符串
String signature = Sha1Utils.getSha1(temp); //由Sha1工具类生成本地签名
System.out.println(signature);
备注：
- jsapi_ticket是调用轻推JSAPI接口的临时票据，通过access_token来获取，获取jsapi_ticket。
- 完整的JSAPI使用说明以及服务端JAVA的签名示例，可以参考示例代码。
附录3：权限认证常见错误说明
| errMsg | 说明 |
|---|---|
| invalid url domain | 当前页面不在安全域名内，或者是没有配置安全域名。 |
| invalid signature | 无效的签名，请检查是否严格按照签名算法得出签名，jsticket是否有效， |
| function not exist | 当前客户端版本不支持该接口，请升级到新版体验 |
| function not in the jsapilist | jsApiList未包含JSAPI |
| verify permission failed | 由于权限导致的无法使用jsapi ，认证失败 |
附录4：示例代码
JSAPI使用说明及服务端签名JAVA示例代码：sample.zip