一、流程概述

二、账号准备

准备企业法人的淘宝企业账号与支付宝企业账号。

① 淘宝企业账号用于登陆淘宝互动开放平台，可以以法人的身份重新注册一个淘宝企业账号。

② 支付宝企业账号用于对您的身份进行实名认证，从而获得企业开发者身份。

③ 支付宝企业账号申请请参照文档支付宝企业账号注册及实名认证 。与淘宝企业账号相同，可以用企业法人的身份与手机号注册一个新的支付宝账号（手机号可以相同，账号邮箱需要更换），完成支付宝企业账号申请。

三、开发者入驻

1. 登录控制台

用上述淘宝账号登录：开发者控制台。

2. 开发者控制台入驻

进入官网入驻地址：https://work.open.taobao.com/open-console-enter

点击企业身份入驻。

入驻【小游戏开发者】身份。

根据流程指引，依次填写信息：

备注：其中“实人认证和资金管理服务开通”入驻时可选择跳过，后面有需要时候仍会引导您进行认证和开通。

紧急可联系【婉清】进行审批。

入驻审核通过后，即可开始应用创建。

四、应用创建

进入控制台，登录企业淘宝账号。进入创建应用。

选择【游戏互动创意】类型应用。

选择为哪个业务进行开发。

点击开始创建，选择对应类目。

确认类目后【进入开发】。

创建应用。

确认提交，此时建立的是应用方案，并未生成小游戏。

此时创建成功后，会生成了服务端appKey。

创建小游戏应用：

创建完成后即可获得到消费者侧的小游戏appId。

五、开发者权限配置

人员管理中增加引擎插件的开发者人员，加入淘宝昵称即可。--目前不支持子账号进行开发。

六、服务端&前端-确认开放数据

请确认即将开发的小程序方案，需要使用到的开放API以及数据有哪些，确认好开放数据后，则申请这些数据API对应的权限包（一组API的集合）。

权限包&申请流程：https://open.taobao.com/v2/doc#/abilityToOpen?docType=1&docId=121030&treeId=805

七、服务端开发看

1. 云服务开通&部署

1）空应用【使用外部云服务时必须对接】

空应用，用于通过云网关调用小游戏部署在外部的云应用，网关会自动带上一些开放相关的上下文参数信息，因此对于使用外部云服务的情况下，必须对接。并且所有的服务端请求对应的域名，需要配置到空应用的域名白名单，并且使用cloud.application.httpRequest api进行调用。详细示例代码请参考下面的示例。

① 新建空应用

按照流程申请空应用，获取空应用的cloudAppId。

② 添加外部域名

添加外部服务器域名，添加了此处的域名，前端才可以通过cloud.application.httpRequest调用该外部域名。

?

等待平台审核完成即可，审核通过后即可进行空应用的调试。

③ 空应用域名续期

游戏owner进入开发者控制台-->左侧云托管菜单-->云应用管理--->选择对应空应用 点击续期

④ 前端调用外部服务端的示例

//game.js文件初始化示例代码
import cloud from '@tbmp/mp-cloud-sdk';

cloud.init({
  //test、online
  env: 'test'
});

----------------------------------
  //调用接口的方法
  async function testCloud() {
    let result
    try {
      result = await cloud.application.httpRequest({
        //不需要完整域名，只需要接口访问路径即可
        'path': '/welcome',
        'method': 'GET',
        'headers': {},
        'params': {"name":"hanruo","action":"test"},
        'body': {},
        //cloudAppId 空应用的Id
        'exts': { 
          "cloudAppId": "xxxx",
          "timeout": 4000,
           //空应用调用需要填写该字段，包括协议头以及端口号（可省略），支持http、https
           "domain":"https://www.taobao.com"
        }
      });
    } catch (error) {
      console.log(error)
    }
    console.log("result:", JSON.stringify(result));
  }

----------------------------------
  //执行方法
  testCloud();



