营销扩展使用指南

我的收藏

为了更好地帮助开发者对模板进行自定义，开放平台设计了一套模板扩展能力，通过这些能力，小程序开发者可以对模板页面或组件进行定制化修改。

开发者如果接入积分类型营销，需要对提单页（orderConfirm）进行拓展。

注意
插件扩展使用代码示例（接入积分类型营销必读）。

使用限制

•

需要在代码中配置行业 SDK 的权限，基础库 2.74.0.0 及以上版本和抖音 23.0.0 及以上版本支持该权限配置。

•

如果需要接入积分类型的营销，则需要配置前端扩展点。如果是第一次接触前端扩展点，可查阅插件扩展能力了解此能力。

注意
如果不接入前端扩展点，服务端也不能返回积分类型营销。

第一步：在小程序中引入插件

修改小程序全局配置文件 package.json，引入交易插件 microapp-trade-plugin 和扩展能力插件 microapp-ability-plugin。

{ 
  "ttPlugins": {
    "dependencies": {
      "microapp-trade-plugin": {
        "version": "0.0.1", 
        "isDynamic": true 
      },
      "microapp-ability-plugin": {
        "version": "0.0.1", 
        "isDynamic": true 
      }
    }
  }
}

第二步：创建插件扩展页面

与普通页面类似，一个扩展页面由 json、 ttml、ttss、js 4 个文件组成。

首先创建扩展页面，在 app.json 的 pages 字段下添加创建的页面路径。

例如：扩展的路径为 pages/my-confirm/index （以下步骤会使用此页面路径作为示范），在 pages 字段下添加该路径。

{ 
  "pages":[
    "pages/my-confirm/index" // 定义扩展的页面路径
  ],
}

然后指定使用的插件页面，在 my-confirm/index.json 文件中配置 extends 字段，表示对指定模板进行定制。

{ 
  "extends": "ext://microapp-trade-plugin/order-confirm"
}

pay-button 组件通过 bind:getextensionpath 方法传入扩展后的路径。

bind:getextensionpath 需要返回 Promise，开发者将扩展后路径作为返回值传入 resolve 函数。

getExtionPath() { 
  return new Promise(resolve => {
      resolve({ 
        orderConfirm: {
          path: 'pages/my-confirm/index', 
          query: { 
            a: 'xxx', 
            b: 'xxx',
          } 
        } 
      });
    });
}

返回路径信息说明如下：

字段名	类型	默认值	必传	说明
orderConfirm	object 详见 ExtensionPath 参数说明	无	是	接入积分营销需要对提单页进行拓展，对应拓展页面。

ExtensionPath：

字段名	类型	默认值	必传	说明
path	string	无	是	拓展后页面路径。
query	object	无	否	query 参数可以在拓展后页面的 js 文件中（本文第四步：使用插件扩展数据与方法）通过 this.template.queryParams 获取。

此时，已完成插件扩展页面的准备工作。

第三步：开发扩展页面视图

ttml 中需使用 slot 属性将节点插入到模板的不同 slot 上，并在 ttml 中编写扩展节点，同时在 ttss 中加入扩展样式。

注意
接入积分营销时 slot 的值必须是 scores，否则不会生效。

代码示例：

•

插件扩展页面的my-confirm/index.ttml：

<view slot="scores">
  <view class="title">输入选择的积分值, 目前剩余{{scoreInfo.value}}：</view>
  <input value="{{value}}" type="number" bindinput="handleInputs"/>
  <button size="mini" bindtap="confirmHandler">确认积分</button>
  <button size="mini" bindtap="cancelHandler">取消选中</button>
</view>

•

插件扩展页面的my-confirm/index.ttss：

.title { 
  color: red;
}

第四步：使用插件扩展数据与方法

在 js 文件中，通过 Extension 构造器来注册扩展，并提供扩展的属性定义、内部数据和自定义方法，开发者可以通过 this.template 访问到模板提供的数据和方法，数据最早能在 created 生命周期中取到。

此拓展页面可获取到的属性和方法：

属性名	类型	说明	使用方法
scoreInfo	object	开发者服务端返回的可用积分数据，可通过此字段获取	this.template.scoreInfo
queryParams	object	开发者通过 bind:getextensionpath 传入的 query 参数，可通过此字段获取	this.template.queryParams
setSelectedScore	function 入参说明详见setSelectedScore 入参说明	开发者通过此方法传入用户选择的积分值和积分 id	this.template.setSelectedScore()
cancelSelectedScore	function	开发者通过此方法取消已选中积分	this.template.cancelSelectedScore()
closeScorePopUp	function	开发者通过此方法隐藏积分选择弹窗，建议配合 setSelectedScore 和 cancelSelectedScore 使用	this.template.closeScorePopUp()

setSelectedScore 参数说明：

属性名	类型	必填	说明
id	string	是	需使用 scoreInfo 中的 id，传递错误 id 将阻塞后续流程
value	number	是	用户选择的积分值不能小于 0

代码示例：

const { Extension } = require('ext://microapp-ability-plugin/index');
 
Extension({
  data: {
    value: '',
  },
  observers: {
    template: {
      // this.template.scoreInfo 变化时，执行这个函数
      scoreInfo(value) {
        // do something
      },
      queryParams(value) {
        // do something
      },
    },
  },
  attached() {
    // 获取模板页面暴露的营销数据
    console.log(this.template.scoreInfo);
  },
  methods: {
    handleInputs(e) {
      this.setData({ value: e.detail.value });
    },

    confirmHandler() {
      const { id, value } = this.template.scoreInfo;
      if (this.data.value > value) {
        return;
      }
      this.setSelectedScore({ id, value: Number(this.data.value) }); // 选择积分
      this.template.closeScorePopUp(); // 关闭弹窗
    },
    cancelHandler() {
      this.template.cancelSelectedScore(); // 取消选中
      this.template.closeScorePopUp(); // 关闭弹窗
    },

    setSelectedScore(selectedScore) {
      this.template.setSelectedScore(selectedScore);
    },
  },
});

其中 microapp-ability-plugin 插件导出 Extension 构造器，使用时需通过 require 引入该构造器。