钉钉微应用接入

###概述

JSAPI为微应用提供调用原生控件的能力，帮助开发者高效使用拍照、定位等手机系统的能力，同时能够直接使用扫一扫、分享、钉盘等钉钉特有的能力，带给微应用接近原生代码的体验。此文档面向开发者介绍钉钉JSAPI如何使用及相关注意事项。

####应用开发流程

1. 注册企业: 进入OA管理后台，经过一系列流程，完成企业注册。
2. 建立微应用: 进入钉钉管理后台后能够进入 “企业应用-应用管理” 页面建立微应用。
3. 须要填写应用Logo、应用名称、功能介绍、首页地址等必填信息。完成后，可在钉钉App的“工做”Tab下找到企业，能够查看到微应用入口。

注意：首页地址必须真实有效，不然没法正常访问 建立微应用后会生成AgentID，方便后续开发使用。AgentID可用于免登鉴权、发送企业会话消息等场景。

####准备工做

1. 开发以前，建议下载钉钉开发者版本的开发包。使用钉钉开发者版本的客户端进行开发、调试，对开发过程当中问题的调试定位很是有帮助。钉钉提供了安卓、IOS端的开发者版本安装包，具体使用方式请点击。
2. 钉钉提供了调试页面，供开发者在开发以前提早体验客户端提供的JSAPI功能。开发者打开钉钉，扫描调试页面二维码便可提早体验，JSAPI调试页面请点击。

#####使用npm安装

咱们推荐使用 npm 的方式进行开发，不只可在开发环境轻松调试，也可放心地在生产环境打包部署使用，享受整个生态圈和工具链带来的诸多好处。

npm install dingtalk-jsapi --save
复制代码

若是你的网络环境不佳，推荐使用 cnpm。

示例代码：

import * as dd from 'dingtalk-jsapi'; // 此方式为总体加载，也可按需进行加载
复制代码

#####浏览器引入

在浏览器中使用 script 和 link 标签直接引入文件，并使用全局变量 dd。

<script src="//g.alicdn.com/dingding/dingtalk-jsapi/2.0.57/dingtalk.open.js"></script>
复制代码

---

####前端流程

######1. 获取JSAPI鉴权 a.调用后台提供的接口获取签名; b.而后前端调用dd.cofig(); ######2. 获取身份免登 a.调用api拿到code; b.调用后台提供的接口拿到access_token; c.最后调用钉钉接口拿到用户信息；

####获取JSAPI鉴权

钉钉提供的jsapi有些须要鉴权后才可调用，好比钉钉业务相关、安全相关的api；有些是手机的基础能力，对这些api的调用不需进行鉴权，只需保证在dd.ready里面调用便可。

#####鉴权流程

#####JSAPI鉴权

示例代码：

dd.config({
    agentId: '', // 必填，微应用ID
    corpId: '',//必填，企业ID
    timeStamp: , // 必填，生成签名的时间戳
    nonceStr: '', // 必填，生成签名的随机串
    signature: '', // 必填，签名
    type:0/1,   //选填。0表示微应用的jsapi,1表示服务窗的jsapi；不填默认为0。该参数从dingtalk.js的0.8.3版本开始支持
    jsApiList : [
		'runtime.info',
		'biz.contact.choose',
		'device.notification.confirm',
		'device.notification.alert',
		'device.notification.prompt',
		'biz.ding.post',
		'biz.util.openLink',
	] // 必填，须要使用的jsapi列表，注意：不要带dd。
});

复制代码

具体见官方文档：open-doc.dingtalk.com/microapp/fr…

对调用不须要进行鉴权的api（即不须要进行dd.config），只须要在dd.ready里面调用便可。 对于一些钉钉业务相关、安全相关的api调用，咱们须要开发者先进行鉴权再进行调用（即dd.config）。

#####身份免登

企业或者ISV开发的应用，须要让用户在登陆钉钉进入应用的时候经过受权获取用户信息，而不用输入用户名密码。

######获取免登受权码

使用如下代码获取免登受权码（调用此api不须要进行鉴权，即不须要进行dd.config）

dd.ready(function() {
    dd.runtime.permission.requestAuthCode({
        corpId: _config.corpId, // 企业id
        onSuccess: function (info) {
                  code = info.code // 经过该免登受权码能够获取用户身份
        }});
});
复制代码

######经过免登受权码换取用户身份

企业应用的服务器在拿到CODE后，须要将CODE发送到钉钉开放平台接口，若是验证经过，则返回CODE对应的用户信息。此接口只用于免登服务中用来换取用户信息。

请求说明 Https请求方式: GET

https://oapi.dingtalk.com/user/getuserinfo?access_token=ACCESS_TOKEN&code=CODE

复制代码

返回结果 正确时返回示例以下：

{
"errcode": 0,
"errmsg": "ok",
"userid": "USERID",
"deviceId":"DEVICEID",
"is_sys": true,
"sys_level": 0|1|2
}
复制代码

具体JSAPI总览：open-doc.dingtalk.com/microapp/fr…

<script type="text/javascript" src="http://g.alicdn.com/dingding/open-develop/1.5.1/dingtalk.js"></script>
<script>
dd.ready(function(){
    //须要鉴权再进行调用 (dd.config)
    //dd.config({
        //agentId : _config.agentid,
        //corpId : _config.corpId,
        //timeStamp : _config.timeStamp,
        //nonceStr : _config.nonceStr,
        //signature : _config.signature,
        //jsApiList : [ 'runtime.info', 'biz.contact.choose',
                //'device.notification.confirm', 'device.notification.alert',
                //'device.notification.prompt', 'biz.ding.post',
                //'biz.util.openLink' ]
    //});
 
    //不须要进行鉴权的api调用
    dd.ready(function(){
        dd.runtime.permission.requestAuthCode({
            corpId :'corpId',
            onSuccess : function(info) {
                $.ajax({
                    url : '请求地址',
                    type : 'post',
                    dataType:"json",  
                    data:data,  
                    processData : false,// 告诉jQuery不要去处理发送的数据 
                    contentType : false,// 告诉jQuery不要去设置Content-Type请求头
                    success : function(data, status, xhr) {
                        alert('1');
                    },
                    error : function(xhr, errorType, error) {
                        alert('0');
                    }
                });
            },
            onFail : function(err) {
                alert('fail: ' + JSON.stringify(err));
            }
        });
    });    
});
</script>
复制代码