# DCloud开放平台DSP对接规范
名词解释：
- DSP：developer service provider，为开发者提供服务的三方厂商
# 开发者服务商（DSP）入驻DCloud开放平台
- DSP在DCloud开放平台https://open.dcloud.net.cn/注册账号，需企业实名认证。
- 注册成功后，由DCloud分配账号级
dspId，dspSecret。
# DSP配置开户所需信息
DSP入驻DCloud开放平台后，需配置希望获取开发者哪些信息，以及是否支持个人用户开户：
- 可选信息：
email，phone，realname，nickname，identity（个人为身份证号、企业为营业执照），bankInfo（开户行，开户名称，银行账号） - 是否支持个人用户
- 账号接口地址，用于接受DCloud开放平台同步过来的用户信息（邮箱、手机号、实名信息等）；API接口定义见下文。
# DSP注册SDK
- DSP按照uniapp插件规范开发相关插件，并发布到插件市场；
- 注册SDK产品，补充完善以下信息：
- SDK支持的平台，如
app-android,app-ios,mp-weixin等； - 各平台开通服务时，需要的应用信息字段（区分必填、选填；如应用名称、包名、证书摘要等）；
- 插件市场的插件ID（必填）；
- 是否支持测试包名、测试证书；
- 各平台的备注信息（在DCloud开放平台向用户展示，可以添加SDK文档链接等）
- 录入DSP API接口地址。API接口定义见下文。
- 创建应用、修改应用接口返回参数的字段名称、描述信息、在原生平台需要标识保存在
AndroidManifest、plist的位置
- SDK支持的平台，如
{
"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平台发起账号注册、修改、注销等流程。
具体流程为：
- 开发者登录DCloud系统
- 选择需要开户的DSP平台
- 开发者授权可向DSP同步的个人信息（手机号、邮箱、实名信息等）
- DCloud系统通过接口方式请求DSP平台，将用户信息发送过去
- DSP平台返回操作结果（如：注册成功、失败以及失败原因等）
# 注册
接口示例 /auth/register
请求参数
{
"dcloudOpenUid": "", // DCloud开放平台用户标识
"email": "mail@dcloud.io", // 账号绑定的邮箱
"phone": "13012345678", // 账号绑定的手机号
"userType": 1, // 用户类型：1为个人，2为企业
"name": "张三", // 用户名称。个人用户为姓名。企业用户为企业名称
"identity": "110110199001011234", // 个人用户为身份证号，企业用户为营业执照
"bankInfo": {
"bank": "招商银行北京支行", // 开户银行
"name": "张三", // 开户名
"account": "12345678" // 银行账号
}
"timestamp": 1633665031,
}
- 返回参数
{
"errCode": 0,
"errMsg": "success"
}
# 同步用户信息
接口同注册接口。
# 注销账号
开发者通过一键登录，在DSP平台中注销。
# 开发者一键登录DSP平台
开发者登录DCloud系统后，可一键登录DSP平台，避免二次登录，优化体验。
一键登录分为两个步骤：
- DCloud平台通过接口请求DSP平台，获取authToken
- DCloud平台通过authToken，跳转DSP平台系统
# 获取authToken
接口示例 /auth/token
请求参数
{
"dcloudOpenUid": "",
"timestamp": 1633665031,
}
- 返回参数
{
"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
请求参数
{
"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,
}
- 返回参数
{
"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
请求参数
{
"pluginId": "",
"authToken": "",
"dspAppid": "",
"appName": "",
"appDesc": "",
"platforms": { // 如果没有某个平台的参数，表示删除该平台配置
"app-android": {
"releasePackageName": "",
"debugPackageName": "",
"releaseCertSha1": "",
"debugCertSha1": "",
}
},
"timestamp": 1633665031,
}
- 返回参数
{
"errCode": 0,
"errMsg": "success",
"data": {
"dspAppid": "",
"platforms": { // 此处返回的字段与SDK注册时配置的字段一致
"server": { // 客户端配套的server配置
"secret": "",
},
"app-android": {
"appid": "",
"appKey": "",
"appSecret": "",
}
}
}
}
# 删除应用
接口示例 /app/delete
请求参数
{
"pluginId": "",
"authToken": "",
"dspAppid": "",
"timestamp": 1633665031,
}
- 返回参数
{
"errCode": 0,
"errMsg": "success",
}
# DSP使用DCloud账号登录（OAuth协议)
完整文档参考：https://ask.dcloud.net.cn/article/38005
# HBuilderX插件
# Web平台
# 附录
# 接口数据传输规范
# 编码方式
- 本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
# 加密数据示例
# 示例加密密钥
gCANeLWoh2CDulqLf0mVAartUFxoPqCn
# 加密原文
{"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
