文档中心 > 店铺动态卡片-开发指引

店铺动态卡片-开发指引

模板实例化

更新时间：2024/08/01 访问次数：32858

背景

 

服务商可以通过研发小程序或小部件模板的方式，为商家提供标准化的应用服务，快速规模化地拓展商家。详细说明请参考 SaaS模板接入指南 文档。

此接入模式下，商家端应用或配置应用必须包含模板实例化过程的功能。

 

一、小程序模板实例化

1. 代码实现

 

实例化小程序与小程序模板本身，最大的差别在于运行期的扩展信息不同，可通过 my.getExtConfigSync 获取。目前 my.getExtConfigSync 已经支持未实例化前，数据从模板代码包内的 ext.json 文件读取（代码路径与 app.json 同层级）；实例化后，数据从服务端接口返回中读取。因此与后续实例化过程相关的模拟数据，服务商可以预先在 ext.json 中模拟。

 

对于业务相关的模拟数据，服务商可以根据 my.getExtConfigSync 返回的自定义环境字段，访问不同环境下的服务端应用，模拟数据在服务端中预先设置好。目前云开发已经支持了测试、预发、线上这几种环境，云应用时服务商自己亦可以实现环境切换。在模拟过程中，服务商需做好后端应用对实例化版本的兼容（实例化小程序存在版本碎片可能）。

 

2. 测试验证

 

实例化相关的接口均会校验商家订购关系，因此在商家应用正式上线且被商家订购前，无法调通相关接口。服务商在研发阶段如需验证模板实例化的结果，可通过「版本管理」-「开发版本」-「实例化测试」功能来验证功能。

 

1）上传模板版本

 

消费者端模板的功能开发完成之后，通过IDE上传版本。上传完成后，在「版本管理」-「开发版本」即可看到此版本，针对此版本可以进行「实例化测试」的操作。

 

image

 

2）实例化测试

 

在实例化测试面板，填写必要的信息字段后，即可创建一个实例化应用。

【商家测试账号】：必须填写一个用于测试的商家身份的淘宝账号（尽量不要使用线上真实店铺的账号），同时此账号需在商家应用详情页「人员管理」中被添加为开发者角色。

【描述】：实例化应用的描述信息。可在手机淘宝端打开该应用的「关于」页查看此处传入的具体值。

【扩展信息】：实例化时传入的扩展字段内容，运行时模板可通过 my.getExtConfigSync 接口获取在此处传入的具体值。

点击「创建实例化」按钮，完成实例化操作。

 

image

 

用手机淘宝扫描实例化应用的预览二维码，即可在手机端体验该实例化应用的真实运行效果。

如果对扩展信息有变更，可重新填入扩展信息，并点击「更新实例化」进行更新，运行效果同上方式进行验证。

 

image

 

注意：

① 通过上述方式创建的实例化应用，仅指定的商家测试账号可以访问，且无法发布上线。

② 正式发布上线的实例化应用，只能当商家订购当前模板后，通过实例化实施流程完成。

 

如需更换商家测试账号进行实例化，可以先「删除」当前的实例化应用，输入新的账号，然后重新「创建实例化」。

 

3. 提审发布

 

提审时，扩展信息通过代码包内置的 ext.json 来定义。另外，服务商不可避免会需要在打开小程序的URL上拼接一些自定义参数，可以在提审页面输入访问页面时的额外自定义参数query、path（填完完成后可以自行预览一下是否正确），便于运营同学审核时打开包含正常数据的页面，而非空页面。

 

image

 

提审后，等待审核结果。若通过审核，则可以将模板正式发布上线。之后，将整个商家应用发布至服务市场。参考 服务上架 文档。

 

4. 实例化实施流程

 

当商家订购了模板之后，需要帮助商家实例化一个归属于商家的小程序应用。此流程通过调用TOP 接口在商家端应用内实现（运行在千牛客户端）。整体实例化的流程如下图所示。

 

