钉钉开放平台微应用接入

HTML5

肖健

字数统计: 1.8k阅读时长: 7 min

 2020/06/28   Share

钉钉开放平台微应用接入

一、概述

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

注意：钉钉微应用PC端开发和移动端开发已经统一，均可使用下面方式进行引入调用。

二、平台接入

1. 开发者后台管理

1.1 准备页面访问地址

http://xxx.xxx.xxx/onemap/home

1.2 创建应用

登录钉钉开发者后台，选择”应用开发”-“企业内部开发”-“H5微应用”，点击”创建应用”。

2.填写基本信息

填写应用基本信息。包括应用名称、应用Logo和应用简介，选择”企业内部自主开发”，点击”下一步”并创建应用

填写说明：
（1）开发模式：开发模式选择“开发应用”。

（2）开发应用类型：开发应用类型选择“微应用”。

（3）应用首页链接：填写应用首页链接

（4）服务器出口IP：调用钉钉服务端API的合法的IP列表。

（5）PC端首页地址：开发者可以选择是否填写PC端首页地址，在PC端展示不同。

（6）管理后台地址：填写管理后台地址，在钉钉管理后台-工作台-找到对应应用，点击应用图标，跳转到填写的地址。

3.查看应用信息

可以查看生成的appKey和appSecret，获取access_token进行开发。

4.注意事项

新创建的应用，仅创建者可以在钉钉工作台看到该应用，企业内其他成员无法在企业工作台看到该应用。原因是应用的可使用范围只有当前应用创建者。如果希望企业内其他成员也可以看到并使用该应用，需要设置应用的可使用范围。

三、应用开发

1. 使用安装

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

npm install dingtalk-jsapi –save

如果你的网络环境不佳，推荐使用 cnpm。

示例代码：

import * as dd from ‘dingtalk-jsapi’; // 此方式为整体加载，也可按需进行加载

2. JSAPI鉴权配置

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

2.1 调用JSAPI组件

注意：所有JSAPI组件的调用，必须在dd.ready里面执行。

dd.ready(function() {
    // dd.ready参数为回调函数，在环境准备就绪时触发，jsapi的调用需要保证在该回调函数触发后调用，否则无效。
    dd.runtime.permission.requestAuthCode({
        corpId: "corpid",
        onSuccess: function(result) {
        /*{
            code: 'hYLK98jkf0m' //string authCode
        }*/
        },
        onFail : function(err) {}

    });
});

通过error接口处理失败验证
dd.config验证失败会执行error函数，错误信息可以在返回的error参数中参看，下面为error信息示例:

dd.error(function(error){
    /**
        {
        errorMessage:"错误信息",// errorMessage 信息会展示出钉钉服务端生成签名使用的参数，请和您生成签名的参数作对比，找出错误的参数
        errorCode: "错误码"
        }
    **/
    alert('dd error: ' + JSON.stringify(error));
});

图片浏览示例：

dd.biz.util.previewImage({
    urls: [String],//图片地址列表
    current: String,//当前显示的图片链接
    onSuccess : function(result) {
        /**/
    },
    onFail : function(err) {}
})

2.2 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。
});

鉴权示例：请查看PHP版本Demo.js

2.3 接口约定

2.3.1 所有接口都为异步

2.3.2 接受一个object类型的参数

2.3.3 成功回调 onSuccess(某些异步接口的成功回调，将在事件触发时被调用，具体详情请查看相关onSuccess回调时机)

2.3.4 失败回调 onFail

dd.命名空间.功能.方法({
    参数1: '',
    参数2: '',
    onSuccess: function(result) {
    //成功回调
    /*
    {
        //所有返回信息都输出在这里
    }*/
    },
    onFail: function(){
    //失败回调
    }
})

3. 获取微应用免登授权码

使用以下代码获取免登授权码（调用此api不需要进行鉴权，即不需要进行dd.config）。获取的免登授权码有效期5分钟，且只能使用一次.

dd.ready(function() {
    dd.runtime.permission.requestAuthCode({
        corpId: _config.corpId, // 企业id
        onSuccess: function (info) {
                code = info.code // 通过该免登授权码可以获取用户身份
        }});
});

4. 通过免登授权码换取用户身份

4.1 获取企业凭证

企业凭证，即企业授权给第三方企业应用时，第三方企业应用获取企业的凭证access_token。第三方企业应用可以使用access_token调用接口获取企业的相关信息。

请求方式：POST(HTTPS)

请求地址：https://oapi.dingtalk.com/service/get_corp_token?signature=kKlP1QmmXXX&timestamp=1527130370219&suiteTicket=xxx&accessKey=suitezmpdnvsw4xxxxx

POST请求包结构体:

{
    "auth_corpid":"auth_corpid_value"
}

4.2 获取用户userid

请求方式：GET（HTTPS）

请求地址：https://oapi.dingtalk.com/user/getuserinfo?access_token=access_token&code=code

参数说明：

参数           类型     必须      说明

access_token  String   是     调用接口凭证
code          String   是     免登授权码，参考上述“获取免登授权码”

4.3 获取用户详情

如果想调用通讯录接口并同时获取员工手机号，设置通讯录接口权限和手机号等敏感字段权限

请求方式：GET（HTTPS）

请求地址：https://oapi.dingtalk.com/user/get?access_token=ACCESS_TOKEN&userid=zhangsan

参数说明：

参数           类型     必须      说明

access_token  String   是     调用接口凭证
userid        String   是     员工id
lang          String   否     通讯录语言(默认zh_CN，未来会支持en_US)

钉钉开放平台微应用接入

钉钉开放平台微应用接入

一、概述

二、平台接入

1. 开发者后台管理

1.1 准备页面访问地址

1.2 创建应用

2.填写基本信息

3.查看应用信息

4.注意事项

三、应用开发

1. 使用安装

2. JSAPI鉴权配置

2.1 调用JSAPI组件

2.2 JSAPI鉴权

2.3 接口约定

3. 获取微应用免登授权码

4. 通过免登授权码换取用户身份

4.1 获取企业凭证

4.2 获取用户userid

4.3 获取用户详情

相关地址