得力e+ Web接入协议

文档目标

本文档用于描述基于WEB网页形式的第三方云应用服务接入得力e+ Web,如何通过JS API接口与得力e+ Web进行交互.

适用范围

第三方云应用管理员通过得力e+ Web进行应用管理,所有基于Web网页形式的第三方云应用开发人员均可通过本文档了解得力e+ Web开放的JS API接口功能以及调用方法.

使用简介

  • 1. 云应用登录流程

  • 用户访问得力Web登录页面,登录成功后获得用户会话token信息。用户点击云应用链接地址,自动携带用户ID、token、组织ID、UUID等关键信息访问云应用服务器;

  • 云应用服务器通过访问链接获得用户token等信息后通过云平台进行用户身份校验,根据校验结果不同,可能调转到不同的页面处理逻辑(应用自定义)。注意,不论跳转到哪个界面,云应用服务器都应该根据AppId、AppKey等信息生成应用签名,并返回到前端页面进行JSSDK加载;

  • 前端页面加载JSSDK脚本文件,并调用SDK的初始化API将应用服务器返回的应用签名等参数进行初始化操作;

  • JSSDK初始化过程中会发送应用签名信息到得力云平台进行应用身份验证。如果应用签名认证失败,则SDK初始化失败,进入错误处理流程;否则,SDK会自动初始化得力Web UI组件,完成应用界面加载;

  • 2. 同步或异步加载Javascript SDK

同步:在HTML文档的标签之后引入delicloud-web.min.js

文件引入地址如下:

测试: http://t.static.delicloud.com/www/sdk/delicloud-web.min.js

线上: http://static.delicloud.com/www/sdk/delicloud-web.min.js

异步:在HTML文档的标签之后引入代码如附录1.所示

备注:同步或者异步引入JS后会得到全局变量 deli ,支持使用AMD/CMD标准模块加载方法加载.

  • 3. JSAPI初始化配置

  • JSAPI初始化过程

    • 注册应用,应用服务端从得力云平台获取appIdappKey,其中appKey是私密信息,应保存在应用服务器中,不得公开;
    • 应用服务端在页面初始化时根据平台提供的签名算法和私密信息计算签名(具体算法见下一小节),并将签名结果和生成签名的原参数返回给前端页面;
    • 前端页面调用deli.config配置接口输入应用服务器传递过来的签名信息进行平台授权验证; 注意,deli.config不要重复配置;
    • 平台验证应用服务器的签名信息并返回验证结果.如果验证失败,SDK会调用deli.error方法返回错误信息,否则会调用deli.ready,SDK初始化完成.

  • JSAPI初始化签名算法

第三方应用服务使用得力云提供的JSAPI时需要验证其调用身份.验证方法是采用简单的签名算法来完成.由于appKey是平台和应用服务之间的私密信息,通过采用相同的appKey计算出来的签名如果一致,则可证明应用服务的合法性. 签名生成的规则如下:

var keyArray = sort(noncestr,timestamp,appId,appKey);
var str = assemble(keyArray);
var signature = md5(str);

参与签名的字段包括在上文中获取的appId, noncestr(随机字符串),timestamp(当前时间戳,具体值为当前时间到1970年1月1号的秒数). 具体的计算过程描述如下:

步骤1. sort()含义为对所有待签名参数按照字段名的ASCII码从小到大排序(字典序);
步骤2. assemble()含义为根据步骤1中获的参数字段的顺序,使用键值对的格式(即key1=value1&key2=value2…)拼接成字符串;
步骤3. md5()的含义为对在步骤2拼接好的字符串进行md5加密.
  • 4. SDK初始化

deli.config是所有需要使用JS-SDK的页面首先需要调用的初始化验证操作.如果配置信息验证不成功,后续所有接口将无法使用.(注意,同一个url仅需调用一次)

