卡券-小程序打通
# 目录
1.小程序内领取卡券
2.小程序内查看卡券
3.小程序开卡组件
4.卡券内跳转小程序
# 小程序内领取卡券
# 场景介绍
商家在小程序内进行营销活动时,可以将卡券作为奖品、优惠兑换凭证发放给用户,用户领取到卡包后可以快捷地出示使用并进行核销。
同时,某些票务类的小程序也可以将用户购买后的票券供用户添加至卡包,方便用户出示使用。
# 步骤
- 开发者须有一个有卡券权限的公众号和认证后的小程序账号;
- 开发者须申请一个开放平台账号,并将小程序和公众号绑定在同一个开放平台账号下,关于开放平台的介绍请参照:微信开放平台;
- 阅读卡券接口说明和创建卡券接口,创建卡券并获得card_id;
- 在小程序内调用wx.addcard接口并处理领取成功的回调;
- 在第三步中获取到的card_id、code(加密code)请求解码code接口获取真实的code;
- 记录用户小程序内的openid、用户领取的code以及card_id;
- 处理卡券领取事件,记录用户在公众号内的openid、以及用户领取的code以及card_id。
# 接口说明
wx.addcard接口请参考:wx.addcard
# 注意事项
- wx.addcard接口中涉及的签名中的api_ticket须传入创建该卡券公众号获取到的ticket;
- 用户领取卡券后,会有领取卡券事件推送至开发者服务器,开发者须进行处理,详细请见卡券事件通知;
- 开发者可以通过outer_str判断用户的领券来源;
- 该功能仅支持1.1.0版本以及以上的基础库版本,小程序内须做版本判断并对低版本进行兼容。
# 小程序内查看卡券
# 场景介绍
开发者可以通过调用该接口允许用户在小程序内查看、出示自己的微信卡券。
# 步骤
1.开发者须在用户进入小程序时,获取用户已经领取到的卡券的card_id和code(真实code); 2.调用wx.openCard打开用户某张卡券供用户查看、使用。
# 接口说明
wx.openCard接口请参考:wx.openCard
# 注意事项
- 目前卡券领取后会自动返回小程序页面,若开发者鼓励用户领卡后继续在卡面上进行下一步操作,须在wx.addcard的函数回调内调用wx.opencard;
- wx.addcard成功后返回的参数中code为加密字段,须解密后才能调用wx.opencard,详情请见解码code接口;
# 小程序开卡组件
# 场景介绍
开发者可以在小程序里面开发自己的会员模块,并将开卡环节嵌入其中,微信卡券为小程序内会员开卡提供了“开卡组件功能”。
用户在小程序内进入开卡组件时,可以快速拉取到用户之前在微信开卡填写的资料并预填,用户可以做到“一键开卡”。
对商户而言,开卡组件集“开卡注册”和“添加至卡包”于一体,快捷开卡的同时可以省掉手机验证等环节,提高开卡率。
目前开卡组件分为跳转型开卡组件和非跳转型开卡组件。
注意:
- 小程序调用开卡组件须公众号具有微信卡券功能,详情请见:微信卡券说明。
- 开发者须先了解卡券开发的基本知识后调用,详情请见:微信卡券接口说明。
# 步骤
跳转型一键开卡步骤
- 创建一张会员卡会员卡,会员卡的激活方式选择“wx_activate":true,"wx_activate_after_submit" : true,并在activate_app_brand_user_name、activate_app_brand_pass传入激活小程序页面的相关信息,并获得card_id,详情见:创建会员卡接口;
- 设置用户开卡时填写的开卡字段,分必填和选填,详情见:设置开卡字段接口
- 获取开卡组件所需的参数;
- 判断新老用户、客户端版本决定是否要调用开卡插件接口;
- 调用开卡插件供用户开卡,并处理开卡插件的回调;
- 获取用户开卡资料并激活用户的会员卡;
具体流程如图:
非跳转型一键开卡步骤
- 创建一张会员卡会员卡,会员卡的激活方式选择“wx_activate":true,"wx_activate_after_submit" : false,并获得card_id,详情见: 创建会员卡接口
- 设置用户开卡时填写的开卡字段,分必填和选填,详情见:设置开卡字段接口
- 获取开卡组件所需的参数;
- 判断新老用户、客户端版本决定是否要调用开卡插件接口;
- 调用开卡插件供用户开卡,并处理开卡插件的回调;
- 获取用户开卡资料;
# 接口说明
# 接口1:获取开卡插件参数
接口说明
开发者可以通过该接口获取到调用开卡插件所需的参数。
请求参数说明
{ "card_id" : "pbLatji6o5g7hJh8Otuvux4y1ty0", "outer_str" : "123" }
{ "errcode": 0, "errmsg": "ok", "url": "https://mp.weixin.qq.com/bizmall/activatemembercard? action=preshow&&enxxxxxxx=MjM5Mzc0OTEwMA%3D%3D#wechat_redirect" }
返回参数说明
注意事项 1.本接口返回的参数须原封不动地填入开卡插件接口,须做urldecode操作;
# 接口2:小程序内打开开卡插件的接口
接口说明
1.开发者通过该接口可以在自己的小程序内打开开卡插件;
2.该接口为小程序接口,开发者须先了解小程序接口的调用方法:详情见:卡券事件通知;
3.基础库 1.3.0 开始支持,低版本需做兼容处理
4.iOS 微信客户端 6.5.9 版本开始支持,Android 客户端即将在 6.5.10 版本开始支持,请先使用 iOS 客户端进行调试
打开同一公众号下关联的另一个小程序。
OBJECT参数说明:
success返回参数说明:
参数名 类型 说明 errMsg String 调用结果
示例代码:
wx.navigateToMiniProgram({ appId: ‘wxeb490c6f9b154ef9’, // 固定为此appid,不可改动 extraData: data, // 包括encrypt_card_id outer_str biz三个字段,须从step3中获得的链接中获取参数 success: function() { }, fail: function() { }, complete: function() { } })
返回说明
在App.onShow里判断从会员开卡小程序返回的数据data
- 判断data.referrerInfo.appId是否为开卡小程序appId 'wxeb490c6f9b154ef9',如果不是则中止判断
- 判断是否有data.referrerInfo.extraData是否有数据,如果没有,表示用户未激活直接左滑/点返回键返回,或者用户已经激活
- 若用户激活成功,可以从data.referrerInfo.extraData中获取activate_ticket card_id code参数用于下一步操作
Bug & Tip tip: 在开发者工具上调用此 API 并不会真实的跳转到另外的小程序,但是开发者工具会校验本次调用跳转是否成功 tip: 开发者工具上支持"被跳转的小程序处理接收参数"的调试
# 接口3:获取用户开卡时提交的信息(跳转型开卡组件)
接口说明
开发者可以通过该接口获取到用户开卡时填写的字段值。
请求参数说明
{ "activate_ticket" : "abcdefg" }
{
"errcode": 0,
"errmsg": "ok",
"info": {
"common_field_list": [
{
"name": "USER_FORM_INFO_FLAG_MOBILE",
"value": "15*****518"
},
{
"name": "USER_FORM_INFO_FLAG_NAME",
"value": "HK"
},
{
"name": "USER_FORM_INFO_FLAG_EDUCATION_BACKGROUND",
"value": "研究生"
}
],
"custom_field_list": []
}
}
返回参数说明
common_field_id_list,支持开发者使用以下选项类型
- 注意事项 1.本接口仅跳转型开卡组件可以调用,非跳转型的开卡组件回调中不含activate_ticket
# 接口4:获取用户开卡时提交的信息(非跳转型开卡组件)
接口说明
开发者可以通过该接口获取到用户开卡时填写的字段值。
请求参数说明
{ "card_id" : "abcdefg", "code" : "abcdefg" }
- 返回数据
{
"errcode": 0,
"errmsg": "ok",
"openid": "obLatjjwDxxxxdoGIdwNqRXw",
"nickname": "Fourier",
"membership_number": "316510891298",
"bonus": 460,
"sex": "MALE",
"user_info": {
"common_field_list": [
{
"name": "USER_FORM_INFO_FLAG_MOBILE",
"value": "1552xxxx8888"
},
{
"name": "USER_FORM_INFO_FLAG_NAME",
"value": "微信"
}
],
"custom_field_list": []
},
"user_card_status": "NORMAL"
}
common_field_id_list,支持开发者使用以下选项类型
# 接口5:激活用户领取的会员卡(跳转型开卡组件)
接口说明
开发者可以通过该接口获取到用户开卡时填写的字段值。
请求参数说明
{
"init_bonus": 100,
"init_bonus_record":"旧积分同步",
"init_balance": 200,
"membership_number": "AAA00000001",
"code": "12312313",
"card_id": "xxxx_card_id",
"background_pic_url": "https://mmbiz.qlogo.cn/mmbiz/0?wx_fmt=jpeg",
"init_custom_field_value1": "xxxxx"
}
返回数据
{
"init_bonus": 100,
"init_bonus_record":"旧积分同步",
"init_balance": 200,
"membership_number": "AAA00000001",
"code": "12312313",
"card_id": "xxxx_card_id",
"background_pic_url": "https://mmbiz.qlogo.cn/mmbiz/0?wx_fmt=jpeg",
"init_custom_field_value1": "xxxxx"
}
# 注意事项
- 新老会员判断:若用户已领取微信会员卡,开发者可以通过获取用户信息接口获取到用户的unionid,用户授权登录小程序后可以关联用户之前的会员账户;
- 新老版本判断:开发者对会员开卡须设计两套流程,iOS 6.5.9 &Android 6.5.10及其以上微信版本可以调用开卡组件,低版本须开发小程序自己的注册页面,用户注册完成后领取会员卡即可
# 卡券内跳转小程序
# 场景介绍
商户创建卡券时可以将卡、券内的服务入口设置进入小程序服务。
# 步骤
- 开发者须将小程序绑定在公众号下,绑定说明请见绑定公众号与小程序
- 创建卡券,并将卡内的cell设置小程序对应的path;
- 处理跳转小程序时获取到的信息;
# 接口说明
- 创建会员卡
{ "card": {
"card_type": "MEMBER_CARD",
"member_card": {
"base_info": {
"custom_url_name": "立即使用",
"custom_url": "http://www.qq.com",
"custom_app_brand_user_name": "gh_86a091e50ad4@app",
"custom_app_brand_pass":"API/cardPage",
"custom_url_sub_title": "6个汉字tips",
"promotion_url_name": "更多优惠",
"promotion_url": "http://www.qq.com",
"promotion_app_brand_user_name": "gh_86a091e50ad4@app",
"promotion_app_brand_pass":"API/cardPage"
}
}
}
*需调用卡券更新接口将相应小程序页面更新至对应跳转外链结构体中,原跳转H5字段保留。
- 获取跳转参数
从卡券跳转小程序后,开发者可以通过apponshow的query中或取到发起跳转的card_id、encrypt_code和用户的公众号openid,开发者须调用 解码code接口 将encrypt_code解码为真实code。