dd-app-sdk

钉钉登录业务通用 jssdk

✨ 基础核心依赖

• Typescript
• axios

✨ 功能模块

• 钉钉运行端环境映射
• 离线化透传登录信息

🎉 使用

安装

yarn add dd-app-sdk -D

or

npm i -D dd-app-sdk

调用

页面内 head 中引入 dd-jssdk

<script src="https://g.alicdn.com/dingding/dingtalk-jsapi/2.10.3/dingtalk.open.js"></script>

在项目的入口文件调用

import DDLogin from 'dd-app-sdk'

...
DDLogin.config({
  env: 'dev',   //  环境
  jsApiList: [] //  钉钉内打开时，需要鉴权的jsApiList，只对于钉钉微应用生效，非钉钉内打开应用可传 空数组
})

🔥 版本历史

• 1.0.0 2021/04/13

  • 支持钉钉（桌面/移动端）应用内免密登录
  • 支持非钉钉微应用内打开接入中台单点登录

• 1.0.8 2021/04/20

  • 中台登出功能

☘️ 目录结构

├── LICENSE
├── README.md
├── babel.config.js
├── docs-source
│   ├── .DS_Store
│   ├── docs
│   │   ├── .DS_Store
│   │   ├── .vuepress
│   │   ├── README.md
│   │   ├── core
│   │   ├── enhance
│   │   └── guide
│   ├── package.json
│   └── yarn.lock
├── examples
│   └── index.html
├── jsdoc.json
├── package.json
├── rollup.config.js
├── src
│   ├── declare
│   │   ├── define.ts
│   │   └── profile.ts
│   ├── http
│   │   ├── HttpClient.ts
│   │   └── Service.ts
│   ├── index.ts
│   └── utils
│       ├── Cookie.ts
│       └── DB.ts
├── tsconfig.json
├── yarn-error.log
└── yarn.lock

🧭 指令

• yarn tree
  显示目录树

• yarn install
  安装依赖

• yarn build
  构建 npm 包

• yarn docs:dev
  文档服务本地启动

• yarn docs:build 编译文档服务项目

🛎️ 编译环境变量参数说明

• BUILD_ENV 数据库连接环境，接口域名
  • local: 本地开发，相对路径，会走 node 的转发代理
  • dev: dev 域名
  • test: test 域名
  • uat: uat 域名
  • prod: prod 域名

rollup 插件配置

• rollup-plugin-typescript2
  • rollup-plugin-typescript 无法完成 ts 声明文件的导出，替换为 typescript2 插件

🎉 其他

• 关于钉钉鉴权

  • 调用后端 ddConfig 接口时传入的 url，必须与当前页面的 url 一致即可，不需要与后台配置的应用首页地址一致。

  使用文档

  内部系统或者外采系统集成到中台，前端应用接入中台单点登录流程

中台登录方式

前端应用场景

登录集成

• 钉钉 APP 内打开，使用钉钉免密登录

• PC 端 web 系统，使用中台扫码登录

统一登录 JSSDK

npm 包名

• [email protected]

适配项目

• jssdk 使用 typescript 编写，且与前端框架解耦，支持 js 或 ts 项目的编写环境，也支持各种语言框架(React/Vue/Angular/JQuery)的集成

问题反馈

• 钉钉联系 @李洋高金食品

接入完整流程

PC 端 web 系统

1. 安装依赖

yarn add dd-app-sdk -D
// or
npm i dd-app-sdk -D

1. 原始模板 html 文件 head 标签中中引入钉钉 jsapi 文件

<script src="https://g.alicdn.com/dingding/dingtalk-jsapi/2.10.3/dingtalk.open.js"></script>

1. 入口文件引入

vue 项目

// App.vue
<script>
import DDLogin from 'dd-app-sdk'

export default {
	mounted() {
	    DDLogin.config({
		     env: 'dev' // 传入环境变量值
	    });
	},
}
</script>

react 项目

// your root component
import React from "react";
import DDLogin from "dd-app-sdk";

export default class Root extends React.Component {
  componentDidMount() {
    DDLogin.config({
      env: "dev", // 传入环境变量值
    });
  }
}

