[TOC]
# 创客贴移动端 API 文档 1.2.1
## DEMO
[在线预览](https://m.chuangkit.com/mapidemo)
## 使用
### 引入 SDK
方式一：
在网页的`<body>`中任意位置写入以下代码：
```html
<script>(function(d,s,a){var w=d.createElement(s),s=d.getElementsByTagName(s)[0];w.src=a;s.parentNode.insertBefore(w,s);})(document,'script','https://static.chuangkit.com/api/v1.2.m.js');</script>
```
方式二：
```sh
npm install @chuangkit/chuangkit-design
```
### 调起
组装调起创客贴 API 所需的参数对象（参数主要来控制创客贴 API 调起后的形态，比如画布尺寸），对象写法如下（对象中支持参数说明见 [附录](#appendix)）：
```js
var option = {
"data-access": "",
"data-exp": "",
"sign": "",
"signType": ""
}
```
调起创客贴 API 之前须进行实例化，如下：
方式一：
```js
var cktMobile = new ChuangkitMobile(option)
```
方式二：
```js
import cktDesign from "@chuangkit/chuangkit-design"
var design = new cktDesign(option)
```
实例化后即可在需要时调起创客贴 API：
```js
cktMobile.openMobile()
// 方式一
design.openMobile() // 方式二
```
<a id="appendix"></a>
## 附录
<a id="init-params"></a>
### 初始化参数说明
> 目前已知 Microsoft Edge 等浏览器渲染个别字符存在问题，导致从本文档复制的参数在后续签名后验证不通过，若排查参数名无误后仍然报错，请更换 PDF 浏览器或手动输入参数名
|参数名|必选|类型|默认值|说明|
|:--|:--|:--|:--|:--|
|data-access|是|string||创客贴分配的企业 appId|
|data-exp|是|timestamp||参数生效截止时间的毫秒时间戳（自定义，须晚于当前时间，超过该时间后再调起创客贴 jssdk 将无法通过通过权限校验）|
|sign|是|string||参数签名（签名生成方式详见文档最下方 [附录 参数签名生成方式](#sign)）|
|signType|是|string||加密算法，目前仅支持 MD5|
|data-ext-ref-user-flag|是|string||用于**保留用户资产（制作的设计、购买的模板等）**，不传该参数则每次调用均创建临时账户。保证该标识与贵平台的用户一一对应即可，推荐使用贵平台用户的用户 ID|
|data-design-id|否|string||已存在的设计ID（修改设计时使用该参数）|
### 附加参数说明
参数名|必选|类型|默认值|说明
---|---|---|---|---
data-extra-path|否|string|home|需要跳转的页面，可由 [创客贴 M 站](https://m.chuangkit.com) 获取
data-extra-kind-ids|否|string|-|指定显示的场景（例子见 data-extra-kind-ids 参数示例），多个以英文逗号分隔。（场景对应的 ID 见 [附录 场景对应表](#scenelist)）
data-extra-get-user-design-url|否|string|-|创客贴通过传参方式回传用户设计图地址到该 URL。回传参数示例见下方
data-extra-hide-bar|否|number|0|是否隐藏底部 tab。1:隐藏;0:显示
**注：附加参数(data-extra 开头)不参与签名**
#### data-extra-path 参数常用值
值|说明
---|---
apiscene|展示自有场景及模板页面（详询市场人员）
mydesign|用户设计列表页面
#### data-extra-kind-ids 参数示例
目的|示例
---|---
显示所有场景入口|不传
只显示一个场景|data-extra-kind-ids=12
显示多个场景入口|data-extra-kind-ids=4,12,20，将要在首屏显示的场景写在首位
显示全部场景入口，并指定首屏显示的场景|data-extra-kind-ids=4,0
#### data-extra-get-user-design-url 回传参数示例
示例：${data-extra-get-user-design-url}?image-urls=XXX
参数|必有|说明
---|---|---
image-urls|是|每张图的 URL 经过 encodeURIComponent 之后以英文逗号（,）连接的字符串
<a id="sign"></a>
### 参数签名生成方式
#### 筛选并排序
获取所有请求参数，不包括字节类型参数，如文件、字节流，剔除 sign 字段和 signType 字段，剔除值为空的参数，剔除附加参数（data-extra 开头），并按照第一个字符的键值 ASCII 码递增排序（字母升序排序），如果遇到相同字符则按照第二个字符的键值 ASCII 码递增排序，以此类推。
#### 拼接
将排序后的参数与其对应值，组合成“参数=参数值”的格式，并且把这些参数用 & 字符连接起来，然后在字符串末尾拼接上用户私钥（创客贴提供），此时生成的字符串为待签名字符串。
例如下面的请求示例：
假设请求信息如下，用户私钥为 abcdefg
```
REQUEST URL: https://openapi.chuangkit.com/xxx/xxxx
REQUEST METHOD: POST
CONTENT:
a=1
b=20
c=300
```
则待签名字符串为：
```js
a=1&b=20&c=300abcdefg
```
#### 调用签名函数签名
MD5 方式：使用各自语言对应的 MD5 签名函数对待签名字符串进行签名，生成大写 32 位 MD5 签名结果。
上述示例签名结果即为：03564928A5126990E773BE7BB5714B6A
#### 全局状态码含义
|代码值|说明|
|:-----|-----|
|200|成功|
|10001|appId 参数错误|
|10005|sign 参数错误（若一直报错，请按 [初始化参数说明](#init-params) 的提示尝试解决）|
|10006|欠费|
|10007|data-exp 参数错误|
<a id="scenelist"></a>
### 场景对应表
>**场景可能存在增删的情况，请以[创客贴 M 站](https://m.chuangkit.com/)中顶部显示的场景及 URL 中对应的 kindId 参数为准**
kindId|场景宽|场景高|场景说明
---|---|---|---
4|1280px|1184px|微信朋友圈封面
20|900px|500px|微信公众号首图
40|200px|200px|公众号封面小图
41|600px|600px|公众号底部二维码
162|1280px|1920px|公众号竖版配图
166|640px|1008px|手机海报
12|90mm|54mm|名片
132|54mm|90mm|竖版名片
13|420mm|570mm|印刷海报
2|14cm|21cm|贺卡
21|16.5cm|10.2cm|明信片
25|720px|1280px|手机截屏
208|720px|1280px|节日海报
## 常见问题
### Safari 下使用 iframe 方式调起，设计时提示需要登录
原因：使用 iframe 方式加载第三方网页时，新版 Safari 默认禁止第三方 Cookie，导致创客贴无法正常使用
解决方案：使用 SDK 的 `setCookie` 方法（接受一个必选参数：redirectUrl）。该方法将做如下操作：
1. 重定向到创客贴中转页
2. 设置 Cookie
3. 跳转回原页面，并增加 "hasCookie=1" 的 queryString
调用方根据 `hasCookie` 设置标志，下次调用时判断若有标志则无需再调用 `setCookie` 走上述流程
