釘釘微應用接入

###概述

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>
複製代碼