领券组件插件接入流程
完整接口时序图

voucherCode
,进行支付宝侧的商家券发放。接入活动咨询接口
示例代码
package com.java.sdk.demo;
import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayMarketingActivityApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
public class AlipayMarketingActivityApiConsult {
public static void main(String[] args) throws ApiException {
ApiClient defaultClient = Configuration.getDefaultApiClient();
// 初始化alipay参数(全局设置一次)
AlipayConfig alipayConfig = new AlipayConfig();
alipayConfig.setServerUrl("https://openapi.alipay.com");
alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->");
alipayConfig.setPrivateKey("<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->");
alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->");
defaultClient.setAlipayConfig(alipayConfig);
AlipayMarketingActivityApi api = new AlipayMarketingActivityApi();
AlipayMarketingActivityConsultModel data = new AlipayMarketingActivityConsultModel();
data.setMerchantId("2088102111111111");
data.setUserId("2088xxxx");
data.setMerchantAccessMode("SELF_MODE");
List<ConsultActivityInfo> consultActivityInfoList = new ArrayList<ConsultActivityInfo>();
ConsultActivityInfo consultActivityInfoList0 = new ConsultActivityInfo();
consultActivityInfoList0.setActivityId("201623213214325423");
consultActivityInfoList.add(consultActivityInfoList0);
data.setConsultActivityInfoList(consultActivityInfoList);
try {
AlipayMarketingActivityConsultResponseModel response = api.consult(data);
} catch (ApiException e) {
AlipayMarketingActivityConsultDefaultResponse errorObject = (AlipayMarketingActivityConsultDefaultResponse) e.getErrorObject();
System.out.println("调用失败:" + errorObject);
}
}
}
响应示例
{
"code":"unknow-error",
"message":"系统繁忙"
}
接入领券组件插件
第一步:订购插件