deli.config({
    appId : "", //必填,应用ID
    timestamp : "", //必填,生成签名的时间戳
    noncestr : "", //必填,生成签名的随机字符串
    signature : "" //必填,签名
})
  • deli.config调用成功后,SDK会自动调用deli.ready方法表示SDK已初始化完毕,可以开始使用SDK的API接口.该方法定义如下:
deli.ready(function(){
    // deli.ready 参数为回调函数,在环境准备就绪时触发,
    // jsapi的调用需要保证在该回调函数触发后调用,否则无效.
    // config信息验证成功会执行ready函数
    // 在执行ready函数之前,SDK会自动检查用户登录状态,如果用户已经登录则正常访问云应用,此时第三方云应用开发者可以从浏览器的url或者cookie中获取用户信息(user_id,org_id,token,uuid),用户未登录 则自动跳转至得力e+ Web登录页面(http://www.delicloud.com/oauth/?redirect=http://www.thirdapp.com),使用得力e+ App扫码功能登录,登录成功后自动跳转至第三方云应用页面并附加相关数据信息在浏览器的url和cookie中(http://www.thirdapp.com?user_id=&org_id=&token=&uuid=)
});
  • deli.config如果验证失败,则自动调用deli.error方法,SDK初始化失败并返回具体的错误信息. 该方法定义如下:
deli.error(function(resp){
    // config信息验证失败会执行error函数,
    //如签名过期导致验证失败,可以在返回的resp参数中查看参数内容并和生成签名参数做对比,找出错误的参数
    { "code" : "错误码", "msg" : "错误信息描述" }
});
  • 5. 其它说明

    • 所有接口都通过deli对象来调用;
    • 所有接口都为异步;
    • 所有接口的调用方式是都是统一的,由三个参数组成.第一个参数是一个object类型,表示请求参数信息,第二个参数是成功回调函数,第三个参数是失败回调函数.示例如下:
deli.app(模块分类).method(方法)(
    {}, //第一个参数,object类型
function(data){
    //第二个参数,成功回调
},function(resp){
    //第三个参数,失败回调
});

成功时返回接口响应数据,不同接口格式不同,具体见各个接口定义. 失败时返回失败的错误码和错误信息描述,默认响应格式如下:

{
    "code": -5,
    "msg": "无效的登录信息"
}

响应参数说明如下:

响应参数 说明
code 错误码,具体错误码列表见末尾
msg 错误信息描述

接口定义

以下接口为得力e+网页应用JS SDK API,目前提供的接口列表,是与得力e+平台业务相关的业务API接口(备注:根据业务需要会陆续新增)

  • 业务接口(app)

  • 用户退出登录(app.onlogout)

用户主动或自动退出登录时, sdk会触发用户退出事件,应用可以通过以下API监听该事件,并通过回调执行应用内部的退出业务逻辑;

deli.app.onlogout({}, function(data){}, function(resp){
    //用户退出自定义处理逻辑
    });

该API无请求参数。

其它

  • 异步引入Javascript SDK

(function(o, s, id){
    var js, fjs = o.getElementsByTagName(s)[0];
    if (o.getElementById(id)) {return;}
    js = o.createElement(s); js.id = id;
    js.src = "http://static.delicloud.com/www/sdk/delicloud-web.min.js";
    fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', ' delicloud-web'));
window.deliAsyncInit = function(){
    deli.config({
        "appId": "", // 必填,应用ID 
        "noncestr": "", // 必填,生成签名的随机串
        "timestamp": "", // 必填,生成签名的时间戳
        "signature": "" // 必填,服务端生成的签名
    });
    deli.ready(function(resp){
    });
    deli.error(function(resp){
    });
};
  • 错误码定义列表(待定义)

错误码 错误码说明
-1 权限校验失败
-2 参数错误
-3 网络错误
-4 未知错误
-5 无效的登录信息
  • 更新日志

1.0 (2018-01-03)

  • 发布1.0线上版本