image

 

注意：以下实例化接口，系统均会校验商家与SaaS模板的订购关系。建议服务商在商家端应用第一个版本中先mock实例化过程，并将其发布上线，同时SaaS服务上架服务市场。然后，在商家端应用第二个版本中真正实现实例化过程，并自行订购后验证实例化功能是否正常。

 

1） 构建实例化应用

 

对模板进行首次实例化的时候，请调用 taobao.miniapp.template.instantiate 接口。调用成功后，即会生成一个实例化应用预览版，返回该实例化应用的app_id、app_version 等关键字段。

 

注意：此时该应用并未真正上线，仅限调用该接口的商家账号访问，普通消费者并不能访问该应用。

 

2）更新实例化应用

 

对已经实例化的应用进行模板版本更新的时候，请调用 taobao.miniapp.template.updateapp 接口。调用成功后，即会根据指定的模板版本生成一个新的实例化预览版，该实例化应用的app_id保持不变，返回最新的app_version 等关键字段。

 

注意：此时该版本并未真正上线，不会影响线上版本。仅限调用该接口的商家账号访问此预览版本，普通消费者仍访问线上版本。

 

3）检查预览版的实例化应用

 

对首次构建实例化或后续迭代更新实例化产生的预览版地址，商家可以使用手机淘宝客户端打开访问，检查该应用视觉表现、交互形式、业务逻辑等方面是否满足预期。若满足预期，方可进行下一步上线操作。

 

4）上线实例化应用

 

对预览版本检查无误后，需要对预览版本进行上线操作，请调用 taobao.miniapp.template.onlineapp 接口。调用成功后，即会将指定的预览版本发布上线，返回最新的online_url 等关键字段。

 

注意：此时，该实例化应用版本已真正上线。普通消费者均可访问，且访问到此线上版本。

 

5）查询实例化应用版本

 

若需要查询当前模板所有实例化后的应用版本列表，请调用 taobao.miniapp.template.queryapp 接口。调用成功后，返回所有实例化应用的版本信息。

 

6）下线与回滚实例化应用

 

请尽量通过更新实例化应用接口复用已有的实例化应用AppID。如无必要，不要构建新的实例化应用。若需要下线当前实例化应用，请调用 taobao.miniapp.template.offlineapp 接口。若需要回滚当前实例化应用的版本，请调用 taobao.miniapp.template.rollback 接口。

 

二、小部件模板实例化

1. 代码实现

 

实例化小部件与小部件模板的代码无任何差别，小部件实例化核心解决的是建立商家与SaaS小部件模板的归属关系，以便开发者在小部件运行时识别其所属的商家。小部件模板不允许直接装修或运行，必须实例化方可正常工作（已上线的小部件不受影响，但请尽快迁移）。

 

一个商家应用中的单个「小部件模板」只允许实例化一次。实例化后将生成新的实例化小部件appid。

 

2. 测试验证

 

实例化相关的接口均会校验商家订购关系，因此在商家应用正式上线且被商家订购前，无法调通相关接口。服务商在研发阶段如需验证模板实例化的结果，可通过「版本管理」-「开发阶段」-「实例化测试」功能来验证功能。

 

2.2.1 上传模板版本

 

小部件模板的功能开发完成之后，通过IDE上传版本。上传完成后，在「版本管理」-「开发阶段」即可看到此版本，针对此版本可以进行「实例化测试」的操作。

 

image

 

2.2.2 实例化测试

 

在实例化测试面板，填写必要的信息字段后，即可创建一个实例化小部件。

【商家测试账号】：必须填写一个用于测试的商家身份的淘宝账号（尽量不要使用线上真实店铺的账号），同时此账号需在商家应用详情页「人员管理」中被添加为开发者角色。

【描述】：实例化应用的描述信息。可在手机淘宝端打开该应用的「关于」页查看此处传入的具体值。

