open.md

# DCloud开放平台DSP对接规范

名词解释：

- DSP：developer service provider，为开发者提供服务的三方厂商


## 开发者服务商（DSP）入驻DCloud开放平台
- DSP在DCloud开放平台[https://open.dcloud.net.cn/](https://open.dcloud.net.cn/)注册账号，需企业实名认证。
- 注册成功后，由DCloud分配账号级`dspId`，`dspSecret`。

## DSP配置开户所需信息

DSP入驻DCloud开放平台后，需配置希望获取开发者哪些信息，以及是否支持个人用户开户：
- 可选信息：`email`，`phone`，`realname`，`nickname`，`identity`（个人为身份证号、企业为营业执照），`bankInfo`（开户行，开户名称，银行账号）
- 是否支持个人用户
- 账号接口地址，用于接受DCloud开放平台同步过来的用户信息（邮箱、手机号、实名信息等）；API接口定义见下文。

## DSP注册SDK
- DSP按照uniapp插件规范开发相关插件，并发布到[插件市场](https://ext.dcloud.net.cn)；
- 注册SDK产品，补充完善以下信息：
	- SDK支持的平台，如`app-android`, `app-ios`, `mp-weixin`等；
	- 各平台开通服务时，需要的应用信息字段（区分必填、选填；如应用名称、包名、证书摘要等）；
	- 插件市场的插件ID（必填）；
	- 是否支持测试包名、测试证书；
	- 各平台的备注信息（在DCloud开放平台向用户展示，可以添加SDK文档链接等）
	- 录入DSP API接口地址。API接口定义见下文。
	- 创建应用、修改应用接口返回参数的字段名称、描述信息、在原生平台需要标识保存在`AndroidManifest`、`plist`的位置
```json
{
	"app-android": { // 平台
		"appid": { // 该平台创建应用时，返回的字段名称
			"title": "appid", // 字段在页面上的展示名称
			"desc": "应用标识", // 字段描述
			"androidManifest": { // 可选，如果需要在打包时将此字段配置到AndroidManifest，需要提供AndroidManifest中字段名称
				"metaDataName": "dcloud_appid"
			}
		},
		"appKey": {
			"title": "",
			"desc": "",
			"androidManifest": { 
				"metaDataName": "dcloud_appkey"
			}
		},
		"appSecret": {
			"title": "",
			"desc": ""
		}
	},
	"app-ios": {
		"appKey": {
			"title": "",
			"desc": "",
			"plist": { // 可选，如果需要在打包时将此字段配置到plist，需要提供plist的参数配置路径
				"keyPath": "sms:config:appKey"
			}
		},
	},
	"server": {
		"masterSecret": {
			"title": "",
			"desc": "",
			"uniConfigCenter": { // 可选。此字段需要配置到uni-config-center
				"pluginId": "", // 此字段是uni-config-center的pluginId。不是插件市场的插件ID。
				"keyPath": "sms:config:masterSecret" // 参数配置路径
			}
		}
	}
}
```


## 开发者向DSP一键开户

开发者可在DCloud系统中，向DSP平台发起账号注册、修改、注销等流程。

具体流程为：
1. 开发者登录DCloud系统
2. 选择需要开户的DSP平台
3. 开发者授权可向DSP同步的个人信息（手机号、邮箱、实名信息等）
4. DCloud系统通过接口方式请求DSP平台，将用户信息发送过去
5. DSP平台返回操作结果（如：注册成功、失败以及失败原因等）


### 注册 

- 接口示例
/auth/register

- 请求参数
```json
{
	"dcloudOpenUid": "",  // DCloud开放平台用户标识
	"email": "mail@dcloud.io", // 账号绑定的邮箱
	"phone": "13012345678", // 账号绑定的手机号
	"userType": 1, // 用户类型：1为个人，2为企业
	"name": "张三", // 用户名称。个人用户为姓名。企业用户为企业名称
	"identity": "110110199001011234", // 个人用户为身份证号，企业用户为营业执照
	"bankInfo": {
		"bank": "招商银行北京支行", // 开户银行
		"name": "张三", // 开户名
		"account": "12345678" // 银行账号
	}
	"timestamp": 1633665031,
}
```

- 返回参数
```json
{
	"errCode": 0,
	"errMsg": "success"
}
```

### 同步用户信息
接口同注册接口。

### 注销账号
开发者通过一键登录，在DSP平台中注销。

## 开发者一键登录DSP平台

开发者登录DCloud系统后，可一键登录DSP平台，避免二次登录，优化体验。

一键登录分为两个步骤：
1. DCloud平台通过接口请求DSP平台，获取authToken
2. DCloud平台通过authToken，跳转DSP平台系统

### 获取authToken
- 接口示例
/auth/token

- 请求参数
```json
{
	"dcloudOpenUid": "",
	"timestamp": 1633665031,
}
```

- 返回参数
```json
{
	"errCode": 0,
	"errMsg": "success",
	"data": {
		"authToken": "",  // 登录凭证，应用相关接口都通过authToken鉴权
		"expire": 3600	 // authToken过期时间，单位为秒
	}
}
```

### 一键登录
- 说明：通过authToken可免登录打开DSP平台。DSP解析dspId,authToken，实现DSP平台自登录。
- 跳转DSP平台地址示例，如：`https://dspdomain.com?dspId=xxx&authToken=xxx`

## 开发者向DSP注册应用

开发者可在DCloud系统中，向DSP平台发起应用注册、修改、删除流程。

### 创建应用
- 接口示例
/app/create

- 请求参数
```json
{
	"pluginId": "",
	"authToken": "",
	"appName": "",
	"appDesc": "",
	"platforms": { // 此字段对应SDK注册时，DSP选择的平台。同时开发者在开通时可选择开通一个或多个平台
		"app-android": {
			"releasePackageName": "",
			"debugPackageName": "",
			"releaseCertSha1": "",
			"debugCertSha1": "",
		},
		"app-ios": {
			"releaseBundleId": "",
			"debugBundleId": "",
		},
		"mp-wexin": {
			"wxAppid": "",
		},
		"web": {
			"domains": ["dcloud.io", "dcloud.net.cn"]
		},
		"webService": {
			"ips": ["1.2.3.4","1.2.3.*"],
			"domains": ["dcloud.io", "dcloud.net.cn"]
		}
	},
	"timestamp": 1633665031,
}
```

- 返回参数
```json
{
	"errCode": 0,
	"errMsg": "success",
	"data": {
		"dspAppid": "",
		"platforms": { // 此处返回的字段与SDK注册时配置的字段一致
			"server": { // 客户端配套的server配置
				"secret": "",
			},
			"app-android": {
				"appid": "",
				"appKey": "",
				"appSecret": "",
			},
			"app-ios": {
				"appid": "",
				"appKey": "",
				"appSecret": "",
			},
			"mp-weixin": {
				
			},
			"web": {
				"appKey": "",
				"jscode": ""
			},
			"webService": {
				
			}
		}
	}
}
```

### 修改应用信息

**注意：** 修改应用信息时，传递的是全量数据。如果某个平台以前开通过，在修改时没有传递，表明开发者需要删除该平台的配置。

- 接口示例
/app/modify

- 请求参数
```json
{
	"pluginId": "",
	"authToken": "",
	"dspAppid": "",
	"appName": "",
	"appDesc": "",
	"platforms": { // 如果没有某个平台的参数，表示删除该平台配置
		"app-android": {
			"releasePackageName": "",
			"debugPackageName": "",
			"releaseCertSha1": "",
			"debugCertSha1": "",
		}
	},
	"timestamp": 1633665031,
}
```

- 返回参数
```json
{
	"errCode": 0,
	"errMsg": "success",
	"data": {
		"dspAppid": "",
		"platforms": { // 此处返回的字段与SDK注册时配置的字段一致
			"server": { // 客户端配套的server配置
				"secret": "",
			},
			"app-android": {
				"appid": "",
				"appKey": "",
				"appSecret": "",
			}
		}
	}

}
```

### 删除应用
- 接口示例
/app/delete

- 请求参数
```json
{
	"pluginId": "",
	"authToken": "",
	"dspAppid": "",
	"timestamp": 1633665031,
}
```

- 返回参数
```json
{
	"errCode": 0,
	"errMsg": "success",
}
```


## DSP使用DCloud账号登录（OAuth协议)
完整文档参考：[https://ask.dcloud.net.cn/article/38005](https://ask.dcloud.net.cn/article/38005)

### HBuilderX插件
![](https://ask.dcloud.net.cn/uploads/article/20201110/2514e1ec371bdebbb9a4111052939720.png)

### Web平台
![](https://ask.dcloud.net.cn/uploads/article/20220914/3bc9cb477832756cc727f3c550b4fcd0.jpg)

## 附录

### 接口数据传输规范
#### 编码方式
- 本API文档所涉及接口均遵循HTTP协议；
- 所有请求的ContentType在不明确指定的情况下均为application/x-www-form-urlencoded；
- 所有返回的ContentType在不明确指定的情况下均为application/json；
- 若无特殊说明或响应头中的Content-Type未指定编码，请求和响应中的字符编码均使用 UTF-8（无 BOM 头）。

#### HTTP请求方式
如无特殊说明，API请求的HTTP Method均为POST 

#### URL定义
URL请求域名由DSP提供，协议：必须使用HTTPS。本文接口详述中使用的请求URL均为示例，实际上线时的URL以DSP提供的为准。

#### 请求参数
接口中描述的请求参数全部加密传输。请求参数只包含以下字段：

|名称	|类型	|必填	|描述												|
|--		|--		|--		|--													|
|dspId	|int	|是		|DSP在DCloud开放平台注册账号后，DCloud返回的dspId	|
|data	|string	|是		|各接口中定义的json string加密后的数据，加密数据见下文描述		|

#### 接口响应
- HTTP状态码

支持HTTP标准状态码，具体如下：

|状态码	|名称				|描述														|
|--		|--					|--															|
|200	|成功				|当 API 请求被正确处理，且能按设计获取结果时，返回该状态码；|
|4xx	|接口调用方端错误	|由接口调用方端原因造成的错误								|
|5xx	|DSP服务器端错误	|DSP API或其下层服务发生内部错误							|

- HTTP Header

接口DSP API响应的Content-Type应为application/json。 

- HTTP Body

响应的JSON数据中包含三部分内容，分别为状态码、返回信息和数据，如下表所示：

|名称	|类型		|必填	|描述										|
|--		|--			|--		|--											|
|errCode|int		|是		|状态码： 0表示成功；其它表示错误			|
|errMsg	|string		|是		|返回信息：若有错误，此字段为详细的错误信息	|
|data	|json object|否		|响应数据。此字段加密传输，加密前为json string。接口无需返回数据时，此字段为空。	|

#### 数据加密算法
所有要求加密的字段均采用AES256加密算法进行加密，加密后的数据使用base64编码。在DSP注册账号后，由DCloud开放平台提供加密的密钥`dspSecret`。
- 加密算法：AES256
- 加密模式：CBC
- 填充方式：Pkcs7 | Pkcs5
- 向量（偏移量）：同密钥
- 加解密测试网站： [https://www.mklab.cn/utils/aes](https://www.mklab.cn/utils/aes)

#### 加密数据示例
##### 示例加密密钥
`gCANeLWoh2CDulqLf0mVAartUFxoPqCn`

##### 加密原文
```json
{"pluginId":"1000","appName":"测试应用","appDesc":"测试应用","platforms":{"app-android":{"releasePackageName":"io.dcloud.sample","debugPackageName":"io.dcloud.sample.debug","releaseCertSha1":"E1:EF:48:A5:BE:E7:64:3E:61:A7:19:5C:FA:23:B1:30:83:29:42:7E","debugCertSha1":"83:85:A9:68:D3:C0:99:E3:20:E0:37:75:81:C5:66:F3:F3:CD:98:78"},"app-ios":{"releaseBundleId":"io.dcloud.sample","debugBundleId":"io.dcloud.sample.debug"}}}
```

##### 加密密文
```
GaySFnUw5yrvM3QPbdtqU7jCeozMPpy0vMv4Z7eaUSPjg9YYvXQw66QMOmYIBo4G862uWAX+4f5X1fJlOXWq2tr7S34hH0qftQ9rwLVKWt6mlhqfCh9GVSTsSv4vcV9HNePrmzxmMhEwDXWlWqaC2xXWd/94/Y07HuNPFR63yl3LTyIn8Y/0pACh7+rlwb44yYeQmI9MNymr7aa5d8RSWhGQ9EC3cPKV7qJjJ7fSXvILKpqIHqzeUecF3ydgIXGF4xzYZIqdgztGace4ddNEVnE7RJmz5F33RyyXMb1K1pjJKOjxZY1CMcNwZvpv4woxHzAJzmbtpHFHaXBJrP1kW3meJ9gqqriAn6Y1yNotkl6ffOVHfkR4G/d69wuOBC2l+KdcMqjnQ+6ijG/eDNzLdaSnpQjpo3+VyQunAZvxTJzxLaFV+K4ob9loxf3a/eCXjMbnybqmSMAQ1H+R2LqTHMtzh5B6bO9UInT44ad92EllKsvVgkzSFSjlPh6JfcdYHHXm/zA5bYvvkyJ9PSeH3sP2mgRXMBfGruqMjarhtPt3FIh3kPV2zTGJgs1Z139r
```