==================================
  //如果需要用户授权，服务端获取对应token，则如下调用：
  //执行方法
  my.authorize({
    scopes: 'scope.userInfo', //需要授权的权限包，此处以用户信息权限包为例
    success: (res) => {
      console.log("res:", res);
      testCloud();
    },
    fail(res) {
      console.log("fail:", res);
    }
  });

2. 服务端处理前端请求

前端通过cloud.application.httpRequest调用服务端。服务端接收到请求后，可获取除自定义参数外的系统参数。具体参数：空应用调用文档。

注意：用户自定义的参数不能和系统参数同名，否则会被覆盖掉。

示例：

服务端获取到的参数：

JAVA为例：

request.getParameterMap()

获取参数如下：

{
    "access_token":[
        "50000800a35OYySsAHauUie7oudnphrweajdphmVUgolwL318fcaedeiwtFKxxxxx"//用户授权 sessionKey
    ],
    "source_app_id":[
        "3000000083xxxx"
    ],
    "app_key":[
        "3427xxxx"
    ],
    "mix_nick":[
        "专01iX1c6xL0GdYGnCEZeOviGFE6pjWHaaOS6xxxxx"//混淆用户昵称
    ],
    "open_id":[
        "AAFDUQQSAOIKi_Utxxxxxxx"  //当前登录用户的openId
    ],
    "mini_app_id":[
        "3000000083xxxx"
    ],
    "sign":[
        "D40C31902FED8D55A181C53xxxxxx"//除sign字段外的所有参数的加签信息，可参考文件验签：https://open.taobao.com/v2/doc#/abilityToOpen?treeId=780&docType=1&docId=118394
    ],
    "env":[
        "test" //当前空应用的调用环境，入参为：test或者online，对应在云开发中绑定的云容器的测试环境和正式环境。在发布上线前注意调整env为online，调用正式环境。
    ],
    "app_owner_open_id":[
        "AAFDUQQSAOIKi_UtQxxxxx"
    ],
    "request_id":[
        "213e21d716787092743006675e1d16"
    ],
    "source_ip":[
        "42.120.74.xxx"
    ],
    "name":[
        "hanruo"//业务自定义参数
    ],
    "action":[//业务自定义参数
        "test"
    ],
}

3. 资源/websocket域名白名单

如果使用了空应用，则已经支持直接访问外部的服务器http接口。

但如果需要访问【外部资源域名或websocket】需要额外申请域名白名单。

目前平台可通过以下路径申请域名白名单：

其中Request类已不建议接入，其他具体该申请哪类，需要游戏前端同学参考下面具体使用的哪些API，然后服务端或前端同学将使用的api对应的访问域名地址申请域名白名单。

https://miniapp.open.taobao.com/doc.htm?docId=120157&docType=1&tag=dev

申请审核流程：联系对应业务对接人去内部后台查询。

4. 服务端调用开放API示例

调用开放api：通用文档介绍。

部分开放能力以topAPI形式开放，需要先申请API对应的权限包。在小游戏下，一般建议前端调用top api，此方法在涉及用户授权时，网关层会自动判断是否有有效授权token并判断是否弹窗。开发者无需感知。

//前端调用示例
async testTopApi(){
  try {
    const result = await cloud.topApi.invoke({  
      api: 'taobao.miniapp.userInfo.get',  //调用的api名称
      data : {
        'xx':"21313",
        'xxx':'tid,type,status'
      },//参数
      authScope: 'scope.userInfo'  //api所在的权限包
    });
    my.alert({
      content: 'success ' + JSON.stringify(result)  
    });
  } catch (e) {
    my.alert({  content: 'error ' + e.message  })
  }  
}

某些特殊情况下，可能使用服务端调用需要用户授权的TOP api。操作流程：申请对应权限包后，下载上述最新SDK，然后编写服务端代码，示例如下：

HttpServletRequest request;// 接受到的请求入参

TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret);
OpenTradesSoldGetRequest req = new OpenTradesSoldGetRequest();
req.setFields("tid,type,status,payment,orders,rx_audit_status,buyer_nick");
req.setStartCreated(StringUtils.parseDateTime("2021-03-01 00:00:00"));
req.setEndCreated(StringUtils.parseDateTime("2021-03-31 23:59:59"));
req.setStatus("ALL_WAIT_PAY");
req.setType("game_equipment");
req.setPageNo(1L);
req.setPageSize(40L);
req.setUseHasNext(true);
req.setBuyerOpenId(request.getParameter("open_id"));
/**
* 注意，此时云网关上下文中获取的sessionkey：对应的是当前发起请求的C端登录用户的sessionkey。
*/
String sessionKey = request.getParameter("access_token");

OpenTradesSoldGetResponse rsp = client.execute(req, sessionKey);

5. 服务端实现官方奇门SPI

1）业务方先授权需要实现的奇门SPI，开发者不用感知。

2）进入开发者控制查看需要实现的SPI：

注意此处必须要申请权限的appkey的拥有者才能看到已授权的场景。

3）下载上述SDK。

4）实现对应接口。

根据api文档定义返回结构，并提供接口地址。

奇门需要域名并配置云SLB。

八、前端开发看

1. 在游戏引擎开发并导出小游戏

1）在 Cocos Creator 开发并导出淘宝小游戏

cocos3.x在3.7.3及后续版本支持淘宝小游戏，下载使用地址：https://docs.cocos.com/creator/manual/zh/editor/publish/publish-taobao-mini-game.html

cocos2.x在2.4.12后支持淘宝小游戏，使用地址：https://docs.cocos.com/creator/2.4/manual/zh/publish/publish-taobao-mini-game.html

?

Cocos Creator 新手上路：https://docs.cocos.com/creator/manual/zh/getting-started/

（选择 项目-》构建发布-》淘宝小游戏）

导出淘宝小游戏流程:

2）在 LayaAir 开发并导出淘宝小游戏

LayaAir3.x在3.1.1及后续版本支持淘宝小游戏，下载使用地址：https://layaair.layabox.com/#/engineDownload

LayaAir2.x在2.13.4及后续版本支持淘宝小游戏，下载使用地址：https://ldc2.layabox.com/layadownload/?type=layaairide-LayaAir%20IDE%202.13.4

?

LayaAir官网：https://layaair.layabox.com/#/

?

导出淘宝小游戏流程：选择 文件 -> 构建发布 -> 选择“淘宝小游戏” -> 构建淘宝小游戏。

?

导出淘宝小游戏流程：

?

2. 淘宝 小游戏IDE 下载

在淘宝开发者工具下载最新版本IDE，下载地址：https://developer.taobao.com/

?

——注意若引擎为laya请选用3.0.4版本进行开发。

3. 在淘宝 IDE 中导入小游戏工程

① 导入项目前，需要先切换为 ---->【小游戏-新】选项卡。如果看不到选项，可通过【小游戏】--打开项目--项目类型选择时再选择 【小游戏-新】按钮；

② 点击右上角的“打开项目”，然后选择从 游戏引擎 中导出好的工程文件夹并打开；

③ 将项目类型更改为 ----> 【小游戏-新】类型；

④ 在【关联应用】处，关联至自己在控制台创建好的小游戏应用；

⑤ 点击【确定】按钮。

4. game.json 配置

{
  "deviceOrientation": "landscape", //横屏配置
  "window":{
    "defaultTitle": "接口功能演示"
  },
  "subpackages": [
    {
      "name": "subPackageA",
      "root": "stage1/" // 可以指定一个目录，目录根目录下的 game.js 会作为入口文件，目录下所有资源将会统一打包
    }, {
      "name": "subPackageB",
      "root": "stage2.js" // 也可以指定一个 JS 文件
    }
  ]
}

1）横屏配置

https://open.taobao.com/doc.htm?docId=120992&docType=1

2）window 配置

{
 	"window":{
	 	"defaultTitle": "接口功能演示"
 	}
}

