mock
title: 模多客企业版移动 SDK 需求文档
grammar_cjkRuby: true
1 流程图
主线流程图
1.1 初始化
在此处创建 WebView，并初始化控件属性：
| 属性名称 | 类型 | 说明 |
|---|---|---|
width |
[number, string] |
WebView的宽，设置同系统WebView |
height |
[number, string] |
WebView的高，设置同系统WebView |
task |
string |
模型的 task ID |
cache_dir |
string |
开发者设定的本地储存路径 |
verification |
JSON |
包含企业 Open API 认证所需的信息 |
1.2 检查是否联网
在此处检查是否联网，如未联网进入离线模式。
1.3 获取模型信息同时完成认证
使用开发者提供的 verification 构建一个 HTTP Header， 访问获取模型信息接口，如果成功，则代表认证成功，同时记录下返回的信息，尤其是其中的 src 信息，是显示 3D 模型必须的，另外可以在这里派发一个事件，将其他信息传递给开发者，让开发者自行处理利用；如果认证失败，则抛出异常，终止后续步骤，根据服务器返回的错误信息提示用户。
verification 包含三个键值，分别是：
| 键值 | 类型 | 说明 |
|---|---|---|
user |
String |
企业版 Open API 用户名 |
signature |
String |
企业版 Open API 认证签名 |
timestamp |
[String, Number] |
生成签名时的时间戳 |
示例代码：
HttpsURLConnection conn = (HttpsURLConnection) url.openConnection();
conn.setUseCaches(false);
conn.setRequestMethod("GET");
conn.setSSLSocketFactory(sf);
// 构建 HTTP Header
conn.setRequestProperty("user", userName);
conn.setRequestProperty("signature", signature);
conn.setRequestProperty("timestamp", String.valueOf(timeStamp));
log("headers=" + conn.getRequestProperties());
conn.connect();
注意： Open API 服务器会对请求头中的时间戳进行校验，任何与服务器时间间隔超过 90 秒的请求将被拒绝。因此要在收到开发者提供的
verification后的 90 秒内完成认证。
请求接口：参考下文 1.7.2 通过 task 获取 src
1.4 检查 Bin 版本
请求 Restful API 接口，获取最新版 Bin 的 MD5 值，与本地 Bin 的 MD5 值比对。若不相同则进行在线更新，下载最新的 Bin 文件。
1.5 解压缩 Bin 文件
Bin 文件是指由显示模型所需的 .html 文件和 .js 文件使用 zip 压缩并偏移后得到的二进制文件。
解压缩 Bin 文件，并将 html 文件载入 WebView。
1.6 检查本地缓存
在开发者设定的 cache_dir 目录中查找对应于 task 的缓存目录。如果找到缓存文件，则优先加载此目录中的模型文件，即此目录优先级高于从模型信息接口获取到的 src。
加载出错时，如遇到文件不存在或其他 IO 错误，抛出异常。
在离线模式下，提示用户联网。
在在线模式下，切换至读取模型信息中的 src 路径，进行在线加载。
1.7 将模型信息传递至 Javascript 显示模型
Javascript 显示模型需要两个属性：
| 变量名 | 类型 | 说明 |
|---|---|---|
| gltf | JSON | gltf 是一种基于 JSON 的 3D 模型格式。通过 Open API 获取。最大不超过 16MB。 |
| src | String | 模型相关文件的储存路径 。通过 Open API 获取。 |
1.7.1 通过 task 获取 gltf
-
接口地址：
https://api.e.modocker.com/v1/model/gltf/:task -
方法：
GET -
认证： 无需认证
-
返回参数说明：
| 返回字段 | 类型 | 说明 |
|---|---|---|
errcode |
int | 错误代码，0代表成功 |
errmsg |
String | 错误信息 |
data |
JSON | 返回的 gltf 数据 |
- 返回示例：
{
"errcode": 0,
"errmsg": "success.",
"data": {
// gltf 数据，太长了，省略
}
}
1.7.2 通过 task 获取 src
-
接口地址：
https://api.mdkrapi.com/open/e/v1/model/:task -
方法：
GET -
认证：需要企业版 Open API 认证
-
返回参数说明：
| 返回字段 | 类型 | 说明 |
|---|---|---|
errcode |
int | 错误代码，0代表成功 |
errmsg |
String | 错误信息 |
data |
JSON | 返回的模型信息，其中只用到 src，其余信息无需处理，可交由开发者自行处理 |
- 返回示例：
{
"errcode": 0,
"errmsg": "success",
"data": {
"ani": 0,
"company_id": 4,
"company_logo": "{\"url\":\"//oss.image.mdkrcdn.com/2018/02/09/5xlv5h3t6pl/logo.png\",\"size\":70,\"tile\":true,\"link\":\"http://e.modocker.com\",\"position\":\"top-right\"}",
"create_at": "2018-05-02T16:30:00+08:00",
"desc": "",
"download_options": "{}",
"download_src": "/model/7F3eXOBDus685edT7JtuN4037un8Ebze/5bP7d1sbJEJ3X3Mh2tr62ePHWQ8fy9p2.zip",
"faceNum": 992,
"imgs": [
{
"path": "/model/2018/05/02/598578ec2c173c7a165c96b949876f5a.jpg"
},
{
"path": "/model/2018/05/14/53f40e45864e34f3d06d9d4ee55cf762.jpg"
},
{
"path": "/model/2018/05/14/93e278917ff06bdf0cd1fdffc4bdf5e7.jpg"
}
],
"imgurl": "/model/2018/05/14/93e278917ff06bdf0cd1fdffc4bdf5e7.jpg",
"is_download": 0,
"library_id": 6,
"materialCount": 1,
"pv": 2,
"rawFileExt": "FBX",
"scaleRate": 0.0028674628119915724,
"size": 0,
"src": "/cok/2018/05/14/5bP7d1sbJEJ3X3Mh2tr62ePHWQ8fy9p2",
"status": 1,
"title": "z.FBX",
"unitSystem": "英寸",
"voice": ""
}
}
2 Bin 文件压缩与解压缩工具
- 压缩工具操作系统：Linux
- 解压缩工具操作系统：Android / iOS
- 压缩格式：Zip
- 加密方式：字节偏移
需要提供一个压缩工具，用于后端系统集成；
需要提供一个解压缩工具，用于 SDK 集成。
3 SDK 系统版本最低需求
- Android：Android 5.0 及以上
- iOS： iOS 8.0 及以上
上述版本以下的操作系统，不支持 WebGL 无需考虑。
4 SDK WebView
既可以使用系统自带的 WebView，也可以使用腾讯X5(https://x5.tencent.com/)
需要搭建本地 HTTP Server 载入 HTML 和 JS，以避免 WebView 的安全限制问题。
