钉钉开发文档

开发应用

更新时间: 2019-1-17

移动端免登

钉钉开放平台提供丰富的接口和开发调试工具,以便开发者接入。

  1. 钉钉开放平台提供了企业通讯录管理、文件管理、发送企业会话消息等功能,接口使用可以参考服务端开发文档
  2. 钉钉开放平台提供了定制微应用在钉钉客户端运行的专用容器,并提供一组可以调用钉钉的本地能力和业务能力的jsapi接口,jsapi接口用于微应用与钉钉功能之间的结合;接口使用可以参考客户端开发文档
  3. 钉钉开放平台提供了与钉钉PC版本集成的能力,接口使用可以参考PC端开发文档

企业微应用接入流程,下面我们将通过流程图讲解微应用的具体流程:

image.png

名词解释

免登:企业自主开发的应用叫企业应用,企业应用免登可以让用户在登录钉钉进入应用后自动获取当前登录的用户信息和企业信息而不需要输入用户名密码。

鉴权:钉钉提供了一些Native能力的jsapi,这些jsapi有很多是手机的基础能力,对这些jsapi的调用不需要进行鉴权(即不需要进行dd.config),只需要保证在dd.ready里面调用即可。对于一些钉钉业务相关、安全相关的jsapi调用,需要开发者先进行鉴权后再调用。

免登流程

免登接口可以实现用户无需输入用户名+密码进行登录,并通过权限认证后获取用户身份的接口。

获取免登授权码

在H5页面调用钉钉的JSAPI之前,需要先引入dingtalk的JS文件

使用钉钉jsapi提供的获取免登授权码接口获取CODE,此jsapi无需鉴权(即不需要进行dd.config)

dd.ready(function() {
    dd.runtime.permission.requestAuthCode({
        corpId: "corpid",
        onSuccess: function(result) {
        /*{
            code: 'hYLK98jkf0m' //string authCode
        }*/
        },
        onFail : function(err) {}
 
    });
});

通过免登码获取用户身份

通过code获取身份userid

通过userid获取用户信息(建议用户信息保存在cookie中,避免多次调用获取用户信息接口)

JSAPI鉴权流程

钉钉提供的jsapi有很多是手机的基础能力,对jsapi的调用不需要进行鉴权(即不需要进行dd.config),只需要保证在dd.ready里面调用即可。对于一些钉钉业务相关、安全相关的js-api调用,需要开发者先进行鉴权后再调用。

鉴权-获取access_token

参考 如何获取access_token

鉴权-获取jsticket

企业在使用微应用中的jsapi时,需要先从钉钉开放平台接口获取jsapi_ticket生成签名数据,并将最终签名用的部分字段及签名结果返回到前端H5中,通过调用dd.config来判断H5是否有权限使用钉钉的jsapi。

通过调用获取jsticket的接口获取企业的jsapi_ticket。

鉴权-获取签名参数

在前端进行免登鉴权之前,我们要先拿到一些免登鉴权的参数,主要有'url','nonceStr','agentId','timeStamp','CorpId'

参数 | 说明 | 企业
------- | -------------
url | 需要进行免登鉴权的页面地址,也就是执行dd.config的页面地址| //
nonceStr | 随机串,自己定义| //
agentId | 应用的标识|编辑企业应用可以看到
timeStamp| 时间戳|当前时间,但是前端和服务端进行校验时候的值要一致
corpId| 企业ID|企业ID,在http://open-dev.dingtalk.com/上企业视图下开发者账号设置里面可以看到

鉴权-计算签名信息

在服务端通过sign(ticket, nonceStr, timeStamp, url)计算前端校验需要使用的签名信息。

代码展示:

      public static String sign(String ticket, String nonceStr, long timeStamp, String url) throws OApiException {
		String plain = "jsapi_ticket=" + ticket + "&noncestr=" + nonceStr + "&timestamp=" + String.valueOf(timeStamp)
				+ "&url=" + url;
		try {
			MessageDigest sha1 = MessageDigest.getInstance("SHA-1");
			sha1.reset();
			sha1.update(plain.getBytes("UTF-8"));
			return bytesToHex(sha1.digest());
		} catch (NoSuchAlgorithmException e) {
			throw new OApiResultException(e.getMessage());
		} catch (UnsupportedEncodingException e) {
			throw new OApiResultException(e.getMessage());
		}
	}

注意:参与签名的字段包括在上文中获取的jsapiTicket,nonceStr(随机字符串,自己随便填写即可),timeStamp(当前时间戳,具体值为当前时间到1970年1月1号的秒数),url(当前用户访问的网页URL,从前端传递到后端且不包含#及其后面部分,需要对url中query部分做一次urldecode)。

将:'url','nonceStr','agentId','timeStamp','corpId','signature'传递到前端页面,在前端HTML5页面使用jsapi提供的dd.config(PC客户端使用DingTalkPC.config)接口进行签名校验。

代码:

dd.config({
    agentId: _config.agentId,
    corpId: _config.corpId,
    timeStamp: _config.timeStamp,
    nonceStr: _config.nonceStr,
    signature: _config.signature,
    jsApiList: [
        'runtime.info' // 需要用到的jsapi都列在这里
    ]
});

鉴权完成后,所有钉钉提供的jsapi就可以进行调用了,具体请查看移动端JSAPI总览

引入使用的JS

在页面引入最新的js:

https://g.alicdn.com/dingding/open-develop/1.6.9/dingtalk.js

或者

http://g.alicdn.com/dingding/open-develop/1.6.9/dingtalk.js

demo参考

前端鉴权js示例:

demo地址:https://github.com/injekt/openapi-demo-php/blob/master/corp/public/javascripts/demo.js

注意点

1、进行鉴权的时候,agentId,appkey,appsecret,jsTicket要一一对应。具体为,创建应用的时候,会生成一组appkey,appsecret和agentId。要用appkey和appsecret获取access_token,然后用access_token换取jsTicket。最后用这个jsTicket和agentId进行dd.config
2、dd.config里的corpId参数切勿使用appkey进行代替

PC端应用免登

1.在使用jsapi的时候,引入的jsapi地址为:http://g.alicdn.com/dingding/dingtalk-pc-api/2.3.1/index.js

2.在使用jsapi的时候,调用方式为:DingTalkPC.config,用DingTalkPC替换移动客户端的dd调用方式。

以上内容是否对您有帮助:
在文档使用中是否遇到以下问题(多选):
  • 内容错误
  • 更新不及时
  • 链接错误
  • 缺少代码/图片示例
  • 太简单/步骤待完善
手机号
更多建议
提交成功,感谢您的反馈!