属性	类型	是否必填	描述
defaultTitle	String	否	页面title标题，需在非首页使用。必须在navigationBarForceEnable设置开启才能展示。使用了tabbar的非首个tab不需要开navigationBarForceEnable也能展示。
transparentTitle	String	否	导航栏透明设置。默认 none，支持 always 一直透明 / auto 滑动自适应 / none 不透明
navigationBarBackgroundBg	String	否	导航栏背景图片地址
navigationBarTextStyle	String	否	导航栏标题颜色，仅支持black/white
titleImage	String	否	导航栏图片地址
titleBarColor	HexColor	否	导航栏背景色
showNavigationBarLogo	Boolean	否	是否显示首页导航栏上的AppLogo ，默认不显示。

3）分包配置

① 代码分包

包含JS的文件夹只能设置为代码分包。

在 cocos或laya 等游戏引擎上设置bundlle的压缩类型为【淘宝小游戏分包】。游戏引擎构建导出后可自动在game.json中设置分包信息。

导出后game.json中包含以下配置。

{
  "subpackages": [
    {
      "name": "subPackageA",
      "root": "stage1/" // 可以指定一个目录，目录根目录下的 game.js 会作为入口文件，目录下所有资源将会统一打包
    }, {
      "name": "subPackageB",
      "root": "stage2.js" // 也可以指定一个 JS 文件
    }
  ]
}

② 资源分包

纯资源素材的文件夹可设置为资源分包，并提供存储素材文件的CDN域名地址，可降低包大小，提升首屏启动速度。注意：设置远程分包后，导出的淘宝小游戏里面的remote文件需要删除。

3）分包配置

调用加载分包，示例代码如下：

my.loadSubPackage({
   name: 'packageA', 
   success:  (res) => {
     this.setData({
       subpackageReady:true
     })
     console.log("download success")
   },
   fail: function (res) {
     console.log(res)
     console.log("download fail")
   }
  })

4）引擎插件配置

为了降低游戏主包大小，提升消费侧启动速度，可以在导出淘宝小游戏代码包的时候，游戏引擎导出时选择分离引擎插件。

5. 调用服务端

项目根目录下新建package.json，写入：

{
  "name": "",
  "version": "1.0.0",
  "main": "",
  "license": "MIT",
  "dependencies": {
    // 版本号必须大于1.5.5，可以直接写 "*" ，表示依赖最新版本，每次小程序打包会字段更新到最新版本
    "@tbmp/mp-cloud-sdk": "1.5.5"  
  }
}

或是在 IDE终端执行 npm install @tbmp/mp-cloud-sdk --save

引用成功后的项目结构

js代码中初始化cloud并调用

//game.js文件初始化示例代码
import cloud from '@tbmp/mp-cloud-sdk';

cloud.init({
  //test、online
  env: 'test'
});

----------------------------------
  //调用接口的方法
  async function testCloud() {
    let result
    try {
      result = await cloud.application.httpRequest({
        //不需要完整域名，只需要接口访问路径即可
        'path': '/welcome',
        'method': 'GET',
        'headers': {},
        'params': {"name":"hanruo","action":"test"},
        'body': {},
        //cloudAppId 空应用的Id
        'exts': { 
          "cloudAppId": "xxxx",
          "timeout": 4000,
           //空应用调用需要填写该字段，包括协议头以及端口号（可省略），支持http、https
           "domain":"https://www.taobao.com"
        }
      });
    } catch (error) {
      console.log(error)
    }
    console.log("result:", JSON.stringify(result));
  }

----------------------------------
  //执行方法
  testCloud();



==================================
  //如果需要用户授权，服务端获取对应token，则如下调用：
  //执行方法
  my.authorize({
    scopes: 'scope.userInfo', //需要授权的权限包，此处以用户信息权限包为例
    success: (res) => {
      console.log("res:", res);
      testCloud();
    },
    fail(res) {
      console.log("fail:", res);
    }
  });

服务端调用文档：https://open.taobao.com/v2/doc?spm=a219a.15212433.0.0.7530669ahPwd3j#/abilityToOpen?docType=1&docId=118538&treeId=776

6. 真机扫码预览

1）点击 IDE 上方工具栏中的“预览”按钮，待编译完成后，会生成【真机预览二维码】；

2）用淘宝 APP 扫描该二维码，即可在手机上预览小游戏的真实运行效果。

7. 真机断点调试