1. 前端通常会使用 axios 拦截器来进行登录鉴权，鉴权逻辑由开发者实现。以下是如何 token 携带，以及鉴权未通过后手动调用中台登录的实现 demo

axios.interceptors.request.use((config) => {
  config.headers["Access-Token"] = DDLogin.getToken();
});

axios.interceptors.response.use(
  (res) => {
    // do your susccess callback
  },
  (error) => {
    if (error.response.status === 401) {
      DDLogin.configSSO({
        env: "dev",
      });
    }
  }
);

1. 任何时候需要调用中台登录（无论是否登录），使用**DDLogin.configSSO**这个 api

钉钉 H5 微应用

1. 安装依赖

yarn add dd-app-sdk -D
// or
npm i dd-app-sdk -D

1. 原始模板 html 文件 head 标签中中引入钉钉 jsapi 文件

<script src="https://g.alicdn.com/dingding/dingtalk-jsapi/2.10.3/dingtalk.open.js"></script>

1. 入口文件引入

vue 项目

// App.vue
<script>
import DDLogin from 'dd-app-sdk'

export default {
	mounted() {
	    DDLogin.config({
		    env: 'dev',  // 传入环境变量值
			jsApiList: [ // 需要授权使用的jsapi
				'biz.contact.complexPicker',
			    'biz.contact.departmentsPicker',
		        'device.geolocation.get',
	            'biz.util.chooseImage',
	            'biz.util.uploadImage',
	            'biz.util.uploadImageFromCamera',
	            'biz.telephone.showCallMenu'
			]
	    });
	},
}
</script>

react 项目

// your root component
import React from "react";
import DDLogin from "dd-app-sdk";

export default class Root extends React.Component {
  componentDidMount() {
    DDLogin.config({
      env: "dev", // 传入环境变量值
      jsApiList: [
        // 需要授权使用的jsapi
        "biz.contact.complexPicker",
        "biz.contact.departmentsPicker",
        "device.geolocation.get",
        "biz.util.chooseImage",
        "biz.util.uploadImage",
        "biz.util.uploadImageFromCamera",
        "biz.telephone.showCallMenu",
      ],
    });
  }
}

1. 前端通常会使用 axios 拦截器来进行登录鉴权，鉴权逻辑由开发者实现。以下是如何 token 携带，以及鉴权未通过后手动调用钉钉免密登录的实现 demo

axios.interceptors.request.use((config) => {
  config.headers["Access-Token"] = DDLogin.getToken();
});

axios.interceptors.response.use(
  (res) => {
    // do your susccess callback
  },
  (error) => {
    if (error.response.status === 401) {
      DDLogin.configSSO({
        env: "dev",
      });
    }
  }
);

1. 任何时候需要调用钉钉免密登录授权，使用**DDLogin.config**这个 api

API 文档-属性

DDLogin.configuation

config 配置项对象

DDLogin.configuation
// 返回
{
	env: 'dev',
    jsApiList: ['some.api.list']
}

DDLogin.accessTokenCookieKey

中台登录后存储在 cookie 中的 token-key，[ENV].sso.login.account.operation.auth

DDLogin.accessTokenCookieKey;

// 返回
("dev.sso.login.account.operation.auth"); // dev环境
("test.sso.login.account.operation.auth"); // test环境
("uat.sso.login.account.operation.auth"); // uat环境
("sso.login.account.operation.auth"); // prod环境

DDLogin.runtimeDeviceEnv

当前环境

DDLogin.runtimeDeviceEnv;

// 返回
("dev");

API 文档-方法

DDLogin.config

初始化配置，开发者需注意，config 方法会自动识别当前运行端环境是钉钉应用还是非钉钉应用，但 jsApiList 在钉钉应用中为必传参数。当未登录时，钉钉应用会自动调用登录，非钉钉应用会跳转中台单点登录。

DDLogin.config({
  env: "dev",
  jsApiList: [],
});

DDLogin.configSSO

强制调用中台单点登录，只能在非钉钉应用内调用。

DDLogin.config({
  env: "dev",
});

DDLogin.hasToken

查询 cookie 中是否已存在 token

DDLogin.hasToken();

// 返回
true;

DDLogin.getToken

获取 token

DDLogin.getToken();

// 返回
("ejluo1jl990jljlfdf-01ld-dfljl19gjobm1");