第二步:接入插件
插件使用声明
{
"plugins": {
"couponPlugin": {
"version": "*", // 拉取当前上架最新版本
"provider": "2021002172680015" // 领券组件插件 ID,固定值
}
}
}
版本兼容
// app.js
// 需先安装 compare-versions 依赖:npm install compare-versions --save
import compareVersions from 'compare-versions'
const { version } = my.getSystemInfoSync()
if (compareVersions(version, '10.1.85') < 0) {
my.ap && my.ap.updateAlipayClient && my.ap.updateAlipayClient();
}
App({
onLaunch() {},
onShow() {},
})
!my.canIUse('plugin') && !my.isIDE
来判断插件是否可用,但该方法对于 10.1.82 的客户端返回 true
,故需要用直接判断客户端版本号的方式。使用插件组件
plugin://
协议指明需要引用的插件自定义组件。{
"usingComponents": {
"get-coupon": "plugin://couponPlugin/get-coupon"
}
}
// page.axml
<get-coupon
onGetCouponSuccess="onGetCouponSuccess"
onGetCouponFail="onGetCouponFail"
onUseImmediately="onUseImmediately"
onClose="onClose"
params="{ {params} }"
senderMerchantId="{ {senderMerchantId} }"
dialogBtnType="{ {dialogBtnType} }"
dialogBtnStyle="{ {dialogBtnStyle} }"
zIndex="{ {9998} }"
extraData="{ {'Any Data'} }"
>
<!-- 内部为自定义代码,「按钮」代码写在这里 -->
<view class="text-button">领券</view>
</get-coupon>
// page.js
Page({
data: {
params: [
{
activityId: '20220426008260043360152XXXX',
outBizNo: '20220xxxx',// 导码模式商家券
},
{
activityId: '20220426008260043360152XXXX',
outBizNo: '20220xxxx',
},
{
activityId: '20220426008260043360152XXXX',
outBizNo: '20220xxxx',
voucherCode: '2022xxxxxxx',//非导码模式商家券
}
],
senderMerchantId: '2088831680549222',
dialogBtnType: 1,
dialogBtnStyle: {
color: '#000',
borderColor: 'yellowgreen',
backgroundColor: 'yellowgreen',
},
},
onGetCouponSuccess(resultList, { extraData }) {
console.log('触发了 onGetCouponSuccess 事件')
console.log('成功返回结果: ', resultList)
},
onGetCouponFail(result, { extraData }) {
console.log('触发了 onGetCouponFail 事件')
console.log('失败返回结果: ', result)
},
onUseImmediately(event, { extraData }) {
console.log('触发了 onUseImmediately 事件')
// 可以跳转到自定义的页面
my.navigateTo({
url: '/pages/goods-detail/index',
})
},
onClose(event, { extraData }) {
console.log('触发了 onClose 事件')
},
});
插件参数说明
名称 | 类型 | 是否必填 | 描述 |
---|---|---|---|
onGetCouponSuccess | string | 否 | 领券请求 成功调用的事件,领券结果可能成功也可能失败。 |
onGetCouponFail | string | 否 | 领券请求 失败调用的事件,如网络错误、接口超时、用户未登录、接口报错等。 |
onUseImmediately | string | 否 | 点击 立即使用 按钮触发的事件,前提是设置了 dialogBtnType 值为 2。 |
onClose | string | 否 | 弹窗关闭事件。 |
params | array | 是 | 发券参数,一次最多 10 张。 示例值: 发一张券 JSON:[{ "activityId": "20220426008260043360152XXXX","outBizNo": "12xxxqccc1qxxc1"}]发多张券 JSON(支持同时发放 导码模式、非导码模式 商家券):[{activityId: '20220426008260043360152XXXX',outBizNo: '20220xxxx',// 导码模式商家券},{activityId: '20220426008260043360152XXXX',outBizNo: '20220xxxx',},{ activityId: '20220426008260043360152XXXX',outBizNo: '20220xxxx',voucherCode: '2022xxxxxxx',//非导码模式商家券}] |
senderMerchantId | string | 否 | 发放者商户 号。注意:投放券的小程序 APPID、发放商户号 senderMerchantId 要和制券方或者是券的归属方对应的 PID 保持一致。 |
dialogBtnType | number | 否 | 弹窗按钮的类型,默认值为 1。按钮状态有可能为 重新领取,由插件内部控制,使用者不感知;券领取全部失败时仍为 我知道了。显示按钮文本为 我知道了,点击关闭弹窗。显示按钮文本为 立即使用,在用户点击的时候触发 onUseImmediately 事件并关闭弹窗。 |
dialogBtnStyle | object | 否 | 弹窗按钮的样式,可以设置 color、borderColor、backgroundColor 三种样式值。示例:{color: '#000',borderColor: 'yellowgreen',backgroundColor: 'yellowgreen'} |
zIndex | number | 否 | 弹窗的层级。 |
boxBounding | object | 否 | 影响 fixed 定位的祖先元素的边界信息。即该祖先元素距离视口(viewport)的左边距(left)和底部边距(bottom)。示例:{left: 30,bottom: 500,} |
params 参数说明
参数名称 | 是否必填 | 参数说明 |
---|---|---|
activityId | 是 | 活动 ID,创建商家券活动成功后获取。 |
outBizNo | 是 | 发券的唯一幂等 ID,商家自定义, 需保证唯一性。 |
voucherCode | 否 | 商家券 非导码模式 必填。发券的唯一标识,商家自定义,需保证唯一性。 |
boxbounding 计算方式

// page.axml
<view>
<view class="text-button" onTap="onShowCenterBox">居中弹窗</view>
<view class="center-box-mask" a:if="{ {centerBoxVisible}}"></view>
<view class="center-box" a:if="{ {centerBoxVisible}}">
<get-coupon
onGetCouponSuccess="onGetCouponSuccess"
onClose="onClose"
params="{ {params}}"
boxBounding="{ {centerBoxBounding}}"
>
<view class="text-button">领取优惠券</view>
</get-coupon>
</view>
</view>
Page({
data: {
centerBoxVisible: false,
centerBoxBounding: {
left: 0,
bottom: 0,
},
},
onShowCenterBox() {
this.setData({
centerBoxVisible: true,
});
// 取得 viewportRect 和「居中弹窗」的 bounding 信息
my.createSelectorQuery()
.selectAll('.center-box')
.boundingClientRect()
.selectViewport()
.boundingClientRect()
.exec((result) => {
const centerBoxRect = result[0][0];
const viewportRect = result[1];
this.setData({
centerBoxBounding: {
left: centerBoxRect.left,
// bottom 值为两值相减
bottom: viewportRect.height - centerBoxRect.bottom,
},
});
});
}
})
返回处理 - onGetCouponSuccess
onGetCouponSuccess(resultList) {
console.log(resultList)
}
字段 | 类型 | 是否必填 | 描述 |
---|---|---|---|
activityId | String | 是 | 活动 ID。 |
outBizNo | String | 是 | 发券的唯一幂等 ID。 |
voucherCode | String | 是 | 券的唯一标识。商家券会返回 voucherCode,支付券该字段为空。 |
voucherId | String | 是 | 券 ID。该券 ID 只有在支付券的时候才使用,商家券无需感知该字段。 |
code | String | 是 | 领券结果,见下列表。 |
领券结果 | 描述 | 解决方案 |
---|---|---|
SUCCESS | 成功 | - |
ACTIVITY_NOT_START | 活动未开始 | - |
COUNT_OVER_LIMIT | 领取次数超过限制 | - |
BUDGET_NOT_ENOUGH | 预算不足 | - |
OTHER | 其他原因 | 出现 OTHER 原因请咨询支付宝技术支持。 |
返回处理 - onGetCouponFail
onGetCouponFail(result) {
console.log(result)
}
字段 | 类型 | 是否必填 | 描述 |
---|---|---|---|
errorCodeName | String | 是 | 错误码,可查看下方列表。 |
errorMsg | String | 是 | 错误描述。 |
错误码 | 描述 | 解决方案 |
---|---|---|
REQUEST_PARAM_ILLEGAL | 请求参数非法。 | - |
INTEGRATION_ERROR | 下游服务调用异常。 | - |
MISC_ERROR | 杂类错误,如网络断开、传参错误等。 | 请检查网络、前端传参等信息。 |
UNKNOWN_EXCEPTION | 未知异常。 | 请咨询支付宝技术支持。 |
MISC_ERROR
错误,可以打开调试器 > AppLog > 找到对应的 rpc 请求,查看具体原因。
修改于 2023-11-22 05:59:11