1）点击 IDE 上方工具栏中的“调试”按钮，待编译完成后，会生成【调试二维码】；

2）用淘宝 APP 扫描该二维码，即可在手机上运行并调试小游戏代码，在 IDE 调试面板中可查看日志和断点；

3）需要被注意的是，【调试二维码】只能被使用一次（多次扫码将无效），每次扫码后若要再次使用，需要重新生成调试码。

8. 基础性能调试

1）调试工具地址：

https://market.m.taobao.com/app/polygon/web-devtool-page-html/index.html#/

2）使用方式：

在IDE内点击生成预览码或调试码：

将生成出来的二维码地址复制到输入框中，并点击生成二维码即可进行性能数据采集调试：

9. 容器 API 能力

小游戏API总览

https://open.taobao.com/v2/doc?spm=a219a.15212433.0.0.7530669ahPwd3j#/abilityToOpen?docType=1&docId=121112&treeId=805

10. 提审&发布

① 上传

本地验证完成后，可点击上传按钮进行版本上传。

上传完成后，可在控制台看到对应的版本信息。https://work.open.taobao.com/workspace-home

② 隐私设置

如果弹窗，前往设置即可。

先填写各项能力使用说明后，修改隐私政策文件。

填写基础信息后，生成隐私政策即可。

③ 提审

进入游戏的版本管理。

提审。

提审后等待平台审核，其中性能审核标准查看：https://www.yuque.com/open-qa/hdnbca/tp9huqqz4dlgcv54

申请审核流程：联系对应业务对接人去内部后台查询。

④ 发布

审核通过后 点击发布按钮。

刷新页面后即可看到版本已发布上线。如下图地方可看到线上版本二维码与链接地址。链接示例：https://m.duanqu.com?_ariver_appid=30000000xxxxxx&_mp_code=tb&_container_type=gm

⑤ 灰度

首次版本发布没有灰度，有线上版本后，再次发布会进入灰度发布，将线上流量部分切到灰度版本。如果版本仅希望部分用户内测，可选择白名单灰度，且百分比设置为0。

刷新页面后即可看到灰度版本。

此时白名单用户需要去线上入口，或扫码线上二维码验证命中灰度。因为是线上分流到灰度版本，所以一定是从线上入口进行访问。访问前可清除本地缓存，避免命中客户端本地缓存的历史旧版本。

点击详情查看灰度数据。

白名单验证没问题后，可直接增加灰度百分比。灰度放量只可增加，不可减少。调整后点击【修改命中概率】。

灰度验证没问题后，可点击发布按钮发布到线上。

灰度有问题，则进入详情页，关闭灰度，退回开发版本，重新再提交新的版本。

九、常用能力介绍&示例

下面是对常用的一些能力的介绍和最佳实践。

1. 用户授权相关链路&使用

以获取获取用户头像信息为例：

1）开发者控制台查看对应的权限包。

2）查看具体的接口使用说明

3）前端代码中引用

my.authorize({
  scopes: 'scope.userInfo',
  success: (res) => {
    my.getAuthUserInfo({
      success: (userInfo) => {
        console.log("userInfo:", userInfo);
      }
    });
  },
  fail(res) {
      console.log("res:", res);
    }
});

成功打印结果：

{
  avatar: 'https://wwc.alicdn.com/avatar/getAvatar.do?userIdStr=Xm8WM8kyX88WvGvGXmI4PGkLvmvyMCguMChhMm-hXHxT&width=80&height=80&type=sns',
  mixNick: '测01Cr+BAwLPl0OuaQefiGfddddxxxxWfgsSUZFFGdMo=', 
  nick: '测试xxx'
}

授权内部校验流程：

调用my.authorize后，容器内部会完成授权的校验与回调处理。

token过期会重新弹窗授权。

如果用户拒绝，由于疲劳度控制，不会再次弹窗。但如果游戏又必须要调用授权接口，游戏内可引导用户主动授权，调用my.openSetting，主动打开授权管理页面。具体操作流程参考：https://open.taobao.com/v2/doc#/abilityToOpen?docType=1&docId=120286&treeId=806

