首页 > API文档 > 客户端开发
Getting Started
更新时间: 2021-12-08 10:44:03

Getting Started

引入JS文件

1, 如果应用珍岛JS API,可以选择直接在Web页面在线引用对应JS文件:



或是将JS文件下载到本地,放到应用站点的本地目录中引用。



成功加载JS文件后,可直接使用全局变量FSOpen调用API,如FSOpen.runtime.getVersion

2, 如需应用珍岛UI组件库,还需另下载对应的JS文件和CSS文件,放在站点的本地目录中引用。下载下来的压缩包需先解压,其中uikit.jsuikit.css包含所有的组件定义。如仅应用了部分组件,也可以仅引用components文件夹中对应的分类js文件和css文件,以加快页面加载速度。

UI组件库下载地址

JS API使用约定

所有接口均接受一个JSON object参数,基本格式如下:

{
    param1: 'xxx',  // 接口参数1(示例)
    ...
    paramn: 'xxx',  // 接口参数n(示例)
    onSuccess: function(resp) {
        // 成功回调处理...
    },
    onFail: function(error) {
        // 失败回调处理...
    }
}

所有成功回调(如有)返回如下内容:

{
    result1: 'xxx',  // 返回参数1(示例)
    ...
    resultn: 'xxx',  // 返回参数n(示例)
}

所有错误回调(如有)返回如下内容:

{
    errorCode: 40000, // 错误码
    errorMessage: '请求参数错误'  // 错误描述
}

错误码可参考错误码汇总表

初始化API运行环境

在使用JS API之前,必须使用FSOpen.init方法对运行环境进行预配置,否则接口调用会出错。 代码样例

FSOpen.init({
    appId: 'FSAID_1313de7',
    timestamp: '123456',
    nonceStr: 'randxxxx',
    signature: '784E655546BCEC2D5B8392B5998FE1403B6DD0DA',

    onSuccess: function(resp) {
        // 初始化成功回调. 所有JS API执行必须在初始化成功后,否则会出错。
    },
    onFail: function(error) {
        // 失败回调处理
        if (error.errorCode === 30000) {
            alert('请更新珍岛客户端到最新版本。');
        } else {
            alert('初始化失败:' + JSON.stringify(error.errorMessage));
        }
    }
});

方法名:FSOpen.init
JS版本:2.0.0
客户端支持版本:5.4.0及以上

参数说明

参数名类型必填参数描述
appIdString应用ID,在珍岛Web端开启应用开发者模式后可查看到appID。
timestampLong生成签名的时间戳
nonceStrString生成签名的随机字符串
signatureString签名。值为十六进制的字符表示形式,如784E655546BCEC2D5B8392B5998FE1403B6DD0DA,大小写敏感,需要全部转为大写。

signature签名算法  

jsapi_ticket

jsapi_ticket是珍岛应用调用珍岛JS API的临时票据,在签名计算中使用。正常情况下,jsapi_ticket的有效期为7200秒,通过corpAccessToken来获取。详情参考获取jsapi_ticket
为提高性能,且避免频繁刷新jsapi_ticket导致api调用受限,影响自身业务,开发者必须在自己的服务全局缓存jsapi_ticket 。    

签名算法

签名生成规则如下:参与签名的字段包括noncestr(随机字符串), 有效的jsapi_ticket, timestamp(时间戳), url(当前网页的URL,不包含#及其后面部分) 。对所有待签名参数按照字段名的ASCII 码从小到大排序(字典序)后,使用URL键值对的格式(即key1=value1&key2=value2…)拼接成字符串src_string,参数名均为小写字符,字段名和字段值都采用原始值,不进行URL转义。最后对src_string作sha1加密,即signature=sha1(src_string)。

示例:

// 各计算因子声明
jsapi_ticket=abc123456789
noncestr=randxxxx
timestamp=123456
url=https://www.71360.com/s?ie=utf8&wd=broker&tn=87048150_dg

// 拼接出src_string。对所有待签名参数按照字段名的ASCII 码从小到大排序(字典序),顺序依次为 jsapi_ticket,noncestr,timestamp,url,用&拼接其键值对。
jsapi_ticket=abc123456789&noncestr=randxxxx×tamp=123456&url=https://www.71360.com/s?ie=utf8&wd=broker&tn=87048150_dg

// 对src_string进行sha1签名,得到signature(大小写敏感,需要全部转为大写)
784E655546BCEC2D5B8392B5998FE1403B6DD0DA

注意事项

  1. 签名用的noncestr和timestamp必须与FSOpen.init中的nonceStr和timestamp相同。
  2. 签名用的url必须是调用JS接口页面的完整URL,但不包含#及其后面部分。
  3. 出于安全考虑,请务必在服务器端实现签名的逻辑。
  4. 上述案例中的各参数取值以及计算结果均为标准算法实际运行结果,开发者可用其检验自己的算法实现。

返回说明

成功回调返回参数
调用成功会回调onSuccess方法,可通过类似resp.parm1``resp.parm2获取相关返回参数,本文提到的“成功回调返回参数”即指这些提取出来的参数,如parm1``param2,后文不再赘述。FSOpen.init执行成功即代表API运行环境初始化成功,无需处理返回结果,当然开发者还是可以在onSuccess回调中添加自己的代码,如数据统计、表单提交等。

注:后文中如接口执行成功无需处理返回结果,将省略成功返回说明。  

失败回调返回参数
调用失败会回调onFail方法,可通过error.errorCode, error.errorMessage获取错误描述,后文不再赘述。
FSOpen.init可能返回的错误:

错误码错误描述
30000当前客户端版本不支持JavaScript API。通常是因为客户端版本小于5.4.0,需要更新到最新版本。
30001API运行环境未初始化
30002API运行环境初始化失败
40000接口调用参数错误
40001初始化签名校验失败。检查signature签名生成算法是否正确,或是js ticket已过期,可尝试更新js ticket。

注:后文中接口调用失败如无特殊情况,将省略失败返回说明,开发者可自行查阅错误码汇总表      

样例




    
    珍岛问问