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

店铺动态卡片-开发指引

小部件开发流程

更新时间：2023/07/06 访问次数：24483

一、创建应用


小部件是属于商家应用中的一种全新开放形式，因此创建小部件前需要先创建应用，可参考创建应用文档 。


二、创建小部件


如果当前的商家应用类目支持小部件，那么会透出创建小部件的入口，如下所示。


1.点击「创建小部件」


image


2.填写小部件相关信息


填入小部件基本信息，包含名称、描述，选择小部件欲将投放的N个位置以及卡片尺寸（同一个投放位置只能选择一个卡片尺寸），最后选择已经上线的消费者端应用或模板与之关联（是否必须，由所选的投放场景而定，请根据实际情况选择），即可成功创建小部件。


image


注意：如遇“名称不合法”或“描述不合法”情况，请检查相关输入的文案，不允许输入不符合国家政策法规的文字。


3.信息修改


1）上述信息如需修改，可以先选中新创建的小部件；


image


2）然后再选中「基本信息」菜单进行修改。


image


注意：

①小部件上线后，关联的端应用无法修改。

②小部件上线后，位置与尺寸只可增加不可减少。


三、编写代码


在淘宝开发者工具 IDE 1.1.0以上版本中，点击「创建项目」-> 输入项目路径 -> 项目类型选择「小部件」-> 选择后端服务 -> 选择关联应用，创建小部件项目工程。如果是SaaS化的小部件项目，请选择「小部件模板」。


image


然后参考小部件的API与组件等相关文档，进行具体的代码编写。所有小部件项目的业务代码务必在「widget」目录下进行编码。如有外部npm包依赖，也务必安装到「widget」目录下。「client」目录仅做预览宿主使用，正式构建上传不会包含其中的代码逻辑。


同时，可以在模拟器里预览效果，也可以通过最新版手机淘宝App进行扫码预览。


image


注意，小部件的代码实现过程中需要了解以下几点：

1.小部件跳转小程序：在小部件创建的过程中已经确定了与其绑定的小程序（或模板），因此在小部件内仅可跳转至绑定的小程序（或模板实例化小程序），不可跳转至其他小程序。换句话说，小部件不支持my.navigateToMiniProgram ，仅支持my.navigateToRelationMiniProgram，可在调用过程中可填入必要的参数透传至小程序。由于各个小部件接入场景可能在框架层面具备拉起关联的小程序入口，为了保障这些框架入口拉起小程序时携带了正确的参数，请在合适的时机调用 my.updateNavigateParams 来更新相关小程序唤起时的参数。

2.小部件运行时后端数据查询：小部件可以与模板小程序绑定，但是小部件不存在“实例化”的概念。因此，在实际运行阶段，存在一个小部件与多个模板实例化小程序关联的情况。显然，这种情况下，小部件需要根据关联的实例化小程序来展示不同的数据与内容。为此，我们提供了my.getRelationAppInfo 接口，可通过该接口获取运行期与其实际关联的小程序appId，传给云服务来获取相对应的数据。这部分逻辑需要服务商自己实现。

3.小部件降级：由于小部件可投放至多个重要的私域场景，因此出于消费者用户体验的考虑，当小部件运行时发生了一些错误时，服务商需要通过 my.widgetDowngrade 接口来告知平台。此时，平台可在透出场景中做实时屏蔽，以免产生消费者舆情。


注意：小部件暂不支持真机调试，真机预览效果与IDE中模拟器预览效果存在差异，真实效果请以真机扫码预览为准。开发同学正在努力支持中。


四、上传代码


与小程序一样，通过IDE右上角的「上传」按钮，将小部件的代码上传至控制台。


五、提审与发布


代码上传后，可以控制台的小部件「版本管理」菜单中看到此版本。开发者可以点击【提交审核】对此版本进行提审。耐心等待审核通过后，可以点击【发布】对此版本进行发布上线。基本流程与小程序几乎一致。


image


六、实例化实施


小部件上线（或与相对应的小程序服务一起）发布至服务市场，商家即可订购该服务来使用小部件。如果是SaaS化小部件模板，需要ISV调用 小部件模板实例化 相关接口来帮助商家完成小部件模板实例化操作，否则在商家创建投放计划时，无法选中该小部件进行前台场景的投放。


1.若商家在ISV提供的商家端应用内完成小部件的一些必要配置操作，ISV需在商家端应用交互过程中的合理时机调用上述实例化接口。

2,若商家在ISV提供的「配置应用」内完成小部件的一些必要配置操作，ISV需在配置应用schema.json的initial指定的函数或应用路径下调用上述实例化接口。


小部件实例化代码参考


exports.main = async function(context) {
    //模版id    
    const templateAppId = context.miniappId ? context.miniappId : context.data.miniappId;
    //模版版本     
    const templateAppVersion = context.appVersion ? context.appVersion : context.data.appVersion;     
    //该商家已实例化的小部件id     
    const instanceWidgetId = context.instanceWidgetId ? context.instanceWidgetId : context.data.instanceWidgetId;     
    //商家授权的token     
    const authToken = context.authToken ? context.authToken : context.data.authToken + "";     
    //小部件描述     
    const description = "小部件实例化可进行整体实例化流程";     
    let result = null,success = true; 
    //已实例化过的，走实例化更新流程     
    if(instanceWidgetId){                 
                const updateFunction = await context.cloud.topApi.invoke({                     
                    api : 'taobao.miniapp.widget.template.instance.update',                     
                    data : {
                        param_mini_app_instantiate_template_app_update_request: {                             
                            entity_id: instanceWidgetId,                             
                            template_id: templateAppId,                             
                            template_version: templateAppVersion                         
                         },                        
                        session: authToken                     
                     },                    
                }).then(async res => { 
                    let updateResult = res.result;                     
                    if (updateResult.success) {   
                        //自身的业务逻辑，按照需求实现                         
                        result = '小部件实例化模板'+templateAppId+'版本'+templateAppVersion+'更新实例成功，描述：'+description;   
                     } else {                         
                         success = false;       
                         result = {           
                             error_message: updateResult.err_message, 
                             error_code: updateResult.err_code   
                         }                   
                    }                 
                 });            
         }             
         else {                 
             //未实例化的，走实例化流程   
             const instanceFunction = await context.cloud.topApi.invoke({
                 api : 'taobao.miniapp.widget.template.instantiate',     
                 data : {          
                     param_mini_app_instantiate_template_app_simple_request: {      
                         description: description, 
                         template_id: templateAppId, 
                         template_version: templateAppVersion   
                      },                         
                      session: authToken,        
                  },                
             }).then(async res => {       
                  let instanceResult = res.result;  
                  if (instanceResult.success) { 
                       //自身的业务逻辑，按照需求实现 
                       result = '小部件实例化模板'+templateAppId+'版本'+templateAppVersion+'创建实例成功，描述：'+description;    
                  } else {    
                      success = false;     
                      result = {            
                          error_message: instanceResult.err_message,  
                          error_code: instanceResult.err_code        
                      }             
                  }           
                });       
            }   
    return {         
      success: success,       
      result: result    
    };
}


FAQ

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