2. TOP API使用说明

调用来源	API类型	TOP API
C端小程序内发起调用	需要消费者授权的API	?
服务端发起调用	无需用户授权的API	?
	需要消费者授权的API（目前不建议使用）	?

1）前端调用TOP API

如果调用的api，需要用户授权，那么需要在发起调用前，调用my.authorize.

const {cloud} = getApp();
Page({
  data:{},
  onLoad(query) {
  // 页面加载  
  },  
  async testTopApi(){
    try {
      const result = await cloud.topApi.invoke({  
        api: 'taobao.miniapp.userInfo.get',  
        authScope: 'scope.userInfo'  
      });
      my.alert({
        content: 'success ' + JSON.stringify(result)  
      });  
    } catch (e) {
        my.alert({  content: 'error ' + e.message  })
    }  
  } 
});

2）服务端调用TOP API

外部服务器里发起top请求，JAVA示例如下。

TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret);
OpenTradesSoldGetRequest req = new OpenTradesSoldGetRequest();
req.setFields("tid,type,status,payment,orders,rx_audit_status,buyer_nick");
req.setStartCreated(StringUtils.parseDateTime("2021-03-01 00:00:00"));
req.setEndCreated(StringUtils.parseDateTime("2021-03-31 23:59:59"));
req.setStatus("ALL_WAIT_PAY");
req.setType("game_equipment");
req.setPageNo(1L);
req.setPageSize(40L);
req.setUseHasNext(true);
req.setBuyerOpenId("AAHm5d-EAAeGwJedwSHpg8bT");
req.setBuyerNick("zhangsan");
// 注意，此处传入的sessionkey为之前商家授权获取的sessionkey，并非此时云网关上下文中获取的sessionkey
// 因为云网关上下文携带的sessionkey为当前调用者的sessionkey。
OpenTradesSoldGetResponse rsp = client.execute(req, sessionKey);
System.out.println(rsp.getBody());

3. 获取用户唯一标识：OpenId

openId是平台基于当前用户账号、当前小游戏信息、当前客户端等多个信息生成的用户唯一标识，开发者可使用openId关联各自的用户帐号体系。不同游戏的openId不同。

获取openId的方式：openId可通过空应用调用的上下文获取。

1）服务端获取openId

JAVA示例：

@RequestMapping(value = "/welcome", method = {RequestMethod.GET, RequestMethod.POST})
@ResponseBody
    public String test(HttpServletRequest request) {
        String openId =request.getParameter("open_id");
		return openId;
	}

2）前端获取openId

上述服务端将openId获取后再手动回塞返回给前端。一般不建议前端获取openId。

async function test() {
  let result
  try {
    result = await cloud.application.httpRequest({
      //不需要完整域名，只需要接口访问路径即可
      'path': '/test',
      'method': 'GET',
      'headers': {},
      'params': {},
      'body':{},
      //cloudAppId填写开启本地调试的空应用ID,否则会调到云端
      'exts': { "cloudAppId": "xxxx", "timeout": 4000 }
    });
  } catch (error) {
    console.log(error)
  }
--------- 执行云请求
test().then(res => {  console.log("openId",res) }

十、FAQ

1.no such file or directory ....build\taobao-minigame \client lapp.json

解法：cocos构建发布的时候，发布平台选择【淘宝小游戏】，或者检查自己是否打开的IDE的【小游戏-新】入口。

2.全局变量undefined

解法：参考文档底部差异部分 https://docs.cocos.com/creator/2.4/manual/zh/publish/publish-taobao-mini-game.html

示例：?

挂载全局变量： import xx的地方： window.xx = xx

使用全局变量： var xx = window.xx 或者cocos导出时设置全局变量。cocos导出面板设置的全局变量只实现了声明使用，上面挂载全局变量需要开发者自己实现。

十一、答疑

提交工单

1）点击控制台右上角“工单”入口。

2）或是从左侧菜单进入工单，选择“小程序开放”-“小游戏”，进行工单提交。

3）选择问题分类，进行工单咨询。