点击「创建实例化」按钮，完成实例化操作。

 

image

 

用手机淘宝扫描实例化应用的预览二维码，即可在手机端体验该实例化应用的真实运行效果。

注意：

① 通过上述方式创建的实例化小部件，仅指定的商家测试账号可以访问，且无法发布上线。

② 正式发布上线的实例化小部件，只能当商家订购当前模板后，通过实例化实施流程完成。

 

如需更换商家测试账号进行实例化，可以先「删除」当前的实例化应用，输入新的账号，然后重新「创建实例化」。

 

3. 提审发布

 

提审时，为了便于平台运营人员审核小部件的样式与功能，请上传真实运行时截图。

 

image

 

提审后，等待审核结果。若通过审核，则可以将小部件模板正式发布上线。之后，将整个商家应用发布至服务市场。参考 服务上架 文档。

 

4. 实例化实施流程

 

当商家订购了小部件模板之后，需要帮助商家实例化一个归属于商家的小部件。此流程通过调用TOP 接口在商家端应用（运行在千牛客户端）或配置应用（运行在旺铺装修后台）内实现。整体实例化的流程如下图所示：

 

image

 

注意：

① 以下实例化接口，系统均会校验商家与SaaS模板的订购关系。建议服务商在商家端应用或配置应用第一个版本中先mock实例化过程，并将其发布上线，同时SaaS服务上架服务市场。然后，在商家端应用或配置应用的第二个版本中真正实现实例化过程，并自行订购后验证实例化功能是否正常。

② 由于线上运行的实例化小部件版本受商家页面装修影响，因此线上的实例化小部件版本不支持下线，商家可以通过重新编辑小部件的透出入口来“废弃”历史版本。

 

2.4.1 构建实例化小部件

 

对小部件模板进行首次实例化的时候，请调用 taobao.miniapp.widget.template.instantiate 接口。调用成功后，即会生成一个实例化小部件，返回该实例化小部件的app_id、app_version 等关键字段。

 

注意：此时该实例化小部件已上线，所有消费者均可访问该小部件。

 

2.4.2 更新实例化小部件

 

对已经实例化的小部件进行模板版本更新的时候，请调用 taobao.miniapp.widget.template.instance.update 接口。调用成功后，即会根据指定的模板版本生成一个新的实例化小部件，该实例化小部件的app_id保持不变，返回最新的app_version 等关键字段。

 

注意：此时该版本已上线，直接覆盖线上版本。所有消费者均访问此线上版本。

 

2.4.3 查询实例化小部件版本

 

若需要查询当前小部件模板所有实例化后的小部件版本列表，请调用taobao.miniapp.widget.template.instance.query 接口。调用成功后，返回所有实例化小部件的版本信息。

 

5. 存量SaaS小部件项目

 

由于平台前期未提供小部件模板的应用类型，因此SaaS小部件的项目无实例化概念，这一类存量项目线上运行暂不受影响。但未来新增的SaaS小部件项目请务必按照上述文档，以小部件模板进行开发和实施。

 

 

FAQ

关于此文档暂时还没有FAQ
有用(0) 我要提问
返回
顶部
阿里巴巴集团 | 淘宝网 | 天猫 | 聚划算 | 全球速卖通 | 阿里巴巴国际交易市场 | 1688 | 阿里妈妈 | 阿里旅行·去啊 | 阿里云计算 | YunOS | 阿里通信 | 万网 | 高德 | 优视 | 友盟 | 酷盘 | 虾米 | 天天动听 | 来往 | 钉钉 | 11Main | 支付宝
关于淘宝 合作伙伴 营销中心 联系客服 开放平台 诚征英才 联系我们 网站地图 法律声明 © 2016 Taobao.com 版权所有
网络文化经营许可证：文网文[2010]040号 | 增值电信业务经营许可证：浙B2-20080224-1 | 信息网络传播视听节目许可证：1109364号