# dd-app-sdk

> 钉钉应用统一登录jssdk

Latest version **1.0.13** (published 2021-04-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install dd-app-sdk
pnpm add dd-app-sdk
yarn add dd-app-sdk
bun add dd-app-sdk
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.13 |
| Published | 2021-04-20 |
| First published | 2021-04-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 15 |
| Unpacked size | 1 MB |
| Known vulnerabilities | 0 (+23 in 1 direct dependencies) |
| Install scripts | no |
| Author | liyang66 |
| Maintainers | liyangltc3600 |
| Keywords | dd-login, rollup, jssdk, typescript |

## Links

- npm: https://www.npmjs.com/package/dd-app-sdk
- Repository: https://github.com/ly4work/dd-app-sdk
- Homepage: https://github.com/ly4work/dd-app-sdk#readme
- Issues: https://github.com/ly4work/dd-app-sdk/issues
- npm.io page: https://npm.io/package/dd-app-sdk

## Dependencies (15)

- [axios](https://npm.io/package/axios.md) ^0.21.1
- [jsdoc](https://npm.io/package/jsdoc.md) ^3.6.6
- [tslib](https://npm.io/package/tslib.md) ^2.1.0
- [rollup](https://npm.io/package/rollup.md) ^2.40.0
- [typescript](https://npm.io/package/typescript.md) ^4.2.3
- [@babel/core](https://npm.io/package/@babel/core.md) ^7.13.14
- [@types/axios](https://npm.io/package/@types/axios.md) ^0.14.0
- [@rollup/plugin-json](https://npm.io/package/@rollup/plugin-json.md) ^4.1.0
- [rollup-plugin-babel](https://npm.io/package/rollup-plugin-babel.md) ^4.4.0
- [rollup-plugin-uglify](https://npm.io/package/rollup-plugin-uglify.md) ^6.0.4
- [rollup-plugin-commonjs](https://npm.io/package/rollup-plugin-commonjs.md) ^10.1.0
- [rollup-plugin-typescript](https://npm.io/package/rollup-plugin-typescript.md) ^1.0.1
- [rollup-plugin-typescript2](https://npm.io/package/rollup-plugin-typescript2.md) ^0.30.0
- [rollup-plugin-node-resolve](https://npm.io/package/rollup-plugin-node-resolve.md) ^5.2.0
- [rollup-plugin-node-polyfills](https://npm.io/package/rollup-plugin-node-polyfills.md) ^0.2.1

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 1.0.13 (latest) — 2021-04-20
- 1.0.12 — 2021-04-20
- 1.0.11 — 2021-04-20
- 1.0.10 — 2021-04-20
- 1.0.9 — 2021-04-20
- 1.0.8 — 2021-04-20
- 1.0.7 — 2021-04-20
- 1.0.6 — 2021-04-20
- 1.0.5 — 2021-04-20
- 1.0.4 — 2021-04-16
- 1.0.3 — 2021-04-15
- 1.0.2 — 2021-04-15
- 1.0.1 — 2021-04-12
- 1.0.0 — 2021-04-12

## README

# dd-app-sdk

> 钉钉登录业务通用 jssdk

### ✨ 基础核心依赖

- Typescript
- axios

### ✨ 功能模块

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

### 🎉 使用

#### 安装

```shell
yarn add dd-app-sdk -D

```

or

```
npm i -D dd-app-sdk
```

#### 调用

页面内 head 中引入 dd-jssdk

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

在项目的入口文件调用

```javascript
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 包名

- dd-app-sdk@1.0.5

### 适配项目

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

### 问题反馈

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

## 接入完整流程

### PC 端 web 系统

1. 安装依赖

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

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

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

1. 入口文件引入

**vue 项目**

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

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

**react 项目**

```javascript
// 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

```javascript
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. 安装依赖

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

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

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

1. 入口文件引入

**vue 项目**

```javascript
// 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 项目**

```javascript
// 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

```javascript
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 配置项对象

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

### DDLogin.accessTokenCookieKey

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

```javascript
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

当前环境

```javascript
DDLogin.runtimeDeviceEnv;

// 返回
("dev");
```

## API 文档-方法

### DDLogin.config

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

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

### DDLogin.configSSO

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

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

### DDLogin.hasToken

查询 cookie 中是否已存在 token

```javascript
DDLogin.hasToken();

// 返回
true;
```

### DDLogin.getToken

获取 token

```javascript
DDLogin.getToken();

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

---
_Source: https://npm.io/package/dd-app-sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._